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 }
6
}

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