> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/reference/endpoints · Doc index: https://docs.gatellm.io/en/llms.txt


# 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 {#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](/en/reference/clients-and-gateway-diffs.md#store-param)) |
| 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](/en/reference/realtime.md) |
| 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-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](/en/reference/access-keys-groups-fields.md)), **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](/en/reference/protocol-matrix.md). 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](/en/reference/mcp-config.md). |

## 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](/en/reference/clients-and-gateway-diffs.md) 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](/en/howto/configure-identity-model-mapping.md).

**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](/en/reference/clients-and-gateway-diffs.md) for how each client SDK connects and how the gateway differs from native APIs; [Protocol interop matrix](/en/reference/protocol-matrix.md) for supported protocol pairs; [Error codes](/en/reference/error-codes.md) for status codes and error-body formats.