# Switchboard

> Switchboard is a cell API that owns third-party credentials, egress, metering, and audit. Callers use `Authorization: Bearer sb_…` only. JSON ops return envelope `{ data, meta, error? }` where `data` is the provider payload. Prefer thinking tiers (`anybody`/`thinker`/`expert`) or provider proxy over OpenAI-compat for product AI.

Base URLs: prefer production/staging `https://{cell}` (e.g. `https://us1.switchboard.example`). Local gateway `http://127.0.0.1:8080` is for `make run-gateway` only — do not paste it into product code.

Auth: Bearer Switchboard key (`sb_…`) or OAuth JWT from `POST /oauth/token`. Never put provider API keys in app repos when the hub owns the hop.

Hard rules: do not double proxy version prefixes; do not point Anthropic/Google SDKs at `{cell}/v1`; on errors `data` is null — check `error`; side-effect ops need `Idempotency-Key`.

## Docs

- [OpenAPI 3.1](/openapi.yaml): Caller-facing HTTP contract (source of truth for paths/schemas)
- [Quick start](/docs/index.md): Mint key, env, first curl
- [Authentication](/docs/authentication.md): Keys, scopes, customer OAuth
- [Call modes](/docs/call-modes.md): Thinking tiers, proxy, /v1/call, MCP, OpenAI-compat
- [Envelope](/docs/envelope.md): data / meta / cost / price
- [Headers](/docs/headers.md): SB-* and Idempotency-Key
- [Errors](/docs/errors.md): Error codes and retry rules
- [MCP for agents](/docs/mcp.md): tools/list and tools/call on the cell
- [TypeScript SDK](/docs/sdk-typescript.md): @switchboard/sdk helpers
- [Guide for coding agents](/docs/agents.md): Discovery order, checklist, forbidden patterns
- Caller self-serve: `GET /v1/me/billing`, `GET /v1/me/explorer`, `/v1/me/webhooks/*` (marketing `/portal`)
- Public status: `GET /v1/public/status` (marketing `/status`)
- Test ring keys: `sb_test_*` → sandbox region or `SB_SIMULATOR_URL` (see authentication.md)
- API changelog: [changelog.md](/docs/changelog.md)
- Alerts: `ALERT_NOTIFY_URLS` comma-separated webhooks (Slack / PagerDuty / email relay)

## Optional

- [Full docs dump](/llms-full.txt): Concatenated Markdown for one-shot context
- [HTML docs](/docs): Human-readable pages
- [Envelope JSON Schema](/docs/envelope.schema.json): Response envelope schema