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 from the generated catalog.
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.

Client protocol selection

Client	Recommended Compose protocol	Important setting
OpenCode	Responses	Use the `@ai-sdk/openai` provider returned by `/.well-known/opencode`; it targets `/responses`.
OpenClaw	Responses or Chat	Select `openai-responses` for native Responses; select `openai-completions` only for Chat.
Hermes	Chat by default	Generic custom endpoints default to `chat_completions`; opt into `codex_responses` explicitly when supported by your Hermes configuration.

“OpenAI-compatible” alone does not select a dialect. Tool definitions, streaming events, call identifiers, and tool-result continuation must all use the same protocol for the whole turn.

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": "<model-id>",
    "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.

<model-id>            -> <priority-provider> / <model-id>
<provider>/<model-id> -> <provider> / <model-id>

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

Client protocol selection

Basic request

Model aliases

Diagnostic headers

​What external routes do

​Client protocol selection

​Basic request

​Model aliases

​Diagnostic headers

​Related

What external routes do

Client protocol selection

Basic request

Model aliases

Diagnostic headers

Related