Skip to navigation

Gateway API reference

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.

Base URL

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

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 and Request and response 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.

APIEndpointsNotes
OpenAI-compatiblePOST /v1/chat/completions, POST /v1/responses, POST /v1/embeddings, GET /v1/models, and other endpoints that the provider offersPoint the OpenAI SDK’s base URL at the route’s base URL. For details, see Send OpenAI-compatible requests.
Anthropic MessagesPOST /v1/messages, POST /v1/messages/count_tokens, GET /v1/modelsSend the anthropic-version header as you would to Anthropic. For details, see Send Anthropic Messages requests.
Provider-nativePaths that the provider defines, for example Amazon Bedrock’s /model/{model_id}/invokeThe 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.

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.

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.

RequestWhat happens
POST with a JSON-RPC requestThe 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 notification202 with an empty body.
GET with Accept: text/event-streamOpens 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.

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.

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

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.

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.

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.

PathMethodsWhat it returns
/healthzAny200 with {"status":"ok"} while the process is up. Answers on any hostname and needs no credential.
/readyzAny200 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-storeAny200 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_PATHGETOAuth 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 listedThe 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 listedThe 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.jsonAnyThe 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