Create Routing Rule
Add a routing rule to an endpoint. Rules sit between the public URL and the agents — every incoming request is evaluated against rules in priority order, and the first matching rule's target_agent_id / target_agent_tags determines which agent gets the request.
Common patterns:
- Canary deployment: route requests with
X-Canary: trueto agents taggedcanary,v2; everything else hits prod. - API split: route
/api/payments/*to a hardened payment service, the rest to the main app. - Geo routing: route by client IP CIDR to nearest-region agents.
Plan-gated: requires the endpoint_routing_rules entitlement.
Path parameters
uuid string (uuid) Req
Endpoint UUID.
Request body
name string Req
Free-form label. Used for dashboard display and audit logs.
priority int
Match order. Lower = earlier. Default
0. Pick wide gaps (10, 20, 30) so you can insert new rules without renumbering.target_agent_id string
Specific agent ID to route to. Mutually exclusive with
target_agent_tags — at least one is required.target_agent_tags string
Comma-separated agent tags. Any agent with all listed tags is eligible (load-balanced across).
enabled boolean
true = active immediately, false = saved but skipped during evaluation. Useful for staging.conditions array Req
At least one condition. Each:
•
•
•
•
•
Set
{condition_type, condition_key?, pattern, negate?}:•
path: glob/regex pattern matched against the request path. condition_key unused.•
header: condition_key = header name, pattern = value pattern.•
cookie: condition_key = cookie name, pattern = value pattern.•
client_ip: pattern = CIDR (10.0.0.0/8) or single IP.•
method: pattern = HTTP verb (GET, POST, …).Set
negate: true to invert.Response (201 Created)
The newly-created rule with assigned id; same shape as list entries.
Errors
400 Bad Request
Missing
name, empty conditions, neither target_agent_id nor target_agent_tags set, or invalid JSON.401 Unauthorized
Missing auth.
403 Forbidden
Plan doesn't include
endpoint_routing_rules entitlement.404 Not Found
Endpoint doesn't exist or doesn't belong to the calling user.
Request — canary by header
curl -X POST "https://api.ngris.com/v1/endpoints/<uuid>/routing-rules" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "canary-5pct",
"priority": 10,
"target_agent_tags": "canary,v2",
"enabled": true,
"conditions": [
{"condition_type": "header", "condition_key": "X-Canary", "pattern": "true"}
]
}'
Python — split by path
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
rule = client.routing_rules.create("<endpoint_uuid>", {
"name": "payments-isolated",
"priority": 5,
"target_agent_id": "payments-prod-1",
"enabled": True,
"conditions": [
{"condition_type": "path", "pattern": "/api/payments/*"},
],
})
print(f"Created rule #{rule['id']}")
Response — 201 Created
{
"id": 17,
"endpoint_id": 184,
"name": "canary-5pct",
"priority": 10,
"target_agent_id": "",
"target_agent_tags": "canary,v2",
"enabled": true,
"conditions": [
{"id": 17, "rule_id": 17, "condition_type": "header", "condition_key": "X-Canary", "pattern": "true", "negate": false}
],
"created_at": "2026-04-29T13:00:00Z",
"updated_at": "2026-04-29T13:00:00Z"
}