Embedded Routing Stack

Embedded Routing gives each of your end customers its own routing, vendor keys, and spend limits under your one organization. Use it when you resell Gateway to tenants without dashboard accounts. The /v1/customers endpoints take your organization-level key (Bearer mg_...), derive the organization from it, and use UUIDs for every ID. See the Embedded Routing API reference for schemas.

How the pieces fit

A request scoped to a Customer uses everything below it.

PUT /v1/customers/{customer_id}/controls sets per-customer vendor, region, and ZDR controls, which override organization settings and work like project-scoped controls: send only the fields you override, and DELETE to inherit again.

Sending requests

Set customer to the Customer’s id, send your own ID in the X-Merge-Customer-Origin-Id header (which creates the customer on first use), or use the customer’s API key. Routing then depends on model and routing_policy_id:

curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "9f8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "routing_policy_id": "2a1b3c4d-5e6f-4708-9a0b-1c2d3e4f5a6b",
    "input": [
      {"type": "message", "role": "user", "content": "Summarize this ticket in one sentence."}
    ]
  }'

The OpenAI, Anthropic, LangChain, and AI SDK surfaces accept both fields in the body; since those SDKs require a model, send default_routing to let the policy route. Any endpoint also accepts X-Merge-Customer and X-Merge-Routing-Policy-Id headers, which can’t override a customer API key’s scope. X-Merge-Customer is unrelated to the tracing tag X-Customer-ID.

Combining customer with a project scope (a project API key, X-Project-Id, or project_id) returns 400 customer_project_conflict. Non-streaming responses name the serving policy in x-merge-routing-policy-id.

Listing a customer’s allowed models

GET /v1/customers/{customer_id}/models returns what the customer can route to after its controls, key usage mode, and your organization’s vendor access apply, for use in a model picker.

{
  "scope": "customer",
  "scope_id": "9f8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "restrictions_active": true,
  "key_usage_mode": "byok_only",
  "models": [
    { "model": "openai/gpt-5.6-sol", "provider": "openai", "vendors": ["openai"] },
    { "model": "mistral/mistral-large-2512", "provider": "mistral", "vendors": ["mistral"] }
  ],
  "gated_model_ids": []
}

vendors lists the hosts that can serve each model; gated_model_ids are allowed by the customer’s controls but not your organization’s vendor access. key_usage_mode is lowercase here, uppercase on the Customer. GET /v1/models with a customer API key or X-Merge-Customer returns the same list.

Status codes

Streaming requests get these as HTTP statuses when the failure precedes the first token, and as an in-band response.error frame (Streaming) after.

Next steps