Gateway Routes

What Are Gateway Routes?

A Gateway Route is AgentWatch’s fundamental routing unit. It defines:

• Which inbound path to intercept (e.g. /v1/chat/completions)
• Which upstream target to forward matching requests to (a provider URL or load-balanced pool)
• How to transform headers, query parameters, and request body before forwarding
• How to protect the route with rate limits, IP allowlists/blocklists, circuit breakers, and timeouts

Every AI API call a developer makes to AgentWatch is matched against the gateway route table. Routes are evaluated in priority order — the first match wins.

How a Request Flows Through a Gateway Route

Developer API Call
        │
        ▼
┌─────────────────────────────────────────┐
│  Route Matching (path + method)         │
│  First matching route wins              │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Security Checks                        │
│  • IP allowlist / blocklist             │
│  • Rate limit (token bucket per route)  │
│  • Circuit breaker — open? Fail fast    │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Request Transforms                     │
│  • Rewrite path                         │
│  • Inject / remove headers              │
│  • Replace query parameters             │
│  • Modify request body (templates)      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Forward to Upstream Target             │
│  (HTTP / HTTPS; streaming supported)    │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Response Transforms                    │
│  • Inject / remove response headers     │
└──────────────┬──────────────────────────┘
               │
               ▼
         Return to Client

Route Configuration Fields

Field	Description	Example
Name	Human-readable label	Production OpenAI
Path Pattern	URL path to match (exact or glob)	/v1/chat/completions
Method	HTTP method (GET, POST, *)	POST
Target URL	Upstream endpoint to forward to	https://api.openai.com
Priority	Evaluation order (lower = first)	1
Enabled	Enable / disable without deleting	true
Timeout (ms)	Max time to wait for upstream	60000
Strip Prefix	Remove path prefix before forwarding	/api/v1
Mode	proxied, enriched, or post-process	proxied

Route Modes

Mode	Description
Proxied	Standard pass-through. Request → upstream → response. Full streaming support.
Enriched	Capture the upstream LLM response, send it to a secondary AgentEnricher endpoint, then return the enriched result to the client.
Post-Process	Send to the AgentEnricher first, extract enriched content, inject it into a second LLM call, then return the final response.

Request Transforms

Transforms modify requests before they are forwarded upstream. They use template variables that are resolved at request time:

Variable	Resolves to
{{route_name}}	The matched route’s name
{{tenant_id}}	The API key’s tenant ID
{{organization_id}}	The tenant’s organization ID
{{timestamp}}	Current UTC timestamp

Path rewriting:

{ "match": "^/v1/", "replace": "/openai/v1/" }

Header injection:

{ "name": "X-Custom-Tenant", "value": "{{tenant_id}}", "action": "set" }

Header removal:

{ "name": "Authorization", "action": "remove" }

Rate Limiting Per Route

Each route has its own rate limit bucket independent of global limits:

Setting	Description	Default
maxRequests	Tokens in the bucket	1000
windowMs	Refill window in milliseconds	60000 (1 min)

When the bucket is empty, the route returns 429 Too Many Requests with a Retry-After header.

IP Filtering Per Route

• Allowlist — Only IP addresses matching the CIDR ranges in this list may access the route. Empty = allow all.
• Blocklist — IP addresses matching these CIDR ranges are rejected with 403 Forbidden.

Blocklist is evaluated before allowlist. Both support CIDR notation (192.168.0.0/16).

Health Monitoring

AgentWatch periodically sends HEAD requests to each route’s upstream target and tracks:

State	Meaning
healthy	Responding within expected latency
degraded	Elevated latency or occasional errors
unhealthy	Auto-disabled after 6 consecutive failures; re-enabled after 3 successes

View real-time route health at Settings → Gateway Analytics (§12.19).

Step-by-Step: Create a Gateway Route

1. Navigate to Settings → Gateway Routes.
2. Click Add Route.
3. Set Name, Path Pattern, and Target URL.
4. Set Timeout (default 60 s) and Priority (1 = highest).
5. (Optional) Under Request Transforms, add header injections or path rewrites.
6. (Optional) Enable Rate Limiting and set a per-minute request cap.
7. (Optional) Add IP Allowlist or Blocklist CIDR ranges.
8. Click Save. The route is active immediately.

Step-by-Step: Load-Balanced Route

1. Create the route as above.
2. Toggle Load Balancing on.
3. Add multiple provider entries, each with a Weight (e.g., OpenAI: 70, Anthropic: 30).
4. Select Strategy: weighted, round-robin, least-loaded, or failover.
5. Click Save. AgentWatch distributes traffic according to weights and health.

API Reference

Method	Endpoint	Description
GET	/admin/gateway/routes	List all routes
POST	/admin/gateway/routes	Create a route
PUT	/admin/gateway/routes/:id	Update a route
DELETE	/admin/gateway/routes/:id	Delete a route
GET	/admin/gateway/health	Route health statuses
POST	/admin/gateway/routes/:id/health/check	Trigger on-demand health check
GET	/admin/gateway/openapi.json	OpenAPI spec generated from routes

---