> 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/config-schema-overview/config-from-sag-api-config-json.md).

# Config Source: SAG\_API\_CONFIG\_JSON

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 variable, which is useful when you generate config dynamically in a pipeline. This source has the lowest priority -- the gateway only reads it if no local file or KV config is found.

**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

```bash
export SAG_API_CONFIG_JSON='{"paths":[{"method":"GET","path":"/health","response":{"status":"ok"}}]}'
wrangler deploy
```

This snippet exports the full gateway config as the `SAG_API_CONFIG_JSON` environment variable. The JSON must be valid and complete -- the gateway parses it at startup and uses it as the sole routing definition for that worker instance.

## 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](/configuration/overview.md)
* [wrangler](/deployment/wrangler.md)
* [gateway troubleshooting matrix](/troubleshooting/wrangler-deploy-guide/gateway-troubleshooting-matrix.md)


---

# 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/config-schema-overview/config-from-sag-api-config-json.md?ask=<question>&goal=<endgoal>
```

`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.