External OpenAI-compatible clients

Use external routes when a client asks for an OpenAI-compatible base URL. That includes IDEs and coding agents such as OpenCode, Cline, and Zed, plus SDKs like AI SDK. Use this base URL:

https://api.compose.market/external/v1

Authenticate with a Compose Key:

Authorization: Bearer compose-...

What external routes do

Behavior	External route
Model IDs	Public catalog IDs such as `gpt-5.5` and `openai/gpt-5.5`.
Auth	Compose Key bearer auth only.
Payment	Prepared and settled by Compose behind the route.
Response shape	OpenAI-compatible JSON and SSE.
Receipts	Kept out of bodies and streams; native clients can use `/v1/*` for receipt bodies.
Diagnostics	Provider/model headers are exposed when safe.

The model IDs are the same public IDs returned by the generated catalog. No provider|model syntax, no hidden provider field.

Basic request

curl https://api.compose.market/external/v1/chat/completions \
  -H "Authorization: Bearer $COMPOSE_MARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Write a deployment note." }
    ]
  }'

Model aliases

When multiple providers expose the same upstream model ID, the generated catalog keeps the priority winner on the bare ID and gives non-primary rows a provider-prefixed public ID.

gpt-5.5         -> azure / gpt-5.5
openai/gpt-5.5  -> openai / gpt-5.5

This keeps the model list readable while still allowing exact provider selection.

Diagnostic headers

External responses can include:

Header	Meaning
`x-public-model`	Public model ID from the request.
`x-upstream-provider`	Provider selected by catalog resolution.
`x-upstream-model`	Provider model ID sent to the adapter.

These headers are useful when a provider rejects a request, rate limits, or applies its own content filter. They tell you which catalog row actually ran.

Overview

External Use

Families

Modalities

Guides

External OpenAI-compatible clients

What external routes do

Basic request

Model aliases

Diagnostic headers

​What external routes do

​Basic request

​Model aliases

​Diagnostic headers

​Related

What external routes do

Basic request

Model aliases

Diagnostic headers

Related