switchback — part of the aimock family private · pre-launch

Providers

Five wire dialects, five adapters, fourteen bundled host profiles. The list is the easy part. What you actually need on your screen is which request features survive a cross-dialect leg unchanged, which are coerced into range, which are discarded (with or without a trace in the report), and which skip the leg before a single byte leaves your process.

The five dialects

Every upstream declares exactly one dialect. It is a full round trip: request translation, response parsing, and stream normalization back into the OpenAI shape your client already speaks. These five values are the complete set, and anything else is a hard config load error.

dialect Upstream wire surface Credential placement Request shape
openai-compat /v1/chat/completions authorization header passthrough
anthropic-messages /v1/messages x-api-key header translated
gemini-generate Gemini generateContent x-goog-api-key header translated
bedrock-converse Bedrock Converse SigV4 signature (no header injected) translated
cohere-chat Cohere chat authorization header translated

openai-compat is the passthrough dialect: the body relays with the model id swapped, plus the fidelity pass described below. That is why any OpenAI-compatible host works without translation: OpenAI itself, Azure, Groq, Together, Fireworks, OpenRouter, or Ollama's /v1 surface. The other four are real translations, and a report that says "translated": true is telling you exactly one thing: this leg was not openai-compat.

Declaring an upstream

An upstream is an entry in route.upstreams, keyed by the name you will use in route.models and in a route's chain. Three fields matter for this page; the rest of the schema lives in Configuration.

dialect enum required

One of the five values above. It selects the adapter: the translation, the parser, and the capability rules in the matrix below.

profile string optional default: openai

A bundled host profile id. It carries the per-host quirks (error envelope grammar, retry-after header formats, stream envelope shape, rejected params) and it supplies the provider attribution label. An unknown id is a hard load error.

auth object or null optional default: keyless

Exactly { "env": "VAR_NAME" }, or { "file": "/path/to/key" }, or null for a keyless upstream. Nothing else: a bare string is refused, an extra key is refused, and a value that looks like a credential is refused without echoing it. Every example on this page names an environment variable, never a key. See Security for file modes, caller keys, and header forwarding.

unlistedModels is also an upstream-level field ("verbatim", "strip-author", or "none") and it affects which legs a request can expand into; Routing covers that expansion.

What can happen to a request feature

This is the distinction the rest of the page hangs on, and it is worth learning once because each outcome is visible in a different place, and one of them is visible nowhere at all. Read every table cell below against these five words.

Separately from all five, request content has a sixth outcome: rejected pre-flight, and the leg is skipped. Multimodal content that cannot be expressed on the target dialect stops the leg before the request is built, at zero cost and with no network call. The leg is classified retryable(translated_bad_request), marked as not dispatched, and annotated unsupported_content. A model answering about an image it was never sent would be a correctness bug, so the content is never quietly discarded instead.

Two mechanisms produce those outcomes, and knowing which one owns a param tells you whether a drop will be annotated. The fidelity engine owns the sampling knobs: it drops what a dialect cannot express, clamps what is out of range, and returns the annotations. It runs in a fixed order, and later steps see the earlier ones' results:

  1. the host profile's rejectedParams;
  2. sampling params the dialect cannot express;
  3. platform extras the dialect cannot express;
  4. the tool_choice drop;
  5. the Anthropic extended-thinking special case;
  6. range clamps.

Each adapter owns the structural params (max_tokens, stop, top_k, top_p, tools, response_format) by explicit name mapping, and the engine neither drops nor clamps those. That split is the source of every silent drop on this page: a param the engine keeps and the adapter does not map vanishes with nothing recorded. It is not that structural params are safe; it is that nothing is watching them.

Warning

dropped_params and clamped_params are per-leg fields on the routing report, and the routing report reaches you through exactly one surface: the onRequestComplete observer hook, plus the bundled journal observer that persists what the hook carries. They are not response headers. The x-switchback-* set is upstream, dialect, attempts, budget-overflow and budget-remaining, and nothing else. So an HTTP client calling switchback cannot see that its sampling params were edited; only an operator reading the journal, or code wired into the hook, can. See Observability.

Capability matrix

Read the rows as dialects and the columns as things your client might send. Every cell is the adapter's actual behavior, verified against the wire body the adapter builds. Where a cell says annotated, the report will also tell you after the fact; where it says silently, the report will not, and the cell is the only warning you get.

Request features

dialect tool_choice reasoning image, base64 data URI image, data URI without base64 image, https URL input_audio file / document transforms / route
openai-compat Yes Yes, kept Yes Yes Yes Yes Yes Only on the openrouter profile
anthropic-messages Yes Translated to thinking Yes Leg skipped Yes, fetched upstream Leg skipped Leg skipped Dropped
gemini-generate Yes Dropped Yes Leg skipped Leg skipped Leg skipped Leg skipped Dropped
bedrock-converse Yes Dropped Four formats only Leg skipped Leg skipped Leg skipped Leg skipped Dropped
cohere-chat Dropped Dropped Yes Leg skipped Leg skipped Leg skipped Leg skipped Dropped

Where each of those columns maps to, when it is expressible:

Sampling parameters

Three outcomes, not two. Forwarded means the value reaches the upstream, under that dialect's own field name where it differs. Dropped, annotated means the fidelity engine removed it and listed it in dropped_params. Dropped, silently means the engine kept it, the adapter's wire body never mentions it, and no report field records it: the value you sent reached nothing, and nothing told you.

Param openai-compat anthropic-messages gemini-generate bedrock-converse cohere-chat
logprobs Forwarded Dropped, annotated Dropped, annotated Dropped, annotated Dropped, annotated
top_logprobs Forwarded Dropped, annotated Dropped, annotated Dropped, annotated Dropped, annotated
logit_bias Forwarded Dropped, annotated Dropped, annotated Dropped, annotated Dropped, annotated
n Forwarded Dropped, annotated Dropped, annotated Dropped, annotated Dropped, annotated
frequency_penalty Forwarded Dropped, annotated defect Dropped, silently Dropped, annotated Forwarded, unclamped
presence_penalty Forwarded Dropped, annotated defect Dropped, silently Dropped, annotated Forwarded, unclamped
seed Forwarded Dropped, annotated defect Dropped, silently Dropped, annotated Forwarded

Known defect

The three gemini-generate cells above are the page's own correction. Gemini can express all three (frequencyPenalty, presencePenalty and seed are real generationConfig fields), and the fidelity engine keeps them because they are not on Gemini's unexpressible list. But the adapter's generationConfig mapper writes only temperature, topP, topK, maxOutputTokens and stopSequences, and the request body is a closed set, so all three vanish with no dropped_params entry. An earlier version of this page listed them as kept, and for the penalties as carrying "no clamp", which reads as forwarded unclamped. They are not forwarded at all. Until the mapper is fixed, do not send penalties or a seed to a Gemini leg and expect either effect or a warning.

Structural parameters

These are name-mapped by each adapter rather than handled by the fidelity engine, so the engine never drops or clamps them and never annotates anything about them. That is exactly why the silent cells below are silent.

Param openai-compat anthropic-messages gemini-generate bedrock-converse cohere-chat
max_tokens Forwarded injected max_tokens, defaulted to 4096 when you omit it maxOutputTokens inferenceConfig.maxTokens max_tokens
stop Forwarded stop_sequences stopSequences stopSequences, non-strings filtered stop_sequences
top_p Forwarded top_p topP inferenceConfig.topP p
top_k Forwarded defect Dropped, silently topK defect Dropped, silently k
tools Forwarded Translated functionDeclarations toolConfig.tools, suppressed when tool_choice: "none" Translated
response_format Forwarded defect Dropped, silently defect Dropped, silently defect Dropped, silently Forwarded

Known defect

top_k and response_format are the two structural params with silent cells, and both matter more than a merely unexpressible param would. top_k is supported by Anthropic's Messages API and expressible on Bedrock through additional model fields, so this is capability lost to an incomplete mapping rather than a dialect limitation. response_format is worse in effect: a request that asks for JSON gets prose back from an Anthropic, Gemini or Bedrock leg while the same request gets JSON from an openai-compat or Cohere leg, and nothing in the report distinguishes the two. If your chain mixes dialects and your caller parses the response, constrain the chain rather than relying on response_format.

Clamp ranges

A value outside the dialect's legal range is clamped to the nearest legal value and annotated in clamped_params. A range in a cell means the param is forwarded, clamped to those bounds if it falls outside them. Only temperature and top_p have declared bounds on any dialect; top_k has none anywhere, so where it is mapped at all it rides verbatim.

dialect temperature top_p frequency_penalty presence_penalty
openai-compat 0 – 2 0 – 1 -2 – 2 -2 – 2
anthropic-messages 0 – 1 0 – 1 Dropped, annotated Dropped, annotated
gemini-generate 0 – 2 0 – 1 defect Never reaches the wire: dropped silently, so there is nothing to clamp defect Never reaches the wire: dropped silently, so there is nothing to clamp
bedrock-converse 0 – 1 0 – 1 Dropped, annotated Dropped, annotated
cohere-chat 0 – 1 0 – 1 Forwarded, no clamp Forwarded, no clamp

Note

"Forwarded, no clamp" on the Cohere row is a real exposure rather than a neutral choice. The canonical scale for both penalties is OpenAI's -2 to 2, so a value that is legal for your client is forwarded untouched and Cohere decides whether to accept it. A servable leg can therefore become an upstream 400 that a declared range would have prevented. Note the asymmetry with the Gemini row directly above it: same "no clamp" wording in the old table, two completely different behaviors.

Warning

Clamping is not rescaling. temperature: 0.7 against a dialect whose ceiling is 1 stays 0.7. It is not remapped to 0.35 to preserve its position on the 0–2 scale. A chain that crosses from a 0–2 dialect to a 0–1 dialect therefore changes the effective sampling behavior of the same request, and only a value actually outside the range shows up in clamped_params: an in-range value is byte-identical on every leg and is recorded nowhere, correctly.

Reasoning and extended thinking

The reasoning control is OpenRouter's unified reasoning knob. On openai-compat it is kept. On anthropic-messages it is translated into an Anthropic thinking block, enabled whenever reasoning is a non-null object that does not set enabled: false. On gemini-generate, bedrock-converse and cohere-chat it is dropped and annotated.

Note

Anthropic forbids a non-default temperature or top_p while thinking is on, so when the router turns thinking on it drops both and annotates them. If you send reasoning and temperature together and then wonder why your temperature had no effect on the Anthropic leg, that pair of dropped_params entries is the answer.

Reasoning output is normalized in the other direction regardless of whether you could ask for it: Anthropic thinking blocks, Gemini thought parts and Cohere thinking blocks all come back to your client as message.reasoning_content.

Content forms and the pre-flight skip

Expressibility is decided by the form of the content part, not by its size or its media type alone. The check runs before the request is built and it never fetches a URL, so it costs nothing and it cannot be fooled by a host that would have 404ed anyway.

Form What it looks like Notes
data data:<mediatype>;base64,<payload> A genuine base64 data URI. Expressible on all five dialects for images.
data-raw a data: URI with no ;base64, No extractable bytes, so only openai-compat can relay it. Everything else skips the leg.
url https:// or http:// openai-compat relays it; Anthropic accepts it and fetches it itself. Gemini, Bedrock and Cohere cannot take a URL.
other relative, protocol-relative, or malformed Inexpressible on every dialect, including openai-compat.

When a form is inexpressible the report names it, so you can tell the four cases apart without guessing: image_url(https), image_url(data), image_url(format), image_url(unsupported), input_audio, file, file(url), and file(unsupported).

Audio and files are the blunt cases. input_audio is carried by openai-compat and by nothing else; file and document parts likewise, in all three URI forms. The four translated dialects declare both unsupported on purpose. Some of those providers can carry audio, but these adapters do not emit it, and declaring it expressible would make the content vanish instead of skipping the leg.

Warning

A pre-flight skip only helps you if the chain is allowed to move on. Put translated_bad_request in a route's policy.advanceOn whenever any non-openai-compat upstream is in that chain. Otherwise the skip surfaces to your client as an error instead of advancing to the next leg. See Routing.

Host profiles

A profile is declarative per-host quirk data, one JSON file per host, selected by id. No provider grammar is hard-coded in the classifier, which is why a new host's error shape is a data change rather than a code change. Fourteen profiles ship in the box:

openai, anthropic, gemini, bedrock, cohere, openrouter, groq, mistral, perplexity, cerebras, sambanova, alibaba, zai, moonshot. openai is the default and the fallback.

Profile field What it carries
id The value you write in profile, and the attribution label.
errorShape Where the message, code and metadata live in this host's error envelope, plus status-to-reason hints and the moderation-flag path.
rateLimitHeaders Which headers carry retry-after, and in which format: seconds, http-date, milliseconds, duration-string, epoch-seconds, epoch-millis.
streamEnvelope Stream quirks: where final usage arrives, whether a done sentinel is sent.
toolCallIdFormat openai-call, mistral-9char, or synthesized.
rejectedParams Params this host refuses, pre-dropped with an annotation.
extraResponseFields Non-standard response fields to carry through instead of discarding.
usageExtensions Where this host reports cost, cost details, and a bring-your-own-key flag.

The openrouter profile is the fullest worked example: it reads the message from error.message and the code from error.code, treats 402 and 403 as auth_budget, walks a three-step retry-after chain from retry-after through x-ratelimit-reset-requests to x-ratelimit-reset-tokens, expects final usage in the last stream chunk plus a done sentinel, carries reasoning_details through, and reads cost out of usage.cost.

The cerebras profile is the fullest rejectedParams example. It rejects logprobs, top_logprobs, logit_bias, frequency_penalty, presence_penalty and n. Those are dropped and annotated before the dialect pass even runs, which is how an openai-compat leg can still report a drop.

Note

The profile also supplies the provider attribution you see in the report and in the response's provider field: it is the profile id if the upstream has one, otherwise the upstream's own name. An upstream you named stub with "profile": "openai" reports "provider": "openai".

Per-adapter notes

openai-compat

The passthrough path, and the only dialect with no capability gaps. Point baseURL at any OpenAI-shaped host and pick the profile that matches it. The dialect governs translation, the profile governs quirks, and they are independent choices. It is also the only dialect that carries audio parts, file parts and data: URIs without base64.

two openai-compat upstreams, different profiles json
"openai-direct": {
  "baseURL": "https://api.openai.com/v1",
  "dialect": "openai-compat",
  "profile": "openai",
  "auth": { "env": "OPENAI_API_KEY" }
},
"cerebras-fast": {
  "baseURL": "https://api.cerebras.ai/v1",
  "dialect": "openai-compat",
  "profile": "cerebras",   // pre-drops logprobs, penalties, n
  "auth": { "env": "CEREBRAS_API_KEY" }
}

anthropic-messages

Credential goes in x-api-key, resolved from this upstream's own auth reference. The Anthropic API is versioned by header, so set anthropic-version in the upstream's static headers.

upstream entry json
"anthropic-direct": {
  "baseURL": "https://api.anthropic.com",
  "dialect": "anthropic-messages",
  "profile": "anthropic",
  "auth": { "env": "ANTHROPIC_API_KEY" },
  "headers": { "anthropic-version": "2023-06-01" }
}

Gotchas specific to this leg:

gemini-generate

Credential goes in x-goog-api-key. tool_choice maps to toolConfig.functionCallingConfig. baseURL is yours to supply, since the router does not hard-code any provider endpoint.

upstream entry json
"gemini-main": {
  "baseURL": "<your Gemini API base URL>",
  "dialect": "gemini-generate",
  "profile": "gemini",
  "auth": { "env": "GEMINI_API_KEY" }
}

Gotchas specific to this leg:

bedrock-converse

The odd one out on credentials: nothing is injected as a header. The material behind this upstream's auth reference is handed to the SigV4 signer, which signs the Converse request itself. tool_choice maps to toolConfig.toolChoice.

upstream entry json
"bedrock-usw2": {
  "baseURL": "<your Bedrock runtime endpoint>",
  "dialect": "bedrock-converse",
  "profile": "bedrock",
  "auth": { "env": "BEDROCK_SIGNING_CREDENTIAL" }
}

Note

There is additional region and credential fallback behavior on this path that these docs do not describe, because we have not verified it end to end. Declare the upstream's auth reference explicitly rather than relying on ambient discovery, and confirm against a real request before you put a Bedrock leg in a production chain.

Gotchas specific to this leg:

cohere-chat

Credential goes in the authorization header. Base64 image data URIs work; everything else multimodal does not.

upstream entry json
"cohere-main": {
  "baseURL": "<your Cohere API base URL>",
  "dialect": "cohere-chat",
  "profile": "cohere",
  "auth": { "env": "COHERE_API_KEY" }
}

Gotchas specific to this leg:

A chain that crosses dialects

Nothing above requires you to think about dialects per request, which is the point. You declare the upstreams, map slugs onto them, and let one chain span vendors.

switchback.config.json json
{
  "route": {
    "listen": { "host": "127.0.0.1", "port": 4011 },
    "upstreams": {
      "openai-direct": {
        "baseURL": "https://api.openai.com/v1",
        "dialect": "openai-compat",
        "profile": "openai",
        "auth": { "env": "OPENAI_API_KEY" }
      },
      "anthropic-direct": {
        "baseURL": "https://api.anthropic.com",
        "dialect": "anthropic-messages",
        "profile": "anthropic",
        "auth": { "env": "ANTHROPIC_API_KEY" },
        "headers": { "anthropic-version": "2023-06-01" }
      },
      "groq-fast": {
        "baseURL": "https://api.groq.com/openai/v1",
        "dialect": "openai-compat",
        "profile": "groq",
        "auth": { "env": "GROQ_API_KEY" }
      },
      "cerebras-fast": {
        "baseURL": "https://api.cerebras.ai/v1",
        "dialect": "openai-compat",
        "profile": "cerebras",
        "auth": { "env": "CEREBRAS_API_KEY" }
      }
    },
    "models": {
      "gpt-4o": { "openai-direct": "gpt-4o" },
      "claude-sonnet-4-5": { "anthropic-direct": "claude-sonnet-4-5" },
      "llama-3.3-70b": {
        "groq-fast": "llama-3.3-70b-versatile",
        "cerebras-fast": "llama-3.3-70b"
      }
    },
    "routes": {
      "chat-default": {
        "match": {},
        "chain": ["gpt-4o", "claude-sonnet-4-5"],
        "policy": {
          "advanceOn": ["rate_limited", "server_error", "translated_bad_request"]
        }
      }
    }
  }
}

How that config behaves, feature by feature:

Known limits

Adding a provider does not add everything you might assume comes with it. These are the honest edges as of today.

Warning

The router is pre-launch and under active development. The dialect list, the capability rules and the config shape can all change, and the CLI says the same thing every time it starts.

Where to go next