# Summa API — one key for every AI model, plus multi-model debate

Summa exposes OpenAI- and Anthropic-compatible endpoints. One API key gives access to
GPT-5, Claude, Gemini and 400+ other models, and to "debate" mode: a panel of models
each answer the prompt, then a moderator synthesizes them into one best answer.

## Base URLs and auth

- OpenAI-compatible base URL:    https://alpha.backend.summachat.com/api/v1
  - POST https://alpha.backend.summachat.com/api/v1/chat/completions   (Chat Completions)
  - POST https://alpha.backend.summachat.com/api/v1/responses          (OpenAI Responses protocol, e.g. Codex)
  - GET  https://alpha.backend.summachat.com/api/v1/models             (model discovery)
- Anthropic-compatible base URL: https://alpha.backend.summachat.com/api
  - POST https://alpha.backend.summachat.com/api/v1/messages (the Anthropic SDK appends /v1/messages to the base URL)
- Auth: header "Authorization: Bearer <API_KEY>" (the Anthropic endpoint also accepts
  "x-api-key: <API_KEY>").
- Create a key at https://summachat.com/developer/keys. A name-only key works with every model
  and mode; pinning models to a key is optional (for tools that hardcode a model name).

## Models and modes

Switching modes is just the "model" string — nothing else in the request changes.

| model                   | mode         | behavior                                              |
|-------------------------|--------------|-------------------------------------------------------|
| summa-fast              | single model | one fast model; streams; full tool support            |
| summa/<slug>            | single model | any catalog model, e.g. summa/openai/gpt-5            |
| summa-debate            | debate       | default panel; moderator synthesizes one answer       |
| summa-debate-coding     | debate       | preset: Claude Sonnet 4.5 (moderator) + GPT-5 + Gemini 2.5 Pro |
| summa-debate-reasoning  | debate       | preset: GPT-5 (moderator) + Claude Opus 4.1 + Gemini 2.5 Pro   |

Discover every model id (paginated + searchable):
  GET https://alpha.backend.summachat.com/api/v1/models?search=<text>&limit=50&offset=0
  -> { "object": "list", "data": [{ "id", "display_name", ... }], "has_more": bool }

## Custom debate panels — the "summa" request-body block

Add a "summa" object to the JSON body of any chat request. Works on /chat/completions,
/messages, and /responses. When present it overrides whatever the model string resolved to.

  "summa": {
    "panel": ["openai/gpt-5", "anthropic/claude-sonnet-4.5"],
    "moderator": "anthropic/claude-sonnet-4.5"
  }

Rules:
- panel: 2 to 8 distinct model slugs (same ids as summa/<slug>, without the prefix).
- moderator: optional; MUST be one of panel. It synthesizes the final answer.
  Omitted -> the first panel entry moderates.
- Invalid input (panel < 2 or > 8, moderator not in panel) -> 400 with a clear message.

With the official SDKs, pass it as a vendor extension:
- Python (openai / anthropic SDKs):  extra_body={"summa": {...}}
- TypeScript (openai / anthropic SDKs): add "summa: {...}" to the request params with
  "// @ts-expect-error" above it (extra params are forwarded as-is).

Legacy (still works, not recommended): encode the panel in the model string as
"summa-debate/<m1>,<m2>[,...]" — the first model moderates.

## Streaming, tools, latency

- "stream": true is supported everywhere (SSE in each protocol's native event shape).
- Debate streaming shows the panel deliberate live on every protocol:
  - Anthropic (/messages): each panelist's turn streams as a "thinking" block, then the
    moderator's synthesis streams as normal text.
  - OpenAI (/chat/completions) and Responses (/responses): each panelist's turn streams as
    visible interim content (a header, each model's turn, then a "Synthesized answer"
    divider), followed by the moderator's answer streamed token by token.
  - Non-streaming debate returns only the synthesized answer (no transcript). Stream to
    watch the debate.
- Tools / function calling: fully supported in single-model mode (passes through to the
  model). In debate mode tools are accepted but not invoked — debate is a reasoning
  surface, not an agentic one.
- Debate is slower than a single model (several model turns + a synthesis pass). Prefer
  streaming and set generous HTTP timeouts.

## Errors

Standard per-protocol envelopes:
- OpenAI:    { "error": { "message", "type", "code" } }
- Anthropic: { "type": "error", "error": { "type", "message" } }

| status | meaning                                                        |
|--------|----------------------------------------------------------------|
| 401    | missing or invalid API key                                     |
| 402    | out of API credit — top up at https://summachat.com/developer/credits    |
| 400    | invalid summa block (panel size, moderator not in panel)       |

Error "type" values are protocol-idiomatic, matching each vendor's own conventions —
e.g. out-of-credit (402) is "insufficient_quota" on the OpenAI endpoints and
"billing_error" on the Anthropic endpoint.

## Billing

API usage bills a prepaid credit balance (separate from app subscriptions) at the
model's token cost + 15% platform fee. A debate charges every panel model's turn, so a
3-model panel costs roughly 3x a single model. Eligible accounts receive a starting
credit on first API use. Full ledger: https://summachat.com/developer/activity

## Examples

Single model (curl):
  curl -X POST https://alpha.backend.summachat.com/api/v1/chat/completions \
    -H "Authorization: Bearer $SUMMA_API_KEY" -H "Content-Type: application/json" \
    -d '{"model":"summa-fast","messages":[{"role":"user","content":"Hello"}]}'

Custom debate panel (curl):
  curl -X POST https://alpha.backend.summachat.com/api/v1/chat/completions \
    -H "Authorization: Bearer $SUMMA_API_KEY" -H "Content-Type: application/json" \
    -d '{"model":"summa-debate","summa":{"panel":["openai/gpt-5","anthropic/claude-sonnet-4.5"],"moderator":"anthropic/claude-sonnet-4.5"},"messages":[{"role":"user","content":"Monolith or microservices?"}]}'

Python (openai SDK):
  from openai import OpenAI
  client = OpenAI(base_url="https://alpha.backend.summachat.com/api/v1", api_key="YOUR_API_KEY")
  response = client.chat.completions.create(
      model="summa-debate",
      messages=[{"role": "user", "content": "Monolith or microservices?"}],
      extra_body={"summa": {"panel": ["openai/gpt-5", "anthropic/claude-sonnet-4.5"],
                            "moderator": "anthropic/claude-sonnet-4.5"}},
  )

TypeScript (openai SDK):
  import OpenAI from "openai";
  const client = new OpenAI({ baseURL: "https://alpha.backend.summachat.com/api/v1", apiKey: "YOUR_API_KEY" });
  const response = await client.chat.completions.create({
    model: "summa-debate",
    messages: [{ role: "user", content: "Monolith or microservices?" }],
    // @ts-expect-error — summa is a Summa vendor extension
    summa: { panel: ["openai/gpt-5", "anthropic/claude-sonnet-4.5"],
             moderator: "anthropic/claude-sonnet-4.5" },
  });

## More

- Quick start (human docs): https://summachat.com/developer
- Integration guides:       https://summachat.com/developer/guides
  (per-tool: Claude Code, Cursor, Codex, Python, TypeScript, curl)
- Model reference:          https://summachat.com/developer/models
- API keys:                 https://summachat.com/developer/keys