Skip to main content
This endpoint allows you to create various types of rules in Requestly, such as Redirect, Cancel, Replace, Headers, User-Agent, Query Param, Modify Request, Modify Response, and Delay. Each rule has a specific structure and parameters.

​
Endpoint

  • Method: POST
  • URL: https://api2.requestly.io/v1/rules

​
Request Structure

​
Body Parameters

NameTypeRequiredDefaultDescription
namestringYesName of the rule.
descriptionstringNoDescription of the rule.
objectTypestringYesruleType of the object. For this endpoint, it is always rule.
ruleTypestringYesType of the rule. Possible values are: Redirect, Cancel, Replace, Headers, UserAgent, QueryParam, Request, Response, Delay.
statusstringNoActiveStatus of the rule, either Active or Inactive.
pairsarray of objectsYesList of key-value pair objects that define the specific conditions and actions for the rule. The structure and details of each pair vary based on the rule type.
groupIdstringNoThe ID of the group the rule belongs to. If omitted, the rule is ungrouped.

​
cURL Request

curl --request POST \
     --url https://api2.requestly.io/v1/rules \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: your_api_key' \
     --data '
{
  "objectType": "rule",
  "ruleType": "Redirect",
  "status": "Inactive",
  "pairs": [
    {
      "destinationType": "url",
      "source": {
        "value": "https://www.google.com/",
        "operator": "Equals",
        "key": "Url"
      },
      "destination": "https://www.bing.com/"
    }
  ],
  "name": "Redirect to Bing"
}
'

​
Response

{
  "success": true,
  "data": {
    "id": "Redirect_wi3uj",
    "creationDate": 1736060959798,
    "modificationDate": 1736060959798,
    "createdBy": "IUAGkRiEx6XI0B6qCc82qbwroKX2",
    "lastModifiedBy": "IUAGkRiEx6XI0B6qCc82qbwroKX2",
    "name": "Redirect to Bing",
    "description": "",
    "ruleType": "Redirect",
    "objectType": "rule",
    "pairs": [
      {
        "destinationType": "url",
        "source": {
          "value": "https://www.google.com/",
          "operator": "Equals",
          "key": "Url"
        },
        "destination": "https://www.bing.com/",
        "id": "jnc6s"
      }
    ],
    "groupId": "",
    "status": "Inactive",
    "isSample": false,
    "isFavourite": false,
    "schemaVersion": "3.0.0",
    "extensionRules": [
      {
        "action": {
          "type": "redirect",
          "redirect": {
            "url": "https://www.bing.com/"
          }
        },
        "condition": {
          "urlFilter": "|https://www.google.com/|",
          "isUrlFilterCaseSensitive": true,
          "excludedInitiatorDomains": [
            "requestly.io"
          ],
          "excludedRequestDomains": [
            "requestly.io"
          ]
        }
      }
    ],
    "currentOwnerId": "IUAGkRiEx6XI0B6qCc82qbwroKX2"
  }
}

​
Rule Type Details

Each rule type has a unique structure for its pairs of objects. The schemas for each rule type are detailed below:

​
Common Source Schema

The source object is consistent across all rule types. It has the following structure:
PropertyTypeRequiredDescription
keystringYesThe key for the source (e.g., url, host, path).
operatorstringYesThe operator for matching (Equals, Contains, Matches, Wildcard_Matches).
valuestringYesThe value to match against.
filtersarrayNoOptional filters for more accurate targeting.

​
Redirect Rule

  • ruleType: Redirect
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching (see common source schema).
destinationTypestringYesType of the destination (ubelowrl, map_local, or mock_or_file_picker).
destinationstringYesThe destination URL value.

​
Cancel Rule

  • ruleType: Cancel
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching.

​
Replace Rule

  • ruleType: Replace
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching.
fromstringYesThe target string to replace.
tostringYesThe replacement value.

​
Headers Rule

  • ruleType: Headers
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching.
modificationsarrayYesList of header modifications (see below).
Header Modification Object:
PropertyTypeRequiredDescription
headerstringYesThe name of the header to modify.
typestringYesModification type (Add, Remove, or Modify).
valuestringNoThe value to set for the header (required for Add and Modify).

​
User-Agent Rule

  • ruleType: UserAgent
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching.
userAgentstringYesThe User-Agent string to set.

​
Query Param Rule

  • ruleType: QueryParam
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching.
modificationsarrayYesArray of query parameter modifications (see below).
Query Param Modification Object:
PropertyTypeRequiredDescription
paramstringYesThe name of the query parameter to modify.
typestringYesModification type (Add, Remove, or Remove All).
valuestringNoThe value to set (required for Add and Modify).

​
Modify Request Rule

  • ruleType: Request
  • pairs schema:
PropertyTypeRequiredDescription
typestringYesType of request modification (code or static).
valuestringYesThe request value or code.

​
Modify Response Rule

  • ruleType: Response
  • pairs schema:
PropertyTypeRequiredDescription
typestringYesType of response modification (code or static).
valuestringYesThe response value or status code.
serveWithoutRequestbooleanNoWhether to serve the response directly from Requestly.

​
Delay Rule

  • ruleType: Delay
  • pairs schema:
PropertyTypeRequiredDescription
sourceobjectYesThe source object for matching.
delaynumberYesDelay value in milliseconds.

​
Responses

Status CodeDescription
200Rule created successfully.
400Invalid rule or payload.
401Unauthorized action.
404Rule or group not found.
405Rule type update not allowed.
429Too many requests.
⌘I