API reference

The SwitchGate REST API, endpoint by endpoint. OpenAI-compatible at https://api.switchgate.ai/v1 — request and response shapes are stable for the public beta; fields marked preview may evolve. Prefer prose? Start with the guides.

Authentication
Chat completions
Models
Embeddings
API keys
Usage & ledger
Errors
Headers & limits

Authentication

All requests are authenticated with a bearer key against the base URL https://api.switchgate.ai/v1. Keys are created in the console (or via the keys API), belong to a named user, and carry that user's budgets and model locks. The API is OpenAI-compatible: official OpenAI SDKs work by changing base_url.

Authorization header

curl https://api.switchgate.ai/v1/models \
  -H "Authorization: Bearer sg-live-…"

POST/v1/chat/completions

Create a model response for a conversation. Works with every model in the catalog, switchgate/auto, and your own local/ or private/ models via the device agent.

Parameter	Type	Description
`model`required	string	Catalog ID like `anthropic/claude-sonnet-4-6`, `switchgate/auto`, or `local/<model>`.
`messages`required	array	Chat messages, OpenAI format: `[{"role":"user","content":"…"}]`. Multimodal content parts supported where the model supports them.
`stream`	boolean	Server-sent events when `true`. Final chunk includes usage and exact cost.
`temperature`	number	0–2, passed through to the provider. Provider defaults apply when omitted.
`max_tokens`	integer	Output cap, passed through.
`tools`	array	Tool definitions, OpenAI format; forwarded to models with tool support.
`sg_cache`	string	`"auto"` (default, exact-match), `"semantic"` (paraphrase matching, key must opt in) or `"off"`. Hits bill 0 credits.
`sg_fallbacks`	array	Ordered model IDs to fail over to on provider error or timeout, e.g. `["openai/gpt-5.2","google/gemini-3-pro"]`.
`metadata`	object	Up to 8 string key-values attached to the ledger trace (team, feature, ticket…).

Request — cURL

curl https://api.switchgate.ai/v1/chat/completions \
  -H "Authorization: Bearer sg-live-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [{ "role": "user", "content": "Bonjour!" }],
    "sg_fallbacks": ["openai/gpt-5.2"],
    "metadata": { "feature": "onboarding-bot" }
  }'

Response — 200

{
  "id": "cmpl-9f41c2",
  "object": "chat.completion",
  "created": 1786561200,
  "model": "anthropic/claude-sonnet-4-6",
  "provider": "anthropic",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Bonjour! Comment puis-je aider?" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21,
    "sg_cost_usd": 0.000171,
    "sg_cache": "miss"
  }
}

Streaming: with "stream": true the endpoint emits OpenAI-style SSE chunks; the terminal chunk carries the usage object including sg_cost_usd, so exact cost is available even on streams.

GET/v1/models

List every model your key can call — the public catalog minus your organization's locks, plus your private models. GET/v1/models/{id} returns one entry.

Response — 200 (truncated)

{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-sonnet-4-6",
      "object": "model",
      "provider": "anthropic",
      "context_window": 200000,
      "pricing": { "input_per_m_usd": 3.0, "output_per_m_usd": 15.0 },
      "modalities": ["text"],
      "locked_for_key": false
    },
    {
      "id": "private/acme/legal-qwen-72b",
      "object": "model",
      "provider": "device-agent",
      "pricing": { "input_per_m_usd": 0, "output_per_m_usd": 0 }
    }
  ]
}

POST/v1/embeddings

OpenAI-compatible embeddings across providers.

Parameter	Type	Description
`model`required	string	An embedding model ID, e.g. `openai/text-embedding-4`.
`input`required	string \| array	Text or array of texts to embed.
`dimensions`	integer	Requested vector size, where the model supports it.

POST/v1/keys

Create a key assigned to a user, with governance attached at birth. Requires an admin key. GET/v1/keys lists keys; POST/v1/keys/{id}/revoke kills one instantly.

Parameter	Type	Description
`name`required	string	Human label shown on the ledger.
`user_email`required	string	The named person (or service identity) this key belongs to.
`monthly_budget_usd`	number	Spend cap enforced before purchase. Omit to inherit the user's budget.
`allowed_models`	array	Model lock list; requests outside it return `403 model_locked`.
`prepaid_usd`	number	Makes the key burnable: fixed balance, stops at zero.
`expires_at`	string	ISO 8601; the key self-revokes at this moment.

Request — cURL

curl https://api.switchgate.ai/v1/keys \
  -H "Authorization: Bearer sg-admin-…" \
  -d '{
    "name": "workshop-badge-042",
    "user_email": "[email protected]",
    "prepaid_usd": 5,
    "expires_at": "2026-09-01T00:00:00Z",
    "allowed_models": ["deepseek/deepseek-v3.2", "openai/gpt-5-mini"]
  }'

GET/v1/usage

The ledger, queryable. Sums always reconcile to billing to the cent.

Parameter	Type	Description
`from / to`	string	ISO 8601 window; defaults to the current month.
`group_by`	string	`user`, `key`, `model`, `provider` or `metadata.<field>`.
`format`	string	`json` (default) or `csv` for the finance team.

Response — 200 (grouped by user)

{
  "from": "2026-08-01T00:00:00Z",
  "to": "2026-08-12T23:59:59Z",
  "groups": [
    { "user": "[email protected]", "requests": 18422, "cost_usd": 31.07, "cache_hits": 6120 },
    { "user": "[email protected]",   "requests":  9114, "cost_usd": 12.55, "cache_hits":  801 }
  ],
  "total_cost_usd": 43.62
}

Errors

Errors use conventional status codes with a machine-readable error.code. Anything the gateway retried on your behalf is annotated in the trace.

Status	Code	Meaning
400	`invalid_request`	Malformed body or unsupported parameter for this model.
401	`invalid_key`	Missing, revoked or expired key.
402	`insufficient_credits`	Org balance or a prepaid key hit zero.
403	`model_locked`	The key's model locks exclude this model.
403	`budget_exceeded`	Per-user or per-key budget cap reached.
404	`model_not_found`	Unknown model ID.
429	`rate_limited`	Provider or gateway rate limit; honor `retry-after`.
429	`breaker_tripped`	The runaway-agent kill switch paused this key; body includes the tripped rule.
502	`provider_error`	Upstream failure after retries and any `sg_fallbacks` were exhausted.
504	`provider_timeout`	Upstream exceeded the timeout after retries.

Response headers & limits

Header	Meaning
`x-request-id`	Trace ID; quote it to support and find it on the ledger.
`x-sg-cost`	Exact cost of this call in USD. `0` on cache hits and local models.
`x-sg-cache`	`hit`, `semantic-hit` or `miss`.
`x-sg-provider`	Provider that actually served the request (relevant with `auto` and fallbacks).
`x-sg-budget-remaining`	The calling user's remaining budget for the period, in USD.

Gateway rate limits are generous and per-organization; provider limits pass through. Idempotency: send an idempotency-key header on writes (key creation) to make retries safe.

Every endpoint, one key away

Free trial credits; the models list is a good first call.

Get API key Back to the docs