Skip to content

Create a rule via API

Use the Rulesets API to create origin rules via API.

Basic rule settings

When creating an origin rule via API, make sure you:

  • Set the rule action to route.
  • Define the parameters in the action_parameters field according to the type of origin override.
  • Deploy the rule to the http_request_origin phase at the zone level.

Procedure

Follow this workflow to create an origin rule for a given zone via API:

  1. Use the List zone rulesets operation to check if there is already a ruleset for the http_request_origin phase at the zone level.

  2. If the phase ruleset does not exist, create it using the Create a zone ruleset operation. In the new ruleset properties, set the following values:

    • kind: zone
    • phase: http_request_origin
  3. Use the Update a zone ruleset operation to add an origin rule to the list of ruleset rules. Alternatively, include the rule in the Create a zone ruleset request mentioned in the previous step.

Make sure your API token has the required permissions to perform the API operations.

Example requests

Example: Add a rule that overrides the HTTP Host header

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single origin rule — overriding the HTTP Host header — using the Update a zone ruleset operation. The response will contain the complete definition of the ruleset you updated.

Terminal window
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"rules": [
{
"expression": "http.request.uri.query contains \"/eu/\"",
"description": "My first origin rule",
"action": "route",
"action_parameters": {
"host_header": "eu_server.example.net"
}
}
]
}'
{
"result": {
"id": "<RULESET_ID>",
"name": "Origin Rules ruleset",
"description": "Zone-level ruleset that will execute origin rules.",
"kind": "zone",
"version": "2",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "route",
"action_parameters": {
"host_header": "eu_server.example.net"
},
"expression": "http.request.uri.query contains \"/eu/\"",
"description": "My first origin rule",
"last_updated": "2022-06-02T14:42:04.219025Z",
"ref": "<RULE_REF>"
}
],
"last_updated": "2022-06-02T14:42:04.219025Z",
"phase": "http_request_origin"
},
"success": true,
"errors": [],
"messages": []
}

Example: Add a rule that overrides the SNI value of incoming requests

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single origin rule — overriding the SNI value of incoming requests addressed at admin.example.com — using the Update a zone ruleset operation.

Terminal window
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"rules": [
{
"expression": "http.host eq \"admin.example.com\"",
"description": "SNI Override for the admin area",
"action": "route",
"action_parameters": {
"sni": {
"value": "sni.example.com"
}
}
}
]
}'

Example: Add a rule that overrides the resolved DNS record and the Host header of incoming requests

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single origin rule — overriding the resolved DNS record and the Host header of incoming requests — using the Update a zone ruleset operation. The response will contain the complete definition of the ruleset you updated.

Terminal window
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"rules": [
{
"expression": "starts_with(http.request.uri.path, \"/hr-app/\")",
"description": "Origin rule for the company HR application",
"action": "route",
"action_parameters": {
"host_header": "hr-server.example.com",
"origin": {
"host": "hr-server.example.com"
}
}
}
]
}'
{
"result": {
"id": "<RULESET_ID>",
"name": "Origin Rules ruleset",
"description": "Zone-level ruleset that will execute origin rules.",
"kind": "zone",
"version": "2",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "route",
"action_parameters": {
"host_header": "hr-server.example.com",
"origin": {
"host": "hr-server.example.com"
}
},
"expression": "starts_with(http.request.uri.path, \"/hr-app/\")",
"description": "Origin rule for the company HR application",
"last_updated": "2022-06-03T14:42:04.219025Z",
"ref": "<RULE_REF>"
}
],
"last_updated": "2022-06-03T14:42:04.219025Z",
"phase": "http_request_origin"
},
"success": true,
"errors": [],
"messages": []
}

Example: Add a rule that overrides the port of incoming requests

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single origin rule — overriding the port of incoming requests — using the Update a zone ruleset operation. The response will contain the complete definition of the ruleset you updated.

Terminal window
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"rules": [
{
"expression": "starts_with(http.request.uri.path, \"/team/calendar/\")",
"description": "Origin rule for the team calendar application",
"action": "route",
"action_parameters": {
"origin": {
"port": 9000
}
}
}
]
}'
{
"result": {
"id": "<RULESET_ID>",
"name": "Origin Rules ruleset",
"description": "Zone-level ruleset that will execute origin rules.",
"kind": "zone",
"version": "2",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "route",
"action_parameters": {
"origin": {
"port": 9000
}
},
"expression": "starts_with(http.request.uri.path, \"/team/calendar/\")",
"description": "Origin rule for the team calendar application",
"last_updated": "2022-06-03T14:42:04.219025Z",
"ref": "<RULE_REF>"
}
],
"last_updated": "2022-06-03T14:42:04.219025Z",
"phase": "http_request_origin"
},
"success": true,
"errors": [],
"messages": []
}

Required API token permissions

The API token used in API requests to manage origin rules must have at least the following permission:

  • Origin > Edit