# Call modes

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

## Mode A0 — Thinking tiers (recommended for product AI)

```http
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

```http
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

```http
POST /v1/mcp
```

JSON-RPC `tools/list` + `tools/call`. See [mcp.md](./mcp.md).

## Mode B — OpenAI-compat (narrow)

```http
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 |