Merge API Documentation

A Customer is the object you provision for each of your end customers. It owns that customer’s routing policies, provider keys, and budget, and it is what you reference with the customer field on an LLM request. Create one per end customer, then attach its sub-resources.

Fields

Field	Description	Type
`id`	Merge UUID. Use as `customer` at request time	string
`origin_id`	Your unique ID for the customer, immutable	string
`name`	Customer name	string
`routing_policies`	The customer’s routing policy IDs	list of Merge UUIDs
`budgets`	The customer’s budget IDs	list of Merge UUIDs
`byok_configurations`	The customer’s provider key IDs	list of Merge UUIDs
`key_usage_default`	`USE_ANY`, `PREFER_BYOK`, or `BYOK_ONLY`	enum
`status`	`ACTIVE` or `INACTIVE`. An inactive customer’s requests are rejected	enum
`created_at`, `modified_at`	Timestamps	datetime

Relations are returned as lists of Merge UUIDs. Fetch a relation’s own endpoint (linked above) to read the full objects.

Create a customer

origin_id is your own identifier for the customer and must be unique within your organization. A duplicate returns 409.

cURL

$ curl -X POST https://api-gateway.merge.dev/v1/customers \
>   -H "Authorization: Bearer mg_<your_production_key>" \
>   -H "Content-Type: application/json" \
>   -d '{ "name": "Acme", "origin_id": "acme-corp" }'

The response includes the id. That id is what you send as the customer field on /v1/responses (see Sending requests).

Next, give the customer a routing policy, optionally a provider key, and a budget.

Look up a customer by your own ID

Every other call takes the Merge UUID, so store the id from the create response. If you only have your own origin_id, resolve it:

cURL

$ curl -X GET "https://api-gateway.merge.dev/v1/customers?origin_id=acme-corp" \
>   -H "Authorization: Bearer mg_<your_production_key>"

The response is the standard list envelope with the single matching customer (or empty results if none).

Manage the lifecycle

Deactivate a customer to stop serving its traffic without losing its configuration, then reactivate it later. Delete is irreversible, and a deleted customer’s ID stays fail-closed (its requests are rejected, never silently served with org defaults).

$ curl -X PATCH https://api-gateway.merge.dev/v1/customers/{customer_id} \
>   -H "Authorization: Bearer mg_<your_production_key>" \
>   -H "Content-Type: application/json" \
>   -d '{ "status": "INACTIVE" }'