Endpoints · auth · protocol interop

This chapter covers which endpoints the gateway exposes, how callers authenticate, and the gateway's protocol translation capability. These are all gateway concerns, not the upstream API's request-body field specs.

Endpoint list

Data-plane endpoints (require access-key auth)

Client requests hit these endpoints and the gateway forwards them to upstreams.

Method	Path	Purpose
POST	/v1/chat/completions	OpenAI Chat Completions
POST	/v1/responses	OpenAI Responses API
GET/DELETE	/v1/responses/{id}	Retrieve/delete Responses turns in gateway storage (see the store parameter and response retrieval)
POST	/v1/messages	Anthropic Messages
POST	/v1/messages/count_tokens	Anthropic token counting
POST	/v1beta/models/{*rest}	Gemini :generateContent / :streamGenerateContent / :countTokens
POST	/v1/models/{*rest}	Gemini v1 stable alias (upstream still built as v1beta)
POST/GET	/v1beta/cachedContents, /v1beta/cachedContents/{id}	Google context caching (create/list/read/update/delete)
POST	/v1/images/generations	Image generation
POST	/v1/images/edits	Image editing (multipart upload)
POST	/v1/embeddings	Text embeddings
POST	/v1/rerank, /v2/rerank	Reranking (Jina/Cohere/vLLM compatible)
POST	/v1/audio/transcriptions	Speech to text (ASR)
POST	/v1/audio/translations	Speech to English
POST	/v1/audio/speech	Text to speech (TTS)
GET	/v1/realtime	Realtime sessions (WebSocket upgrade, OpenAI Realtime protocol), see Realtime sessions
POST/GET	/v1/services/{*rest}	DashScope unified service (text/multimodal/image/video/embeddings/rerank/ASR); GET polls async tasks /v1/services/{model}/tasks/{task_id}
POST/GET	/v3/{model}/{*rest}	identity passthrough: client protocol == target protocol, request body forwarded as-is
POST	/mcp	MCP JSON-RPC 2.0 (Streamable HTTP)
GET	/mcp/sse	MCP SSE transport
GET	/v1/models	Model list (OpenAI style)
GET	/v1beta/models	Model list (Gemini style)

{*rest} in a path means matching any subsequent path segments. For example /v1beta/models/gemini-2.0-flash:generateContent.

Public endpoints (no access key required)

Method	Path	Purpose
GET	/	Model list page (HTML)
GET	/health, /healthz	Liveness probes, always 200
GET	/ready	Readiness probe, 503 when unhealthy/draining
GET	/metrics	Prometheus metrics; requires Bearer access after configuring metrics_auth_token, 403 if unconfigured

About AWS Bedrock and passthrough

• AWS Bedrock is an upstream-side protocol: the gateway does not expose Bedrock-shaped client endpoints. Clients access Bedrock models via OpenAI/Anthropic/Gemini protocol endpoints (translated) or /v3/{model}/{*rest} (passthrough).
• /v3/{model}/{*rest} is the identity passthrough entry: when the client protocol equals the model's configured target protocol, the request body is forwarded as-is with no protocol conversion.

Authentication

When calling data-plane endpoints, the gateway tries authentication in the following order, using the first match:

Order	Request header	Applicable client
1	Authorization: Bearer <your access key>	OpenAI SDK, generic
2	x-api-key: <your access key>	Anthropic SDK
3	x-goog-api-key: <your access key>	Gemini SDK
4	(none of the above)	Anonymous fallback: only matches when an anonymous=true access key is configured

Key points:

• The Bearer prefix is case-insensitive.
• The access key is the one you issued in the console (see Access key and key group fields), not the upstream's sk-....
• Key format has no enforced prefix; any string works.
• A request with an invalid key, when an anonymous key is configured, falls to the anonymous branch (equivalent to no key).
• No valid key and no anonymous key → 401 Unauthorized.
• Unmatched proxy paths also return 401 (rather than 404), to avoid letting unauthenticated requests probe routes.

Protocol interop capability

One of the gateway's core capabilities: the client protocol and the upstream protocol can differ.

For example:

• Your client uses the Anthropic SDK (requests /v1/messages), but the upstream is OpenAI — the gateway translates the Anthropic request body into OpenAI format for the upstream, then translates the OpenAI response back into Anthropic format.
• Your client uses the OpenAI SDK, but the upstream is Gemini or AWS Bedrock — translated the same way.

There are 12 supported protocols: OpenAI Chat, OpenAI Response, OpenAI Images, OpenAI Embeddings, OpenAI Audio, OpenAI Rerank, Anthropic, Google, AWS Bedrock Converse, AWS Bedrock InvokeModel, Alibaba DashScope, Passthrough.

The full interop matrix is in Protocol interop matrix. Key points:

• Most protocol pairs translate in both directions.
• The passthrough protocol forwards directly without translation.
• If a "client protocol → upstream protocol" combination has no translator, the request returns 400 (unsupported_feature).

Gateway-specific endpoints

Endpoint	Description
/v1/messages/count_tokens	Anthropic-style token counting; does not actually call the upstream and is not counted in statistics.
/v3/{model}/{*rest}	Identity passthrough; the request body is forwarded as-is to the model's configured target protocol.
/mcp, /mcp/sse	MCP gateway, aggregates external tool servers — see MCP configuration.

FAQ

Q: My client uses the OpenAI SDK but I want to call Anthropic's Claude model — what do I fill in? Point the client's base_url at the gateway http://<host>:7890/v1, and set model to the model name you configured in the gateway (whose upstream protocol is anthropic). The gateway automatically translates the OpenAI request into Anthropic format for the upstream. See Client integration and gateway differences for specifics.

Q: /v1/models doesn't list a model I just configured? Check whether the model is "enabled", whether its upstream is "enabled", and whether the model has hide_name set (if so it doesn't appear in the list and can only be accessed by alias). Also, identity-scoped model-mapping source names do not appear in the list — the list only contains models that really exist in the config; a mapping's from name (e.g. claude-opus-5) is usually a fictional client name and is not in it; but a client requesting that name directly is still mapped and routed successfully. See Configure identity model mapping.

Q: Why do some paths use /v1beta and others /v1? This is the upstream's native path difference: Gemini upstreams use /v1beta, OpenAI uses /v1. The gateway keeps the path prefix consistent with the upstream, so client SDKs can point at the gateway without modification.

Next: see Client integration and gateway differences for how each client SDK connects and how the gateway differs from native APIs; Protocol interop matrix for supported protocol pairs; Error codes for status codes and error-body formats.