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>

Key endpoints

Gateway’s public API surface is centered around three endpoint groups:

• GET /models
  • list models
  • filter by provider or vendor
  • fetch a single model by query string with ?model=<provider/model_id>
• GET /vendors
  • list execution vendors and the models they currently serve
  • fetch a single vendor with GET /vendors/{vendor_id}
• POST /responses
  • create an LLM response
  • the response includes the vendor that ultimately served the request and the service_tier that actually served it

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
}

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:

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.