> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Gateway API reference

> The endpoints that your applications call on the Fabric AI Gateway data plane, for LLM, MCP, and REST routes, and the endpoints the gateway answers itself.

Your applications send requests to the data plane, the part of Fabric AI Gateway that serves traffic. This page describes the endpoints that the data plane exposes: LLM endpoints, the MCP endpoint, REST passthrough, and the endpoints that the gateway answers itself, such as health checks. For the admin API that manages configuration, see [Use the admin API](/configure/automation/admin-api).

## Base URL

Every request goes to a route. A route's URL is the data plane host followed by the route's base path:

```text
https://GATEWAY_HOST/ROUTE_BASE_PATH
```

For a cloud tenant, `GATEWAY_HOST` has the form `TENANT_NAME.dp.fabricgateway.ai`. For a data plane that your organization runs, it's the host that an admin set in **Admin** > **Data plane**. To copy a route's URL, in the console sidebar, select **LLMs**, **MCP servers**, or **Services**, select the **Routes** tab, find the route, and select the copy icon in its row: **Copy LLM base URL** for an LLM route or **Copy DP URL** for other routes.

A request to a host that doesn't belong to your organization gets `421`. A path that no route serves gets `404`.

## Authentication

Send your gateway key in the `fg-api-key` header on every request. If the route uses JWT Auth, send `Authorization: Bearer <token>` instead. The gateway removes your gateway credential before it calls the upstream and adds the upstream's own credential. For details, see [Authenticate and send a request](/use/authenticate) and [Request and response headers](/reference/headers).

## LLM endpoints

An LLM route exposes the endpoints that you selected for it under **Endpoints**, appended to the route's base URL. The endpoints you can select depend on the API that the route's providers speak.

| API                | Endpoints                                                                                                                                | Notes                                                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| OpenAI-compatible  | `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/embeddings`, `GET /v1/models`, and other endpoints that the provider offers | Point the OpenAI SDK's base URL at the route's base URL. For details, see [Send OpenAI-compatible requests](/use/llm/openai-compatible).         |
| Anthropic Messages | `POST /v1/messages`, `POST /v1/messages/count_tokens`, `GET /v1/models`                                                                  | Send the `anthropic-version` header as you would to Anthropic. For details, see [Send Anthropic Messages requests](/use/llm/anthropic-messages). |
| Provider-native    | Paths that the provider defines, for example Amazon Bedrock's `/model/{model_id}/invoke`                                                 | The model comes from the path instead of the body.                                                                                               |

The request and response bodies are the provider's own. The gateway works like this:

* **No translation.** The gateway sends an OpenAI-format request only to a provider that offers that OpenAI endpoint, and an Anthropic-format request only to an Anthropic-format endpoint. A request to an endpoint that no provider on the route offers gets `404` `unknown LLM endpoint`.
* **The model comes from the request.** The gateway reads `model` from the JSON body, or from the path for provider-native endpoints, to check it against the connection's model filter and to route it. It forwards the body unchanged unless a plugin, such as the Adaptive Model Router, rewrites it.
* **Streaming is relayed as it arrives.** Set `"stream": true` as you would with the provider. The gateway passes each server-sent event or AWS event-stream frame to you as soon as it's complete. Before the first event reaches you, the gateway can still fail over to another provider.
* **Errors use the provider's envelope.** Most gateway errors on LLM routes use the OpenAI or Anthropic error shape, matching the endpoint you called. For the full list, see [Gateway error codes](/reference/error-codes).

On a route with several connections, a routing plugin such as the LLM Router chooses the connection. Without a routing plugin, name the connection in the `x-gateway-service` header, or the request gets `400`.

### Model-name routing

A route with the `llm-model-router` plugin serves many providers from one base URL. You name the model as `<provider>/<model>`, for example `openai/gpt-4o-mini`, or by an alias that your admin defines. On these routes:

* `GET /v1/models` lists the models you can call. It answers in OpenAI's list format, or in Anthropic's when you send the `anthropic-version` header.
* `GET /v1/models/{model}` returns one entry from that list, or `404` if the model isn't on it.
* The `x-fabric-model` response header names the provider and model that answered.

For details, see [Route requests by model name](/configure/routing/model-router).

## MCP endpoint

An MCP route serves one MCP endpoint at its URL, using the Streamable HTTP transport. Point your MCP client at the route's URL. For the steps, see [Connect an MCP client](/use/mcp/connect-a-client).

| Request                                | What happens                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` with a JSON-RPC request         | The gateway answers `initialize`, `ping`, `tools/list`, and `tools/call` itself. On protocol revisions up to 2025-11-25, it forwards other methods, such as `resources/*` and `prompts/*`, to the route's first MCP server. On revision 2026-07-28, it answers them with HTTP `404` and JSON-RPC `-32601`, and it also answers `server/discover` and `subscriptions/listen`.           |
| `POST` with a notification             | `202` with an empty body.                                                                                                                                                                                                                                                                                                                                                              |
| `GET` with `Accept: text/event-stream` | Opens a notification stream for the caller. The gateway sends `notifications/tools/list_changed` after you connect an account, so your client can reload its tools. On revision 2026-07-28, `GET` and `DELETE` get `405` with `Allow: POST`. Clients on that revision receive these notifications through a `POST` `subscriptions/listen` request, whose response is the event stream. |

The gateway speaks MCP protocol revisions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. On 2026-07-28, each request carries its envelope in `params._meta`, and some JSON-RPC error codes differ from earlier revisions. For the codes, see [Gateway error codes](/reference/error-codes).

How the gateway answers the main methods:

* **`initialize`** returns a session ID in the `Mcp-Session-Id` header. On a route with one MCP server, the result is the server's own `initialize` result. On any other route, or when that server can't be reached or needs an account you haven't connected, the result is the gateway's own: it advertises the `tools` capability with `listChanged` and names `fabric-gateway` as the server.
* **`tools/list`** returns one list built from every MCP server on the route. On a route with several connections, each tool name has a prefix that identifies its server, in the form `<prefix>__<tool>`. Tools that you have no access to are removed. A server that needs an account you haven't connected appears as one `connect_<service>` tool. When the route uses Tool Search, the list is exactly `search_tool`, `get_tool`, and `execute_tool`.
* **`tools/call`** calls the tool on its server and returns the server's result unchanged.

When a gateway error happens during an MCP call, the gateway usually answers with HTTP `200` and a JSON-RPC error. For the codes, see [Gateway error codes](/reference/error-codes).

## REST passthrough

A REST route forwards requests to the API behind it. The gateway matches the request to a route by path, host, method, and any header conditions on the route, and then forwards it:

* **Path.** The upstream receives the request path, or a rewritten path if the route defines one, after the connection's base path. The query string is passed unchanged.
* **Method, headers, and body.** Passed through, except for the changes listed in [Request and response headers](/reference/headers#what-the-upstream-receives).
* **Response.** The upstream's status, headers, and body are relayed unchanged, unless a response plugin changes them. Server-sent events and AWS event streams are passed on event by event.

The gateway doesn't handle CORS and doesn't add `Access-Control-*` headers. WebSocket upgrades don't work through the gateway. For the steps to call a REST route, see [Call a REST route](/use/call-a-rest-api).

## Example requests

Each route type takes the same gateway key in the `fg-api-key` header. Replace `GATEWAY_HOST`, `BASE_URL`, `ROUTE_URL`, and `GATEWAY_KEY`.

#### LLM

```bash
curl "BASE_URL/v1/chat/completions" \
  -H "fg-api-key: GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Hello from Fabric Gateway!" }]
  }'
```

For the Anthropic Messages API and streaming, see [Use the Anthropic Messages API](/use/llm/anthropic-messages).

#### MCP

```bash
curl -i "ROUTE_URL" \
  -H "fg-api-key: GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

For the next steps, see [Connect an MCP client](/use/mcp/connect-a-client#verify-the-connection).

#### REST

```bash
curl -i "https://GATEWAY_HOST/petstore/pets/42" \
  -H "fg-api-key: GATEWAY_KEY"
```

For details, see [Call a REST route](/use/call-a-rest-api).

## Endpoints the gateway answers itself

The gateway answers these paths itself, before it matches any route. A route that you configure on one of these paths never receives traffic for it. Paths are compared exactly, so `/healthz/` isn't a gateway endpoint.

| Path                                                                                                                                                              | Methods   | What it returns                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/healthz`                                                                                                                                                        | Any       | `200` with `{"status":"ok"}` while the process is up. Answers on any hostname and needs no credential.                                                                                                                                                                                                                                                                            |
| `/readyz`                                                                                                                                                         | Any       | `200` with `{"status":"ready"}` while the process can take requests. It doesn't wait for configuration to arrive from the control plane. On a data plane configured with an OPA policy bundle, it answers `503` with `{"status":"not_ready","reason":"opa_bundle_not_loaded"}` until the bundle loads. Answers on any hostname and needs no credential.                           |
| `/readyz/secret-store`                                                                                                                                            | Any       | `200` with `{"status":"ready"}`. On a data plane with the distributed secret store, it answers `503` with `{"status":"not_ready","reason":"secret_store_rereplication_pending"}` for up to 5 minutes while the pod rewrites its entries. It ignores the OPA policy bundle. Answers on any hostname and needs no credential.                                                       |
| `/.well-known/oauth-protected-resource/ROUTE_PATH`                                                                                                                | `GET`     | OAuth protected-resource metadata for a route protected by JWT Auth, which MCP clients use to find where to sign in. Other methods get `405`. A path that no protected route serves, and the bare prefix, get `404`.                                                                                                                                                              |
| `/.well-known/oauth-authorization-server` (`GET`), `/auth/register` (`POST`), `/auth/authorize` (`GET`, `POST`), `/auth/callback` (`GET`), `/auth/token` (`POST`) | As listed | The gateway's sign-in endpoints for MCP clients, including dynamic client registration and PKCE. Other methods get `405`, and other paths under `/auth/` get `404`. Active only when the data plane has an encryption key and your organization has at least one OIDC identity provider with a client ID configured for gateway sign-in. Otherwise these paths go to your routes. |
| Paths under `/api/v1/oauth/broker/` that end in `/authorize` (`GET`, `POST`) or `/callback` (`GET`)                                                               | As listed | The pages where you connect an account for an MCP server or API. Other methods get `405`, and other paths under this prefix get `404`.                                                                                                                                                                                                                                            |
| `/.well-known/agent.json`                                                                                                                                         | Any       | The agent card for an agent route. `404` if there's none.                                                                                                                                                                                                                                                                                                                         |

Only `/healthz` and `/readyz` answer on any hostname. Every other path in this table needs a hostname that belongs to your organization, and the gateway answers `421` for an unknown host. The gateway issues no tokens of its own, so `GET /.well-known/openid-configuration` and `GET /auth/jwks` return `404`.

No plugins run on these endpoints, so rate limits and authentication plugins don't apply to them.

## Next steps

* Send your first request by following [Authenticate and send a request](/use/authenticate).
* Check which endpoints each provider supports in [Supported endpoints](/reference/supported-endpoints).
* Look up gateway errors in [Gateway error codes](/reference/error-codes).
* To connect your account to an MCP server, see [Connect your accounts to MCP servers](/use/mcp/connect-your-accounts).