Header-Based Routing

What Is Header-Based Routing?

Header-Based Routing lets you direct gateway requests to different upstream targets based on the values of HTTP request headers — without changing the request URL or requiring separate API keys. It is the foundation for multi-tenant routing, blue-green deployments, environment separation (production vs. staging), and feature flags for gradual rollouts.

Example scenarios:

Use Case	Header	Routes to
Multi-tenant routing	X-Tenant: acme-corp	Acme’s private LLM endpoint
Environment separation	X-Environment: staging	Staging model provider
A/B model testing	X-Experiment: gpt4	GPT-4o provider
Regional routing	X-Region: eu	EU-hosted model endpoint

Match Types

Type	Description	Example
Exact	Header value must match exactly	X-Tenant: acme-corp
Glob	Header value matches a glob pattern	X-Tenant: acme-*
Regex	Header value matches a regular expression	X-Tenant: ^(acme|globex)$

Match Modes

• AND — All header conditions in the rule set must be satisfied for this route to match.
• OR — Any single condition is sufficient to match.

How Routing Is Evaluated

1. Incoming request arrives with its headers.
2. AgentWatch evaluates header routing rules in order.
3. The first rule whose conditions match (AND/OR) wins; the request is forwarded to that rule’s target.
4. If no header rule matches, the request falls through to the default route target.

Configuration Example

{
  "route": "/v1/chat/completions",
  "headerRouting": {
    "mode": "AND",
    "rules": [
      { "header": "X-Tenant", "match": "exact", "value": "acme-corp" },
      { "header": "X-Environment", "match": "glob", "value": "prod-*" }
    ],
    "target": "https://acme-prod.internal.company.com"
  }
}

This forwards any request that has both X-Tenant: acme-corp AND X-Environment starting with prod- to Acme’s production endpoint.

Step-by-Step: Setting Up Header-Based Routing

1. Navigate to Settings → Gateway Routes.
2. Open or create a gateway route.
3. In the Advanced section, enable Header Routing.
4. Click Add Rule and fill in:
   • Header Name (e.g. X-Tenant)
   • Match Type (exact, glob, or regex)
   • Value (the pattern to match)
   • Target URL (where to forward matching requests)
5. Set Match Mode to AND or OR.
6. Save. The rule takes effect immediately.

Relationship to Tenant Routing Rules

Header-based routing (this section) operates at the gateway route level — it directs traffic to different upstream hosts. Tenant Routing Rules (section 7.12) operate at the request processing level — they modify, enrich, or redirect request content before sending it to the LLM. Both can be used together.