List Routing Rules
Routing rules sit between the public URL and the agents. They match incoming requests on path, header, cookie, client IP, or HTTP method, and route the matched traffic to a specific agent (by ID) or any agent matching a tag set. Useful for canary deployments, regional sharding, blue/green cutovers, and routing different paths to different upstream services.
Rules are evaluated in priority order (lowest first). The first rule whose conditions all match wins; remaining rules are skipped. If no rule matches, the request falls through to the endpoint's default routing (round-robin across all connected agents).
Path parameters
uuid string (uuid) Req
Endpoint UUID.
Response (200 OK)
JSON array of rules ordered by priority ASC. Each rule:
id int64
Numeric rule ID.
endpoint_id int64
Owning endpoint (echo).
name string
Free-form label.
priority int
Match order. Lower runs first; ties broken by
id.target_agent_id string?
Agent ID this rule routes to. Mutually exclusive with
target_agent_tags.target_agent_tags string?
Comma-separated tag list — any agent with all these tags is eligible. Used for "any us-east agent" type routing.
enabled boolean
false = rule is in the table but skipped during evaluation. Useful for staging changes.conditions array
List of match conditions — ALL must hold for the rule to fire. Each:
{condition_type, condition_key?, pattern, negate}. condition_type is one of path, header, cookie, client_ip, method. condition_key is the header/cookie name (when relevant). pattern supports glob (/api/*) and regex (per platform configuration). negate: true inverts the match.created_at, updated_at datetime
RFC 3339 UTC timestamps.
Errors
401 Unauthorized
Missing auth.
404 Not Found
Endpoint doesn't exist or doesn't belong to the calling user.
Request
curl "https://api.ngris.com/v1/endpoints/<uuid>/routing-rules" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
for rule in client.routing_rules.list("<endpoint_uuid>"):
badge = "✅" if rule["enabled"] else "❌"
print(f"{badge} [{rule['priority']:>3}] {rule['name']}")
Response — 200 OK
[
{
"id": 1,
"endpoint_id": 184,
"name": "api-route",
"priority": 10,
"target_agent_id": "api-agent-prod",
"target_agent_tags": "",
"enabled": true,
"conditions": [
{"id": 1, "rule_id": 1, "condition_type": "path", "pattern": "/api/*", "negate": false}
],
"created_at": "2026-04-29T12:00:00Z",
"updated_at": "2026-04-29T12:00:00Z"
},
{
"id": 2,
"endpoint_id": 184,
"name": "canary-5pct",
"priority": 20,
"target_agent_id": "",
"target_agent_tags": "canary,v2",
"enabled": true,
"conditions": [
{"id": 2, "rule_id": 2, "condition_type": "header", "condition_key": "X-Canary", "pattern": "true", "negate": false}
]
}
]