Docs

Call modes

Thinking tiers, proxy, hub-native, MCP, OpenAI-compat.

Pick by how much vendor SDK surface you want to keep. Auth is always Switchboard Bearer.

Mode A0 — Thinking tiers (recommended for product AI)

POST /v1/proxy/switchboard/chat/completions
Authorization: Bearer sb_…
Content-Type: application/json

{ "model": "thinker", "messages": [{ "role": "user", "content": "…" }] }

Model id	Intent
`anybody`	Cheap / fast ladder
`thinker`	Default product AI
`expert`	Highest quality ladder

Gateway walks the configured ladder, injects house (or BYOK) credentials, bills price from pricebook://switchboard/chat/{tier}, and records cost from the resolved provider’s pricebook row. See meta.resolved_connector / meta.resolved_model.

SDK helper: switchboardTiersBaseUrl(cell) → {cell}/v1/proxy/switchboard.

Mode A — Per-provider proxy

Keep Anthropic / OpenAI / Gemini / Mistral / xAI SDKs. Set baseURL to {cell}/v1/proxy/{connector} and auth with the Switchboard key (use createProxyFetch to unwrap envelopes).

Provider	SDK `baseURL`	SDK appends	Full path
Switchboard tiers	`{CELL}/v1/proxy/switchboard`	`/chat/completions`	`/v1/proxy/switchboard/chat/completions`
Anthropic	`{CELL}/v1/proxy/anthropic`	`/messages`	`/v1/proxy/anthropic/messages`
OpenAI	`{CELL}/v1/proxy/openai`	`/chat/completions`, `/embeddings`, …	`/v1/proxy/openai/…`
Google	`{CELL}/v1/proxy/google`	`/models/{id}:generateContent`	`/v1/proxy/google/models/…`
Mistral	`{CELL}/v1/proxy/mistral`	`/chat/completions`	`/v1/proxy/mistral/chat/completions`

Critical — do not double the version prefix

Vendor connectors already include /v1 or /v1beta in base_url. If you set Anthropic baseURL to {CELL}/v1/proxy/anthropic/v1, the SDK appends /messages and the upstream path breaks.

Wrong: {CELL}/v1/proxy/anthropic/v1

Right: {CELL}/v1/proxy/anthropic

JSON responses are Switchboard envelopes. SSE streams stay raw; hub facts on SB-* headers. createProxyFetch unwraps success data for vendor SDKs.

Mode C — Hub-native call

POST /v1/call/{connector}.{op}

Named ops from connector.yaml (e.g. stripe.create_payment_intent, twilio.send_sms, buffer.create_post). No vendor SDK required. Always enveloped for JSON.

Side-effect / hub-idempotent ops require Idempotency-Key.

Mode MCP — Agents

POST /v1/mcp

JSON-RPC tools/list + tools/call. See mcp.md.

Mode B — OpenAI-compat (narrow)

POST /v1/chat/completions
POST /v1/embeddings

Returns raw OpenAI JSON + SB-* headers. Pinned to gateway -llm (often echo locally). Do not use for multi-provider products; do not point non-OpenAI SDKs here.

Decision guide

If you…	Use…
Want one model knob for cost/quality	Thinking tiers
Already have Anthropic/OpenAI/Gemini SDKs	Provider proxy + `createProxyFetch`
Need Stripe / Twilio / Buffer / HubSpot / …	`/v1/call/…`
Building an agent with tools	`POST /v1/mcp`
Customer brings their own provider key	BYOK capture link (config) — same `SB_KEY` on calls