# Switchboard developer docs

> One hub key. Provider secrets stay in the cell. Response `data` is still the third party’s shape — Switchboard wraps it with `meta` (cost, price, request id, outcome).

**For coding agents:** start at [`/llms.txt`](../marketing/public/llms.txt) (or this folder’s [`llms.txt`](./llms.txt)), then load [`openapi.yaml`](./openapi.yaml). Prefer Markdown pages linked from `llms.txt` over scraping HTML.

## Quick start

1. Mint a caller key in Control Room (scopes = connectors / models you need) and publish LKG.
2. Set env:

```bash
SWITCHBOARD_BASE_URL=https://us1.switchboard.example   # no trailing slash
SB_KEY=sb_live_…                                       # or SWITCHBOARD_API_KEY
```

3. Call (hub-native):

```bash
curl -sS "$SWITCHBOARD_BASE_URL/v1/call/twilio.send_sms" \
  -H "Authorization: Bearer $SB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sms-1" \
  -d '{"To":"+15550192","Body":"hi"}'
```

4. Or use thinking tiers (recommended for product AI):

```bash
curl -sS "$SWITCHBOARD_BASE_URL/v1/proxy/switchboard/chat/completions" \
  -H "Authorization: Bearer $SB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"thinker","messages":[{"role":"user","content":"hi"}],"max_tokens":64}'
```

## Choose a mode

| Mode | Path | When |
|---|---|---|
| Thinking tiers (A0) | `/v1/proxy/switchboard/…` | One model knob: `anybody` / `thinker` / `expert` |
| Provider proxy (A) | `/v1/proxy/{connector}/…` | Keep Anthropic / OpenAI / Gemini / Mistral SDKs |
| Hub-native (C) | `/v1/call/{connector}.{op}` | Stripe, Twilio, Buffer, HubSpot, … |
| MCP | `POST /v1/mcp` | Agents / tool loops |
| OpenAI-compat (B) | `/v1/chat/completions` | Smoke only — raw JSON + `SB-*` headers |

## Doc map

| Page | Audience |
|---|---|
| [authentication.md](./authentication.md) | Keys, OAuth, scopes |
| [call-modes.md](./call-modes.md) | Modes A0/A/B/C + proxy baseURL rules |
| [envelope.md](./envelope.md) | `data` / `meta` / `error` |
| [headers.md](./headers.md) | `SB-*`, idempotency, region |
| [errors.md](./errors.md) | Error codes + retry rules |
| [mcp.md](./mcp.md) | Agent JSON-RPC tools |
| [sdk-typescript.md](./sdk-typescript.md) | `@switchboard/sdk` |
| [agents.md](./agents.md) | How coding agents should use these docs |
| [changelog.md](./changelog.md) | API / envelope change log and deprecation policy |
| [openapi.yaml](./openapi.yaml) | Machine-readable API contract |

## Hard rules (do not skip)

- Apps authenticate **only** with Switchboard. Do not put OpenAI / Stripe / Twilio keys in product repos when the hub owns the hop.
- Do **not** point Anthropic / Google / Mistral SDKs at `{cell}/v1` (OpenAI-compat). Use `/v1/proxy/{connector}`.
- Do **not** double version prefixes on proxy `baseURL` (see [call-modes.md](./call-modes.md)).
- On envelope errors, `data` is `null` and `error` is set — never treat “has meta” as success.
- Side-effect ops need `Idempotency-Key`.