Docs

API Reference

Schema reference for routes.json, policy options, and environment config. Gateway behavior is declared here.

routes.json

The top-level file defines routes, upstream targets, and each route's policy chains.

Route object

{
  "path": "/v1/chat/completions",     // required: URL path to match
  "methods": ["POST"],              // required: HTTP methods to match
  "upstream": "https://...",        // required: upstream base URL
  "pathRewrite": "/chat/completions", // optional: rewrite path before forwarding
  "policies": {
    "inbound": [ ... ],            // run before forwarding
    "outbound": [ ... ]            // run after upstream response
  },
  "corsPolicy": "anything"         // optional: named CORS policy
}

Path parameters

Define dynamic segments with :param. Policies receive the matched value as a request property.

"path": "/models/:modelId/completions"

Policy schema

Each entry in an inbound or outbound array is a policy object:

{
  "name": "my-rate-limit",          // unique name, referenced in logs
  "policyType": "rate-limit-inbound", // policy identifier
  "options": { ... }              // policy-specific options
}

Built-in policy types

policyType	Direction	Description
`api-key-inbound`	inbound	Validate Zuplo-managed API keys in Authorization header
`rate-limit-inbound`	inbound	Request rate limiter (fixed window, sliding window, or token bucket)
`token-budget-inbound`	inbound	Daily token budget per consumer. Reads usage from upstream response.
`jwt-inbound`	inbound	JWT validation with JWKS endpoint, RS256/ES256 support
`llm-routing-inbound`	inbound	Route to a provider chain with failover and load balancing
`mcp-session-guard-inbound`	inbound	Auth and rate limiting for MCP sessions
`request-log-outbound`	outbound	Log request + response metadata to a configured sink
`header-inject-outbound`	outbound	Add or override response headers

Environment config

Put secrets and environment-specific values in zuplo.env.json. Reference them in policies with $env(KEY_NAME).

{
  "OPENAI_API_KEY": "sk-...",
  "ANTHROPIC_API_KEY": "sk-ant-...",
  "JWKS_URL": "https://auth.yourapp.com/.well-known/jwks.json"
}

Response codes

HTTP code	Meaning
`401`	API key missing or invalid
`403`	Consumer does not have access to this route
`429`	Rate limit exceeded. `Retry-After` header included.
`502`	All upstream providers failed (LLM routing exhausted)
`503`	Gateway policy error (misconfigured policy options)