Add fallbacks

Send an ordered list

Replace model with models. Router tries the candidates in order and returns the first success:

curl "https://router-api.ramp.com/v1/responses" \
  -H "Authorization: Bearer $RAMP_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      "openai:gpt-5.4-mini",
      "fireworks:accounts/fireworks/models/deepseek-v4-flash",
      "fireworks:accounts/fireworks/models/kimi-k2p7-code"
    ],
    "input": "Return the order total as JSON."
  }'

The list holds 1–15 candidates your key is authorized for.

When Router advances

Router moves to the next candidate after a rate limit, a provider 5xx, a network failure, a timeout, or a stream that fails before it starts. It does not retry a candidate it already tried.

Invalid requests and unauthorized models fail immediately without touching the rest of the list, since retrying them on another provider would fail the same way.

If every candidate fails, Router returns a non-2xx error whose message summarizes what it tried.

Streaming

Router can switch models right up until the client receives 200 text/event-stream. After that the response is committed and a mid-stream provider failure ends the stream.

Bound both halves of that window explicitly:

{
  "models": [
    "openai:gpt-5.4-mini",
    "fireworks:accounts/fireworks/models/kimi-k2p7-code"
  ],
  "input": "Explain the result.",
  "stream": true,
  "timeout_before_headers": 10,
  "provider_timeout": 60
}

timeout_before_headers caps startup, so a low value fails over to the next model sooner. See Timeouts.

Before production

Every candidate has to support the tools, input types, and output schema your request uses. Otherwise the fallback fails on the feature rather than the outage you added it for — check the capability table first.

Set your client deadline long enough for Router to walk the whole list, not just to call one model.