List Routing Rules

GET /v1/endpoints/{uuid}/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
The endpoint's uuid from /endpoints.

Response (200 OK)

JSON array of rules ordered by priority ASC ([] when the endpoint has none). Each rule:

uuid string (uuid)
The rule's public id. Use it in /routing-rules/{rule_uuid} and in reorder's ordered_uuids.
endpoint_uuid string (uuid)
Owning endpoint (echo).
name string
Free-form label.
priority int
Match order. Lower runs first; ties broken by creation order.
target_agent_id string?
Agent ID this rule routes to. Mutually exclusive with target_agent_tags. Omitted when empty.
target_agent_tags string?
Comma-separated tag list — any agent with all these tags is eligible. Used for "any us-east agent" type routing. Omitted when empty.
enabled boolean
false = rule is in the table but skipped during evaluation. Useful for staging changes.
fallback boolean
What happens when the rule matches but its target agent is offline: true = send the request to any healthy agent of the endpoint (the default round-robin); false = answer 502.
conditions array
List of match conditions — ALL must hold for the rule to fire. Each: {rule_uuid, condition_type, condition_key?, pattern, negate} (conditions have no public id of their own). 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. condition_key is omitted when empty.
quota_paused_at datetime?
Set while the rule is paused because the account is over its plan's routing-rule limit: kept, but not applied, until the account has room again. Omitted when not paused.
created_at, updated_at datetime
RFC 3339 UTC timestamps.

Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

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/019bb1e4-e785-77d2-9966-c3cff31d0a0e/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("019bb1e4-e785-77d2-9966-c3cff31d0a0e"): badge = "✅" if rule["enabled"] else "❌" print(f"{badge} [{rule['priority']:>3}] {rule['name']}")
Response — 200 OK
[ { "uuid": "019b8b02-732f-7d67-b36a-271ec6e8d5fa", "endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "name": "api-route", "priority": 10, "target_agent_id": "api-agent-prod", "enabled": true, "fallback": false, "conditions": [ {"rule_uuid": "019b8b02-732f-7d67-b36a-271ec6e8d5fa", "condition_type": "path", "pattern": "/api/*", "negate": false} ], "created_at": "2026-04-29T12:00:00Z", "updated_at": "2026-04-29T12:00:00Z" }, { "uuid": "019b962b-971a-77df-97b0-e3905fa06cd4", "endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "name": "canary-5pct", "priority": 20, "target_agent_tags": "canary,v2", "enabled": true, "fallback": true, "conditions": [ {"rule_uuid": "019b962b-971a-77df-97b0-e3905fa06cd4", "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" } ]
Was this helpful?
On this page
List Routing Rules
Was this helpful?
Homepage Docs Dashboard Docs API Docs nvelox Dashboard