> For the complete documentation index, see [llms.txt](https://docs.serverlessapigateway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.serverlessapigateway.com/reference.md). # Reference - [Config](https://docs.serverlessapigateway.com/reference/config-schema-overview.md): 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 - [Config Source: Local File](https://docs.serverlessapigateway.com/reference/config-schema-overview/config-from-local-file.md): Start with a local file when you are iterating in the repo and want simple, inspectable config. The gateway looks for the config file relative to the worker - [Config Source: Cloudflare KV](https://docs.serverlessapigateway.com/reference/config-schema-overview/config-from-kv.md): Load config from KV when you need runtime-managed routing without baking config into the bundle. This lets you update routing rules, add paths, or change - [Config Source: SAG\_API\_CONFIG\_JSON](https://docs.serverlessapigateway.com/reference/config-schema-overview/config-from-sag-api-config-json.md): Use the inline JSON env var for tests, previews, and CI flows that need an isolated config payload. The entire config is passed as a single environment - [Config Validation: Strict Mode](https://docs.serverlessapigateway.com/reference/config-schema-overview/config-strict-mode.md): Enable strict mode when you want invalid config to fail the worker early instead of logging compatibility warnings. In strict mode, any unknown field, type - [Config Validation: Compatibility Mode](https://docs.serverlessapigateway.com/reference/config-schema-overview/config-compatibility-mode.md): Stay in compatibility mode when you are normalizing legacy config and cannot block traffic on validation warnings yet. Compatibility mode logs warnings for - [Config Normalization: Legacy Keys](https://docs.serverlessapigateway.com/reference/config-schema-overview/config-legacy-key-normalization.md): Understand how legacy aliases like \`http\` and \`servicesBindings\` are normalized before routing begins. The gateway automatically converts old field names to - [CORS And Responses](https://docs.serverlessapigateway.com/reference/cors-basics.md): Use the gateway CORS block to centralize browser access policy instead of reimplementing it in every upstream. The CORS config defines which origins, methods, - [CORS: Credentials and Origins](https://docs.serverlessapigateway.com/reference/cors-basics/cors-credentials-and-origins.md): Set credentials and origins deliberately so browser auth works without opening the API too broadly. When \`allow\_credentials\` is true, the browser requires an - [CORS: Default Preflight Behavior](https://docs.serverlessapigateway.com/reference/cors-basics/cors-preflight-default-behavior.md): Rely on the built-in 204 preflight response unless a route truly needs a custom OPTIONS handler. The gateway automatically responds to OPTIONS requests using - [Responses: JSON, String, Boolean, and Null](https://docs.serverlessapigateway.com/reference/cors-basics/response-json-string-boolean-null.md): Use config responses for small, deterministic endpoints where a full proxy or service call adds no value. The \`response\` field in a path entry can be a JSON - [Responses: Error Shapes](https://docs.serverlessapigateway.com/reference/cors-basics/error-response-shapes.md): Use this page to understand the gateway's JSON error surface before wiring client-side handling. The gateway returns structured JSON errors for 401, 403, 404, - [Responses: Powered-By Header Behavior](https://docs.serverlessapigateway.com/reference/cors-basics/powered-by-header-behavior.md): Know when the gateway adds its response header so you can reason about downstream caching and observability. The gateway includes a \`powered-by\` header on every - [Responses: Health, Readiness, and Liveness Patterns](https://docs.serverlessapigateway.com/reference/cors-basics/health-readiness-liveness-patterns.md): Model operational endpoints separately so you can distinguish worker health from upstream dependency health. A health endpoint confirms the worker is running; a - [Mapping And Variables](https://docs.serverlessapigateway.com/reference/mapping-overview.md): Use mapping when the upstream needs transformed headers or query params rather than the original client request. The mapping block lets you select specific - [Mapping from Request Headers](https://docs.serverlessapigateway.com/reference/mapping-overview/mapping-request-headers.md): Forward selected request headers to the upstream without exposing the whole client header set. Only headers listed in the \`mapping.headers\` block are sent -- - [Mapping from Request Query Parameters](https://docs.serverlessapigateway.com/reference/mapping-overview/mapping-request-query.md): Promote request query values into stable upstream parameters when you need consistent backend contracts. The \`mapping.query\` block lets you rename, forward, or - [Mapping from JWT Claims](https://docs.serverlessapigateway.com/reference/mapping-overview/mapping-jwt-claims.md): Inject user or tenant claims into upstream requests after the gateway verifies the token. Any standard or custom JWT claim is available via - [Mapping: Route Variables vs Global Variables](https://docs.serverlessapigateway.com/reference/mapping-overview/mapping-route-variables-vs-global-variables.md): Use route variables for one-off overrides and global variables for cross-route defaults. Global variables in the top-level \`variables\` block apply to all - [Environment Variables and Secret Replacement](https://docs.serverlessapigateway.com/reference/mapping-overview/env-and-secret-replacement.md): Replace \`$env.\*\` and \`$secrets.\*\` placeholders at load time so sensitive values stay outside repo config. The gateway resolves these placeholders when it parses - [Mapping: Debugging Null Values](https://docs.serverlessapigateway.com/reference/mapping-overview/mapping-debugging-null-values.md): Diagnose missing mapped values by checking token claims, request headers, and variable scope order. When a mapped value arrives as null or empty at the --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.serverlessapigateway.com/reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.