Routing: Prefix Add and Remove

Map public paths to upstream paths cleanly when the origin and public API use different prefixes. The gateway can strip a prefix from the incoming path before

Map public paths to upstream paths cleanly when the origin and public API use different prefixes. The gateway can strip a prefix from the incoming path before forwarding, or add a prefix that the upstream expects. This keeps your public API structure independent from backend path conventions.

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

{
  "servers": [
    { "alias": "upstream", "url": "https://api.example.com/base" }
  ],
  "paths": [
    {
      "method": "GET",
      "path": "/proxy/{.+}",
      "integration": {
        "type": "http_proxy",
        "server": "upstream"
      }
    }
  ]
}

This snippet proxies all subpaths to an upstream server. To add prefix manipulation, include "remove_prefix": "/api/v1" or "add_prefix": "/internal" fields in the path entry alongside the integration.

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