Rules

On this page, we'll dive into the different rule endpoints you can use to manage domain rules programmatically. We'll look at how to query, create, update, and delete rules, as well as how to reorder them.

The rule model

The rule model contains all the information about your domain rules. Rules allow you to define custom behavior for your domain based on request patterns. Each rule consists of matchers (conditions) and handlers (actions). Rules are evaluated in order based on their position, and the first matching rule is applied.

Properties

  • Name
    uuid
    Type
    string
    Description

    Unique identifier for the rule.

  • Name
    name
    Type
    string
    Description

    Human-readable name for the rule.

  • Name
    active
    Type
    boolean
    Description

    Whether the rule is currently active.

  • Name
    position
    Type
    integer
    Description

    Position of the rule in the evaluation order (lower numbers are evaluated first).

  • Name
    matchers
    Type
    array
    Description

    An array of conditions that determine when the rule should be applied. Matchers define the criteria for matching incoming requests based on path, HTTP method, headers, or query parameters. Multiple matchers are combined with AND logic, meaning all conditions must be met for the rule to match.

  • Name
    handlers
    Type
    array
    Description

    An array of actions to execute when the rule matches. Handlers define what happens to the request or response when all matchers are satisfied. This can include rewriting URLs, returning static responses, modifying response headers, or replacing content in the response body.

  • Name
    custom_domain_uuid
    Type
    string
    Description

    UUID of the custom domain this rule belongs to.

  • Name
    account_uuid
    Type
    string
    Description

    UUID of the account that owns this rule.

  • Name
    created_at
    Type
    timestamp
    Description

    The date and time when the rule was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    The date and time when the rule was last updated.

Matcher Types

Rules can include the following matcher types:

Path Matcher

Match requests based on the URL path component.

  • Name
    type
    Type
    string
    Description

    Must be set to "path".

  • Name
    value
    Type
    string
    Description

    The path value to match against.

  • Name
    operator
    Type
    string
    Description

    The comparison operator to use. Possible values:

    • is - Exact path match
    • is_not - Path does not match exactly
    • starts_with - Path starts with the value
    • ends_with - Path ends with the value
    • contains - Path contains the value
    • does_not_contain - Path does not contain the value
    • has_any_value - Path exists (any value)
    • is_unknown - Path does not exist
{
  "type": "path",
  "value": "/blog",
  "operator": "starts_with"
}

Method Matcher

Match requests based on the HTTP method (GET, POST, PUT, DELETE, etc.).

  • Name
    type
    Type
    string
    Description

    Must be set to "method".

  • Name
    value
    Type
    string
    Description

    The HTTP method to match against (e.g., "GET", "POST").

  • Name
    operator
    Type
    string
    Description

    The comparison operator to use. Possible values:

    • is - Method matches exactly
    • is_not - Method does not match
    • has_any_value - Any method
    • is_unknown - No method (rare/impossible in HTTP)
{
  "type": "method",
  "value": "POST",
  "operator": "is"
}

Header Matcher

Match requests based on the presence or value of HTTP headers.

  • Name
    type
    Type
    string
    Description

    Must be set to "header".

  • Name
    header_params
    Type
    array
    Description

    Array of header parameters to match against.

Each header parameter has the following properties:

  • Name
    name
    Type
    string
    Description

    The name of the header.

  • Name
    value
    Type
    string
    Description

    The value to match against.

  • Name
    operator
    Type
    string
    Description

    The comparison operator to use. Possible values:

    • is - Header value matches exactly
    • is_not - Header value does not match
    • starts_with - Header value starts with the value
    • ends_with - Header value ends with the value
    • contains - Header value contains the value
    • does_not_contain - Header value does not contain the value
    • has_any_value - Header exists (any value)
    • is_unknown - Header does not exist
{
  "type": "header",
  "header_params": [
    {
      "name": "User-Agent",
      "value": "Mozilla",
      "operator": "contains"
    },
    {
      "name": "Accept-Language",
      "value": "en",
      "operator": "starts_with"
    }
  ]
}

Query Matcher

Match requests based on query string parameters in the URL.

  • Name
    type
    Type
    string
    Description

    Must be set to "query".

  • Name
    query_params
    Type
    array
    Description

    Array of query parameters to match against.

Each query parameter has the following properties:

  • Name
    key
    Type
    string
    Description

    The name of the query parameter.

  • Name
    value
    Type
    string
    Description

    The value to match against.

  • Name
    operator
    Type
    string
    Description

    The comparison operator to use. Possible values:

    • is - Query parameter value matches exactly
    • is_not - Query parameter value does not match
    • starts_with - Query parameter value starts with the value
    • ends_with - Query parameter value ends with the value
    • contains - Query parameter value contains the value
    • does_not_contain - Query parameter value does not contain the value
    • has_any_value - Query parameter exists (any value)
    • is_unknown - Query parameter does not exist
{
  "type": "query",
  "query_params": [
    {
      "key": "version",
      "value": "v2",
      "operator": "is"
    },
    {
      "key": "debug",
      "operator": "has_any_value"
    }
  ]
}

Handler Types

Rules can include the following handler types:

Static Response Handler

Return a custom HTTP response without forwarding the request to the upstream server.

  • Name
    type
    Type
    string
    Description

    Must be set to "static_response".

  • Name
    status_code
    Type
    integer
    Description

    The HTTP status code to return.

  • Name
    body
    Type
    string
    Description

    The response body to return.

{
  "type": "static_response",
  "status_code": 200,
  "body": "<!DOCTYPE html><html><body><h1>Hello World!</h1></body></html>"
}

Rewrite Handler

Modify the request URL before forwarding it to the upstream server.

  • Name
    type
    Type
    string
    Description

    Must be set to "rewrite".

  • Name
    uri
    Type
    string
    Description

    The URI to rewrite the request to. You can use placeholders in your rewrite URI (see below).

Rewrite URI Placeholders

The following placeholders can be used in the rewrite URI:

{http.request.uri} The full request URI
{http.request.uri.path} The path component (e.g. /old-path)
{http.request.uri.path.dir} The directory (excluding the filename)
{http.request.uri.path.file} The filename (excluding the directory)
{http.request.uri.query} The query string (without ?)
{
  "type": "rewrite",
  "uri": "https://blog.example.com{http.request.uri.path}?source=proxy&{http.request.uri.query}"
}

Replace Response Handler

Modify the response body content by replacing text patterns.

  • Name
    type
    Type
    string
    Description

    Must be set to "replace_response".

  • Name
    replacements
    Type
    array
    Description

    Array of replacements to apply to the response body.

Each replacement has the following properties:

  • Name
    search
    Type
    string
    Description

    The string to search for.

  • Name
    replace
    Type
    string
    Description

    The string to replace matches with.

{
  "type": "replace_response",
  "replacements": [
    {
      "search": "example.com",
      "replace": "customdomain.com"
    },
    {
      "search": "Original Content",
      "replace": "Modified Content"
    }
  ]
}

Set Response Header Handler

Add or modify headers in the HTTP response.

  • Name
    type
    Type
    string
    Description

    Must be set to "set_response_header".

  • Name
    headers
    Type
    array
    Description

    Array of headers to set in the response.

Each header has the following properties:

  • Name
    name
    Type
    string
    Description

    The name of the header.

  • Name
    value
    Type
    string
    Description

    The value to set for the header.

{
  "type": "set_response_header",
  "headers": [
    {
      "name": "X-Custom-Header",
      "value": "custom-value"
    },
    {
      "name": "Cache-Control",
      "value": "max-age=3600"
    }
  ]
}

Delete Response Header Handler

Remove specific headers from the HTTP response.

  • Name
    type
    Type
    string
    Description

    Must be set to "delete_response_header".

  • Name
    headers
    Type
    array
    Description

    Array of headers to delete from the response.

Each header has the following properties:

  • Name
    name
    Type
    string
    Description

    The name of the header to delete.

{
  "type": "delete_response_header",
  "headers": [
    {
      "name": "Server"
    },
    {
      "name": "X-Powered-By"
    }
  ]
}

Redirect Handler

Redirect the request to a different URL with a specified HTTP status code.

  • Name
    type
    Type
    string
    Description

    Must be set to "redirect".

  • Name
    location
    Type
    string
    Description

    The URL to redirect to. Must be a valid URL starting with http:// or https://. You can use placeholders in your redirect location (see below).

  • Name
    status_code
    Type
    integer
    Description

    The HTTP status code to use for the redirect. Must be either 301 (permanent) or 302 (temporary).

The following placeholders can be used in the Redirect Location URI:

{http.request.uri} The full request URI
{http.request.uri.path} The path component (e.g. /old-path)
{http.request.uri.path.dir} The directory (excluding the filename)
{http.request.uri.path.file} The filename (excluding the directory)
{http.request.uri.query} The query string (without ?)
{
  "type": "redirect",
  "location": "https://new-location.example.com{http.request.uri.path}?source=redirect&{http.request.uri.query}",
  "status_code": 301
}
GET
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules

List Rules

This endpoint allows you to retrieve a paginated list of all rules for a custom domain.

Optional attributes

  • Name
    active
    Type
    boolean
    Description

    Filter rules by active status.

  • Name
    sort
    Type
    string
    Description

    Field to sort by (e.g., position, name, created_at).

  • Name
    direction
    Type
    string
    Description

    Sort direction (asc or desc).

  • Name
    page
    Type
    integer
    Description

    Page number for pagination.

  • Name
    items
    Type
    integer
    Description

    Number of items per page.

Request

GET
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules
curl -G https://app.saascustomdomains.com/api/v1/accounts/acc_123abc/upstreams/upstream_456def/custom_domains/domain_789ghi/rules \
  -H "Authorization: Bearer {token}" \
  -d active=true

Response

{
  "data": [
    {
      "uuid": "rule_01234abc",
      "name": "Redirect to blog",
      "active": true,
      "position": 1,
      "matchers": [
        {
          "type": "path",
          "value": "/blog",
          "operator": "starts_with"
        }
      ],
      "handlers": [
        {
          "type": "rewrite",
          "uri": "https://blog.example.com{path}"
        }
      ],
      "custom_domain_uuid": "domain_789ghi",
      "account_uuid": "acc_123abc",
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z"
    },
    {
      "uuid": "rule_56789def",
      // ...
    }
  ],
  "pagination": {
    "page": 1,
    "count": 10,
    "items": 25,
    "pages": 1
  }
}
GET
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/:uuid

Get a Rule

This endpoint allows you to retrieve a single rule by its UUID.

Request

GET
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/:uuid
curl https://app.saascustomdomains.com/api/v1/accounts/acc_123abc/upstreams/upstream_456def/custom_domains/domain_789ghi/rules/rule_01234abc \
  -H "Authorization: Bearer {token}"

Response

{
  "uuid": "rule_01234abc",
  "name": "Redirect to blog",
  "active": true,
  "position": 1,
  "matchers": [
    {
      "type": "path",
      "value": "/blog",
      "operator": "starts_with"
    }
  ],
  "handlers": [
    {
      "type": "rewrite",
      "uri": "https://blog.example.com{path}"
    }
  ],
  "custom_domain_uuid": "domain_789ghi",
  "account_uuid": "acc_123abc",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}
POST
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules

Create a Rule

This endpoint allows you to create a new rule for a custom domain. The rule will be assigned the next available position.

Required attributes

  • Name
    name
    Type
    string
    Description

    Human-readable name for the rule.

  • Name
    matchers
    Type
    array
    Description

    At least one matcher must be provided.

  • Name
    handlers
    Type
    array
    Description

    At least one handler must be provided.

Optional attributes

  • Name
    active
    Type
    boolean
    Description

    Whether the rule is active. Default is true.

Request

POST
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules
curl https://app.saascustomdomains.com/api/v1/accounts/acc_123abc/upstreams/upstream_456def/custom_domains/domain_789ghi/rules \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redirect to blog",
    "active": true,
    "matchers": [
      {
        "type": "path",
        "value": "/blog",
        "operator": "starts_with"
      }
    ],
    "handlers": [
      {
        "type": "rewrite",
        "uri": "https://blog.example.com{path}"
      }
    ]
  }'

Response

{
  "uuid": "rule_01234abc",
  "name": "Redirect to blog",
  "active": true,
  "position": 1,
  "matchers": [
    {
      "type": "path",
      "value": "/blog",
      "operator": "starts_with"
    }
  ],
  "handlers": [
    {
      "type": "rewrite",
      "uri": "https://blog.example.com{path}"
    }
  ],
  "custom_domain_uuid": "domain_789ghi",
  "account_uuid": "acc_123abc",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}
PATCH
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/:uuid

Update a Rule

This endpoint allows you to update an existing rule.

Optional attributes

  • Name
    name
    Type
    string
    Description

    Human-readable name for the rule.

  • Name
    active
    Type
    boolean
    Description

    Whether the rule is active.

  • Name
    matchers
    Type
    array
    Description

    Conditions that determine when the rule should be applied.

  • Name
    handlers
    Type
    array
    Description

    Actions to take when the rule matches.

Request

PATCH
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/:uuid
curl -X PATCH https://app.saascustomdomains.com/api/v1/accounts/acc_123abc/upstreams/upstream_456def/custom_domains/domain_789ghi/rules/rule_01234abc \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated rule name",
    "active": false
  }'

Response

{
  "uuid": "rule_01234abc",
  "name": "Updated rule name",
  "active": false,
  "position": 1,
  "matchers": [
    {
      "type": "path",
      "value": "/blog",
      "operator": "starts_with"
    }
  ],
  "handlers": [
    {
      "type": "rewrite",
      "uri": "https://blog.example.com{path}"
    }
  ],
  "custom_domain_uuid": "domain_789ghi",
  "account_uuid": "acc_123abc",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:30:00Z"
}
DELETE
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/:uuid

Delete a Rule

This endpoint allows you to delete a rule.

Request

DELETE
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/:uuid
curl -X DELETE https://app.saascustomdomains.com/api/v1/accounts/acc_123abc/upstreams/upstream_456def/custom_domains/domain_789ghi/rules/rule_01234abc \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Rule rule_01234abc (Redirect to blog) deleted."
}
PATCH
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/update_positions

Update Rule Positions

This endpoint allows you to update the positions of multiple rules at once.

Required attributes

  • Name
    rule_positions
    Type
    array
    Description

    Array of rule position updates.

Each rule position update has the following properties:

  • Name
    uuid
    Type
    string
    Description

    The UUID of the rule.

  • Name
    position
    Type
    integer
    Description

    The new position for the rule.

Request

PATCH
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:custom_domain_uuid/rules/update_positions
curl -X PATCH https://app.saascustomdomains.com/api/v1/accounts/acc_123abc/upstreams/upstream_456def/custom_domains/domain_789ghi/rules/update_positions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_positions": [
      {
        "uuid": "rule_01234abc",
        "position": 2
      },
      {
        "uuid": "rule_56789def",
        "position": 1
      }
    ]
  }'

Response

{
  "message": "Rule positions updated successfully."
}

Error Responses

When an error occurs, the API will return an appropriate HTTP status code and a JSON response with error details:

{
  "error": "Rule not found.",
  "error_code": "not_found"
}

Common error codes:

  • not_found - The requested resource was not found
  • feature_not_enabled - The domain rules feature is not enabled for this account
  • invalid_position - The requested position is invalid
  • Various validation errors (e.g., name_blank, matchers_invalid)