Config

Use the schema as the contract for valid gateway behavior before you deploy any routing changes. The schema defines every field the gateway accepts, including

Use the schema as the contract for valid gateway behavior before you deploy any routing changes. The schema defines every field the gateway accepts, including paths, servers, authorizer, cors, variables, services, and serviceBindings. Start here if you want a top-level map of what the config can express.

Last reviewed: 2026-03-06

When to use this

Use the config reference when you need to understand the shape, source, or validation behavior of the gateway JSON configuration. The config file is the single source of truth for all routing, auth, CORS, and integration behavior in the gateway.

Key concepts

• The config schema (api-config.schema.json) defines every valid field, type, and default. Use it with your editor for autocompletion and validation before deploying.

• Config can be loaded from three sources: a local JSON file bundled with the worker, a Cloudflare KV namespace, or the SAG_API_CONFIG_JSON environment variable. The gateway checks them in that order.

• Strict mode rejects any config with unknown fields or type mismatches at startup, returning a 500 error. Compatibility mode logs warnings but allows the worker to start.

• Legacy key normalization automatically converts old field names (like http to paths and servicesBindings to serviceBindings) so older configs continue to work during migration.

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 shows a minimal valid config with a CORS block and a single path. Every field in this example is defined in the schema -- $schema enables editor validation, title is metadata, and paths is the required routing array.

Troubleshooting

• If the worker starts but routes return 404, check which config source the gateway loaded -- add a health route to each source so you can identify which one is active.

• If strict mode rejects your config, run the JSON against api-config.schema.json locally with a JSON schema validator to see the exact validation errors.

• If legacy key normalization is not converting a field, confirm you are running a version of the gateway that supports that alias -- check the CHANGELOG for the normalization version.

• If KV config changes are not reflected after updating, remember that Workers cache KV reads. Redeploy the worker or wait for the cache TTL to expire.

Related docs

• overview

• wrangler

• gateway troubleshooting matrix