Routing API

Select a provider for a request or save account preferences.

Fetch model providers

GET /providers returns selected_provider_chain in saved order and provider options in the current Auto order with auto_rank, success rates, limits, capabilities, and availability.

curl

curl https://api.closerouter.dev/v1/providers \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY"

Select a provider for one request

Pass provider as a string: auto, provider-1, provider-5, and so on.

curl

curl https://api.closerouter.dev/v1/chat/completions \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider": "provider-5",
    "messages": [
      { "role": "user", "content": "Reply with exactly: ok" }
    ],
    "max_tokens": 16
  }'

Save one provider

The provider field saves a one-provider chain.

curl

curl https://api.closerouter.dev/v1/providers \
  -X PATCH \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider": "provider-5"
  }'

Save a provider chain

PATCH /providers saves a strict account-level chain. provider_chain order is the attempt order for every account API key and the /models dashboard.

curl

curl https://api.closerouter.dev/v1/providers \
  -X PATCH \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider_chain": [
      { "name": "provider-5" },
      { "name": "provider-2" }
    ]
  }'

Return to Auto

provider: "auto" clears the saved chain and restores automatic selection.

curl

curl https://api.closerouter.dev/v1/providers \
  -X PATCH \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider": "auto"
  }'

Tier availability depends on the provider and model. Inspect service_tier in GET /providers, then use the desired provider.option_id or supported model suffix :flex, :default, :priority. Support at one provider does not imply support at another.

Service tier

Tier	Purpose
Flex	Lower price, potentially longer queue time.
Default	Standard processing.
Priority	Higher priority and price.

Auto and saved settings

Auto selects by price (cheap), speed (fast) or stability (stable). For one request, send provider: {"name":"auto","strategy":"fast"}. An explicit strategy cannot be combined with a specific provider or option_id.

In PATCH /providers, auto_strategy saves the model’s Auto setting; null or explicitly choosing the current account Auto restores inheritance. Omission preserves the setting. provider: "auto" also clears the manual chain. Auto does not substitute another tier for a selected Default when several tiers exist.

Settings precedence

Explicit request choice → manual chain → key Auto → model Auto → account Auto → Cheap. Explicit Auto in the request bypasses a manual chain; key Auto does not.

Chains are strict: the request fails after the last selected provider fails. provider.order refers to public model developers and does not define this chain. Changes apply to new requests.