Configuring routing rules

Routing rules determine how RTB Fabric maps incoming HTTP requests to links. Each rule specifies conditions that a request must satisfy. When a request arrives at the gateway, RTB Fabric evaluates rules across all links and forwards the request to the link whose highest-priority matching rule wins.

Routing rule structure

You create routing rules using the CreateLinkRoutingRule API. Each rule consists of a numeric priority and a set of conditions. The ruleId is system-generated.

{
  "gatewayId": "rtb-gw-abc123def456",
  "linkId": "link-001",
  "priority": 1,
  "conditions": {
    "hostHeader": "bid.example.com",
    "pathPrefix": "/openrtb"
  },
  "clientToken": "unique-idempotency-token"
}

The response includes a system-generated ruleId (pattern: rule-[a-z0-9-]+) and a status field. Use the GetLinkRoutingRule API to check when the rule reaches ACTIVE status.

Supported match types

RTB Fabric supports six match types. All conditions within a single rule use AND logic — every specified condition must match for the rule to apply.

Host header exact match (hostHeader)

Matches the Host header of the incoming request against an exact hostname value.

Example:

{
  "conditions": {
    "hostHeader": "east-bid.dsp.example.com"
  }
}

This condition matches requests with Host: east-bid.dsp.example.com, Host: East-Bid.DSP.Example.com, and Host: east-bid.dsp.example.com:443.

Host header wildcard match (hostHeaderWildcard)

Matches the Host header against a wildcard pattern. The hostHeader and hostHeaderWildcard conditions are mutually exclusive — a single rule cannot contain both.

Example:

{
  "conditions": {
    "hostHeaderWildcard": "*.dsp.example.com"
  }
}

Path prefix match (pathPrefix)

Matches the URL path against a prefix value with segment-boundary awareness.

Example:

{
  "conditions": {
    "pathPrefix": "/openrtb/bid"
  }
}

Path exact match (pathExact)

Matches the URL path using a byte-for-byte comparison. The pathPrefix and pathExact conditions are mutually exclusive — a single rule cannot contain both.

Example:

{
  "conditions": {
    "pathExact": "/openrtb/bid/v2"
  }
}

Query string equals match (queryStringEquals)

Matches a specific query string key-value pair.

Example:

{
  "conditions": {
    "queryStringEquals": {
      "key": "format",
      "value": "json"
    }
  }
}

A request to /bid?format=json matches. A request to /bid?format=XML does not match (case-sensitive value comparison).

Query string exists match (queryStringExists)

Checks whether a specific query string key is present, regardless of its value.

Example:

{
  "conditions": {
    "queryStringExists": "debug"
  }
}

A request to /bid?debug=true matches. A request to /bid?debug (key present with no value) also matches. A request to /bid?Debug=true does not match (case-sensitive key).

Composite rules

All conditions within a single rule are combined with AND logic. A request must satisfy every specified condition for the rule to match.

The following rule matches requests that meet all three criteria simultaneously:

{
  "gatewayId": "rtb-gw-abc123def456",
  "linkId": "link-001",
  "priority": 10,
  "conditions": {
    "hostHeader": "bid.example.com",
    "pathPrefix": "/openrtb/bid",
    "queryStringEquals": {
      "key": "format",
      "value": "json"
    }
  },
  "clientToken": "unique-idempotency-token"
}

A request to https://bid.example.com/openrtb/bid/v2?format=json matches this rule. A request to https://bid.example.com/openrtb/bid/v2?format=xml does not match because the queryStringEquals condition fails.

Rule evaluation order

RTB Fabric evaluates routing rules globally across all links, not per-link. The evaluation follows this process:

Priority must be unique within each link. Across different links, rules may share the same priority value. If two rules from different links have the same priority and both match, the result is non-deterministic. Assign distinct priority values across all links to avoid ambiguous routing.

Example: Interleaved priorities across links

Consider two links with the following rules:

Link A (link-east) has two rules with priorities 1 and 3:

Link B (link-west) has two rules with priorities 2 and 4:

The global evaluation order is: rule-east-openrtb (1) → rule-west-openrtb (2) → rule-east-native (3) → rule-west-native (4).

A request to https://west-bid.example.com/openrtb/bid skips rule-east-openrtb (host mismatch), matches rule-west-openrtb (priority 2), and routes to link-west.

Link ID resolution chain

When a request arrives at the gateway, RTB Fabric resolves the target link using a three-step resolution chain. Rule-based routing is the final step in this chain:

RTB Fabric uses the first method that returns a result. Rule-based routing applies only when the first two methods do not resolve a link ID.

Example: Multi-partner routing

The following example demonstrates routing for a partner (AnyCompany) with multiple regional endpoints and path-based traffic segmentation.

AnyCompany operates four combinations of region and traffic type:

Rule on link 1 (link-anyco-east-openrtb):

{
  "gatewayId": "rtb-gw-abc123def456",
  "linkId": "link-anyco-east-openrtb",
  "priority": 1,
  "conditions": {
    "hostHeader": "east-bid.dsp.example.com",
    "pathPrefix": "/openrtb"
  },
  "clientToken": "token-east-openrtb"
}

Rule on link 2 (link-anyco-east-native):

{
  "gatewayId": "rtb-gw-abc123def456",
  "linkId": "link-anyco-east-native",
  "priority": 2,
  "conditions": {
    "hostHeader": "east-bid.dsp.example.com",
    "pathPrefix": "/native"
  },
  "clientToken": "token-east-native"
}

Rule on link 3 (link-anyco-west-openrtb):

{
  "gatewayId": "rtb-gw-abc123def456",
  "linkId": "link-anyco-west-openrtb",
  "priority": 3,
  "conditions": {
    "hostHeader": "west-bid.dsp.example.com",
    "pathPrefix": "/openrtb"
  },
  "clientToken": "token-west-openrtb"
}

Rule on link 4 (link-anyco-west-native):

{
  "gatewayId": "rtb-gw-abc123def456",
  "linkId": "link-anyco-west-native",
  "priority": 4,
  "conditions": {
    "hostHeader": "west-bid.dsp.example.com",
    "pathPrefix": "/native"
  },
  "clientToken": "token-west-native"
}

With this configuration:

Testing routing rules with /resolve-link

The gateway exposes a /resolve-link endpoint that evaluates your routing rules against a given URL without sending actual traffic. Use this endpoint to verify that rules are configured correctly before migrating DNS.

Request: GET /resolve-link?url=<url-encoded-value>

The url query parameter must be a fully qualified, URL-encoded URL (including scheme, host, path, and optional query string).

Responses:

Example:

curl "https://<GATEWAY_ENDPOINT>/resolve-link?url=https%3A%2F%2Fbid.example.com%2Fopenrtb%2Fbid"

A successful match returns the link_id and rule_id of the first matching rule:

{"link_id": "link-abc123", "rule_id": "rule-xyz789"}