API details

Base API URL

All API endpoints in the reference documentation are relative to the following base URL:

https://api-gateway.merge.dev/v1

Authentication

For any request you make when communicating with Merge Gateway, you will need an API key to authenticate yourself as an authorized user.

Add your API Key with a “Bearer ” prefix as a header called Authorization to authorize your Merge API requests. This header must be included in every request in this format:

Authorization: Bearer <your_api_key>

You do not have to use the dashboard to get a key. The Management API mints, rotates, and revokes API keys programmatically, which is what you want if keys are provisioned per customer or checked into infrastructure-as-code.

Key endpoints

Gateway’s model-calling surface is centered around these endpoint groups:

• GET /models: List models, filter by provider or vendor, or fetch a single model with ?model=<provider/model_id>
• GET /vendors: List execution vendors and the models they currently serve, or fetch one with GET /vendors/{vendor_id}
• POST /responses: Create an LLM response in Gateway’s native Responses shape. The response includes the vendor that ultimately served the request and the service_tier that actually served it.
• POST /chat/completions: Create a chat completion in the OpenAI wire format
• POST /messages: Create a message in the Anthropic wire format, with POST /messages/count_tokens to count input tokens without calling a model
• POST /embeddings: Create embeddings, priced on input tokens

Gateway also exposes SDK-compatible surfaces under /v1/openai, /v1/anthropic, /v1/ai-sdk, and /v1/langchain, so an existing client reaches the same models with a base URL change. The OpenAI and Anthropic wire formats are additionally served at their vendor-default paths: POST /v1/chat/completions (OpenAI SDK pointed at https://api-gateway.merge.dev/v1) and POST /v1/messages plus /v1/messages/count_tokens (Anthropic SDK pointed at https://api-gateway.merge.dev). Both forms accept the same requests. See Get started.

Administering the org, rather than calling models, is a separate surface: see Management API below.

Management API

API keys, projects, routing policies, and usage are administered programmatically through the Management API, on the same host. It is authenticated by a management key (Authorization: Bearer mgmt_<your_management_key>) rather than a gateway API key, so the credential that provisions keys is never one that can make model calls. Create a management key in the dashboard under API keys → Management keys.

Full reference and scopes: Management API. Walkthroughs: API keys and Projects API.

Models API shape

GET /models returns canonical model identity at the top level and vendor-specific execution metadata under vendors.

Example:

1
{
2
  "model": "anthropic/claude-opus-4-6",
3
  "provider": "anthropic",
4
  "display_name": "Claude Opus 4.6",
5
  "vendors": {
6
    "anthropic": {
7
      "launch_date": "2025-05-14",
8
      "context_window": 1000000,
9
      "max_output_tokens": 32768,
10
      "availability_status": "available",
11
      "capabilities": {
12
        "input": ["text", "image"],
13
        "output": ["text", "tool_use"],
14
        "supports_tool_calling": true,
15
        "supports_tool_choice": true,
16
        "supports_structured_outputs": true,
17
        "streaming": true
18
      },
19
      "service_tiers": ["standard", "flex"],
20
      "pricing": {
21
        "input_per_million": 2.5,
22
        "output_per_million": 10,
23
        "currency": "USD",
24
        "flex": { "input_per_million": 1.25, "output_per_million": 7.5 }
25
      }
26
    }
27
  },
28
  "availability_status": "available",
29
  "created_at": "2025-05-14T00:00:00Z",
30
  "updated_at": "2026-03-01T00:00:00Z"
31
}

Use GET /models?model=<provider/model_id> when you want one specific model object but prefer a query parameter over a path parameter. The slash is fine there because it is part of the query parameter value.

Vendors API shape

GET /vendors returns execution hosts, not canonical model owners.

Example:

1
{
2
  "vendor": "bedrock",
3
  "name": "AWS Bedrock",
4
  "models": [
5
    "anthropic/claude-opus-4-6",
6
    "google/gemma-3-27b-it"
7
  ],
8
  "supports_zdr": true,
9
  "supports_byok": true,
10
  "availability_status": "active"
11
}

Pagination

GET /models and GET /vendors return a paged list envelope:

1
{
2
  "object": "list",
3
  "data": [ ... ],
4
  "has_more": true,
5
  "next_cursor": "mistral/magistral-medium-2509-thinking"
6
}

limit sets the page size. It defaults to 50 and caps at 500. A higher value is rejected before the request reaches the catalog:

1
HTTP 422
2
{
3
  "detail": [
4
    {
5
      "type": "less_than_equal",
6
      "loc": ["query", "limit"],
7
      "msg": "Input should be less than or equal to 500",
8
      "input": "1000",
9
      "ctx": { "le": 500 }
10
    }
11
  ]
12
}

Do not size a single request to the catalog. The catalog grows as models are added, so a limit that fits today silently starts truncating later. Page instead: send the previous response’s next_cursor back as cursor and keep going while has_more is true. The next page starts after the cursor entry, so pages never overlap, and next_cursor is null on the last page. Treat the cursor as opaque, a value to pass back rather than one to construct.

1
import requests
2
3
BASE = "https://api-gateway.merge.dev/v1"
4
headers = {"Authorization": "Bearer YOUR_API_KEY"}
5
6
models, cursor = [], None
7
while True:
8
    params = {"limit": 500}
9
    if cursor:
10
        params["cursor"] = cursor
11
    page = requests.get(f"{BASE}/models", headers=headers, params=params).json()
12
    models.extend(page["data"])
13
    if not page["has_more"]:
14
        break
15
    cursor = page["next_cursor"]
16
17
print(len(models))

$
# First page
$
curl "https://api-gateway.merge.dev/v1/models?limit=500" \
>
  -H "Authorization: Bearer YOUR_API_KEY"
$
$
# Next page: pass the previous response's next_cursor
>
curl "https://api-gateway.merge.dev/v1/models?limit=500&cursor=mistral/magistral-medium-2509-thinking" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Filters do not carry across pages on their own, so repeat provider or vendor on every request in the loop alongside cursor. Fetching one model with ?model=<provider/model_id> returns a bare model object rather than a list envelope, so it has no has_more or next_cursor.

The Management API paginates separately and caps its list endpoints at 100 per page: GET /v1/keys takes offset and limit and reports has_more, and GET /v1/projects takes cursor and limit.

Responses

POST /responses returns the canonical model that served the request and a top-level vendor field for the execution host that actually handled it.

Request parameters

Beyond the message input, the request accepts these optional fields:

OpenAI Responses API clients

POST /responses speaks Gateway’s native shape. OpenAI’s Responses API is served at POST /openai/responses, and that is where OpenAI-wire clients (the OpenAI SDK’s client.responses.*, Codex) should point. Three behaviors keep a client that reaches the native endpoint by mistake from failing silently:

• Codex is served the OpenAI shape automatically. Codex tags every request with an originator: codex_* header; a POST /v1/responses carrying it is served by POST /v1/openai/responses, so Codex works whether its base URL ends in /v1 or /v1/openai. The documented base URL is still /v1/openai.
• X-Merge-Wire-Format selects the shape explicitly. X-Merge-Wire-Format: openai on POST /v1/responses returns the OpenAI Responses shape for any caller; X-Merge-Wire-Format: native pins the native shape and overrides the Codex detection. Any other endpoint ignores the header.
• OpenAI-only request fields are translated, not dropped. On the native endpoint, instructions becomes a leading system message, reasoning.effort is applied as the reasoning effort for the route that serves the request, text.format becomes response_format, and max_output_tokens is an alias of max_tokens. An explicit native field wins over its OpenAI counterpart (thinking over reasoning, response_format over text.format). parallel_tool_calls is accepted without effect. Any other OpenAI-only field (truncation, include, background, prompt_cache_key, …) is ignored and reported in the response’s warnings with code openai_fields_ignored, so a misrouted client can see which settings did not apply:

1
"warnings": [{
2
  "code": "openai_fields_ignored",
3
  "message": "Request fields with no native Responses API equivalent were ignored: truncation. Clients speaking the OpenAI Responses wire format (Codex, the OpenAI SDK) should call /v1/openai/responses, or send X-Merge-Wire-Format: openai.",
4
  "detail": { "ignored_fields": ["truncation"], "openai_compat_path": "/v1/openai/responses" }
5
}]

On streaming requests the warning rides on the final response.done chunk. An unknown reasoning.effort level or a malformed text.format is rejected with 400, exactly as on POST /openai/responses.

Served tier and billing

The response echoes a top-level service_tier: the tier that actually served the request and the rate you were billed at. On a throttle fallback this differs from the tier you sent (e.g. you requested flex but were served and billed at standard).

1
{
2
  "model": "openai/gpt-5.4",
3
  "vendor": "openai",
4
  "service_tier": "flex",
5
  "usage": { "input_tokens": 812, "output_tokens": 180, "total_tokens": 992, "cost": 0.00219 }
6
}

See Service tiers for the full flow, supported vendor routes, and fallback behavior.

Per-call cost

Every response carries usage.cost: the provider cost in USD that Gateway computed for that call, from the tokens above and the pricing of the route that actually served the request. No request parameter is needed.

1
"usage": { "input_tokens": 812, "output_tokens": 180, "total_tokens": 992, "cost": 0.00219 }

usage.cost is returned on:

Three details worth knowing:

• cost is null, never 0, when the served route has no pricing on file. A false zero would be recorded as real spend by anything summing costs, so an unknown price is reported as unknown. Cost-tracking tools that read this field, such as Langfuse, skip a null instead of logging $0.
• It is the same figure as routing.cost_usd, which is only returned when you set include_routing_metadata: true. Both come from the same calculation, so a request that asks for both sees them agree. Use usage.cost for everyday cost tracking and routing metadata when you also need the policy and vendor decisions behind the call.
• It is provider cost, not your invoiced amount. The two can differ, and the invoice is the authority. Billing starts from this figure and then applies your organization’s plan rate, prices BYOK requests against the model’s list price rather than what your own provider account charged, and adds server-tool charges such as web search, which never appear in usage.cost.

Cost reflects the tier that served the request, so a flex request that fell back to standard is priced at standard. For invoiced spend, budgets, and dashboards, see Cost governance and savings.