Routing: Static Response Routes

Return fixed JSON or simple values directly from config for health checks and low-risk utility endpoints. Static response routes bypass integration entirely, so

Return fixed JSON or simple values directly from config for health checks and low-risk utility endpoints. Static response routes bypass integration entirely, so they have no upstream dependency and respond in sub-millisecond time. Use them for health probes, feature flags, and version endpoints.

Last reviewed: 2026-03-06

When to use this

Use the routing guides when you need to understand how the gateway matches incoming requests to configured paths. Routing is the core behavior of the gateway -- every request passes through the path matcher before reaching an integration, auth check, or static response.

Key concepts

• The gateway supports three route shapes: exact paths (/health), parameterized paths (/users/:id), and wildcard paths (/proxy/{.+}). Exact matches take highest priority.

• When multiple routes could match a request, the gateway uses a fixed priority order: exact > parameterized > wildcard. This is not configurable.

• The method field accepts standard HTTP methods (GET, POST, etc.) as well as ANY, which matches all methods on that path.

• Prefix add/remove rules transform the path before forwarding to the upstream, letting you decouple public API structure from backend path layout.

• Static response routes skip integration entirely and return the response field directly, which is useful for health checks and feature flags.

Repo-grounded example

{
  "$schema": "./api-config.schema.json",
  "title": "Minimal Gateway",
  "cors": {
    "allow_origins": ["https://app.example.com"],
    "allow_methods": ["GET", "POST", "OPTIONS"],
    "allow_headers": ["Content-Type", "Authorization"],
    "expose_headers": ["X-Request-Id"],
    "allow_credentials": true,
    "max_age": 300
  },
  "paths": [
    {
      "method": "GET",
      "path": "/health",
      "response": { "status": "ok" }
    }
  ]
}

This snippet returns a static JSON object from the /health path. The response field can be a JSON object, a string, a boolean, or null -- whatever the route needs to return without calling an upstream service.

Troubleshooting

• If a request hits the wrong route, check whether a wildcard pattern is matching before your intended exact or parameterized route -- exact always wins over wildcard.

• If an OPTIONS request returns unexpected results, verify whether you have an explicit OPTIONS handler for that path or are relying on the default CORS 204 behavior.

• If prefix removal produces a double-slash in the upstream URL, confirm that both the remove_prefix and the upstream url do not include trailing/leading slashes that conflict.

• Use wrangler tail and look at the matched path in the log output to confirm which route config entry the gateway selected.

Related docs

• README

• add and remove prefix

• gateway troubleshooting matrix