API reference

Every REST endpoint, the MCP tools, the receipt fields and the error codes.

Base URL and auth

https://www.quorum.dog/v1

Send the key as Authorization: Bearer <key>. Keys start with qk_live_ or qk_test_. The API is server to server: a request carrying a browser Origin header returns 403 browser_origin_not_allowed.

API keys always bill your organization's API account. Each API-key call has a ceiling on its bill: the higher of $2.00 and the price of the Mode being called, unless the API key carries its own ceiling. Only Quorum sets a key's own ceiling. A request can lower the ceiling for one call with quorum.max_cost_usd. Calls from a connected app on a plan pay real cost and have no per-call ceiling.

Endpoints

Every model field takes a Mode ticker in the form COMPANY:MODE, for example QRUM:STAN for Standard Mode. model is required on every call.

POST /v1/chat/completions

curl -sS https://www.quorum.dog/v1/chat/completions \
  -H "Authorization: Bearer $QUORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 300 \
  -d '{
    "model": "QRUM:STAN",
    "messages": [{"role": "user", "content": "Should we use RLS or app-layer authz?"}],
    "quorum": { "max_cost_usd": 1.00 }
  }'

Request fields:

Headers: Idempotency-Key makes a retry safe. Send a new key for each request and the same key only when you retry that request. If you omit it, one is derived from your organization, key, model and messages, so an identical repeat question is a retry.

A replay matches on the key alone. A key reused with a different request returns the first request's answer, when that request succeeded, and runs nothing new. While the first call is still running, a retry with the same key returns 409 request_in_progress; wait and retry.

A repeat of a call that succeeded replays the stored answer with quorum.replayed: true and bills nothing. The replayed quorum block holds request_id, replayed, mode, a note, and seats_answered and answer_truncated when they were recorded. It does not hold converged, remaining_friction, contested_passage, deliberation or billed_usd. Check replayed first and read the other fields with a default. A call that ended capped is not replayed: a retry with the same key runs again and bills again.

Response:

{
  "id": "…",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "QRUM:STAN",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" }
  ],
  "usage": {
    "prompt_tokens": 41,
    "completion_tokens": 612,
    "total_tokens": 653,
    "completion_tokens_details": { "reasoning_tokens": null }
  },
  "quorum": {
    "request_id": "…",
    "mode": "QRUM:STAN",
    "rounds": 1,
    "seats": 3,
    "seats_answered": 3,
    "converged": true,
    "remaining_friction": null,
    "contested_passage": null,
    "best_seat_rationale": "…",
    "best_seat_judged_by": "llm",
    "deliberation": [],
    "capped": false,
    "surcharge_usd": 0.05,
    "platform_fee_usd": 0.004,
    "cap_credit_usd": 0,
    "billed_usd": 0.10,
    "latency_ms": 26418,
    "engines": ["<seat model id>", "<seat model id>", "<seat model id>"],
    "substitutions": [],
    "persisted": true
  }
}

finish_reason is stop or length. length means the answer was cut off. The values in the sample are illustrative.

quorum fields:

A deliberation runs several models. Set the client timeout to 300 seconds.

POST /v1/estimate

Same request body as chat completions. Free. The response:

{
  "request_id": "…",
  "model": "QRUM:STAN",
  "mode": "QRUM:STAN",
  "depth": "medium",
  "difficulty_score": 0.61,
  "task_type": "analysis",
  "estimated_price_usd": 0.10,
  "billed_usd": 0,
  "deliberation_value": {
    "verdict": "likely_helps",
    "reason": "multi_step_conclusion",
    "basis": "hypothesis",
    "evidence": "…"
  },
  "timing_ms": { "total": 912, "classify": 874 }
}

The values in the sample, including timing_ms, are illustrative. estimated_price_usd is the Mode's surcharge for the classified depth. The bill for the real call adds a token charge and the platform fee.

deliberation_value.verdict is likely_helps, likely_hurts or unknown. See the escalation router.

GET /v1/models

Returns { "object": "list", "data": [...] }. Each entry has id (the ticker), quorum.name, quorum.description, quorum.use_when, quorum.pricing (q_surcharge_usd, q_surcharge_by_depth, q_surcharge_express_usd), quorum.provider_families and quorum.includes_deliberation.

GET /v1/receipts/{request_id}

Returns { "ok": true, "receipt": {...} }. Add ?include_transcript=true to include each seat's text. A request id from another organization returns 404 receipt_not_found.

A call that never convened a panel, such as an estimate or a call that ended before a seat fired, returns 200 with { "ok": true, "request_id": "...", "status": "...", "receipt_available": false, "reason": "..." } and no receipt key. Check receipt_available before reading receipt.

Top level of receipt:

Each entry in seats:

A staff engine that could not run shows as unavailable: reason. The fee applies to API calls only, on the source's real billed cost; never on plan usage.

Lab and certification

POST /v1/tests runs known-answer questions against a Mode you can call and returns a batch_id and a status_url. Send dry_run: true for a quote. POST /v1/certify runs the certification for a Mode your organization owns. The Mode must be listed in the Marketplace to launch, and a dry_run on an unlisted Mode returns its quote with requires_listing: true. Both are billed per question to the organization, accept Idempotency-Key, and are polled with GET and batch_id. The same operations are the run_test and certify_mode MCP tools.

MCP tools

The server is at https://www.quorum.dog/mcp. It has 13 tools. Setup is in Connect Quorum to your tools. The loop is estimate, deliberate, get_receipt, act.

deliberate takes model, messages, and optionally max_cost_usd and tier. estimate takes model and messages. get_receipt takes request_id. A connected app signed in to a plan pays real cost with no API surcharge. max_cost_usd applies to API-key calls.

Convene a panel for judgement calls: a consequential assumption, options close enough that the numbers no longer separate them, a diagnosis you cannot check, a decision you will have to defend, or a "what have I missed" check. Use a single model for lookups, syntax, formatting, conversions, arithmetic and anything you need reproduced word for word.

Errors

Every error has the OpenAI shape plus a quorum block.

{
  "error": { "message": "Rate limit exceeded for this API key.", "type": "rate_limit_error", "code": "rate_limit_exceeded", "param": null },
  "quorum": { "request_id": null }
}

Branch on error.code. Messages can change.

MCP tool calls that fail return a result with isError: true. The text of the result is JSON in one of three shapes.

Tools that forward to the REST API (deliberate, list_modes, estimate, get_receipt, run_test, certify_mode) return the REST error object, with the HTTP status beside it. request_id and quorum appear only when the API sent them.

{
  "http_status": 404,
  "error": { "message": "Unknown model: ACME:NOPE", "type": "invalid_request_error", "code": "model_not_found", "param": null }
}

The tools Quorum answers itself (list_engines, validate_mode, ask_genie, approve_quote, genie_propose_mode, save_mode, list_mode) return error.code and error.message. Extra detail, such as refusals or retry_after_seconds, sits in quorum.

{
  "http_status": 409,
  "error": { "code": "quote_already_used", "message": "Request failed (quote_already_used)." },
  "quorum": { "quote": { "status": "launched" } }
}

upstream_unreachable and a tool that fails before it can answer (internal_error) return a plain string: { "error": "upstream_unreachable", "detail": "..." }. Branch on error.code when error is an object and on error when it is a string.

These failures arrive outside the tool result, as a JSON-RPC error or an HTTP status:

• No bearer token. A request with no Authorization: Bearer header is refused before any tool runs, initialize included. It answers HTTP 401 with WWW-Authenticate: Bearer resource_metadata="https://www.quorum.dog/.well-known/oauth-protected-resource/mcp" and a JSON-RPC error with code -32001 and the message Authentication required: sign in with OAuth, or send your Quorum API key as a Bearer token. A connected app reads the challenge and starts sign-in.
• Invalid arguments. A call missing a required argument, or naming an unknown tool, gets a JSON-RPC error with code -32602 and a message naming the argument. The check runs in the MCP server, for run_test, certify_mode and the tools the server answers itself. deliberate, estimate and get_receipt skip it and send the call on, so a missing argument comes back as the REST error in the tool result: deliberate with no model returns invalid_messages, and estimate with no model returns invalid_model. run_test needs model and questions (or the legacy buckets; or batch_id alone), certify_mode needs model (or batch_id alone), ask_genie needs mode and message (or batch_id alone), genie_propose_mode needs description, approve_quote needs quote_id, validate_mode needs spec, save_mode needs spec (or mode_id with release: true), and list_mode needs mode_id or mode.
• A request the server cannot read. A body that is not valid JSON answers HTTP 400 with code -32700. A body that is not a JSON object or array answers HTTP 400 with code -32600.
• An unknown method. A JSON-RPC request with an id and a method the server does not have gets code -32601 in an HTTP 200 reply. A notification, which has no id, gets an empty 202.
• An unhandled exception. HTTP 500 with code -32603 and the message Internal error. Retry.
• The wrong HTTP method. GET and DELETE answer HTTP 405 with an Allow: POST header. Send every MCP message as a POST.
• A refused sign-in. When a connected app's access token is refused, the whole MCP request answers HTTP 401 with a WWW-Authenticate challenge, so the app refreshes the token or signs in again. An API key that fails gets invalid_api_key or revoked_api_key in the tool result instead.

The REST codes above come back unchanged through the forwarding tools. The server adds these:

approve_quote also passes on the /v1/tests or /v1/certify code that refused the launch, such as insufficient_balance or listing_required. A refusal with no code of its own comes back as launch_refused, and http_status is the status the launch answered with, or 502 when it gave none. That status can be 200 when the launch answered without a run id.

save_mode and list_mode pass on the save endpoint's own code. The codes it can send are in the table above and in the validation codes below. When it sends a status with no code, the tool uses invalid_request (400), invalid_api_key (401), forbidden (403), mode_not_found (404), conflict (409) or save_failed.

Validation codes

save_mode with release: true checks the stored draft again before it releases it. A draft that no longer passes returns the check's own code as error.code, usually with HTTP 400, and the message says what to fix. validate_mode reports the same codes in body.error of each entry in refusals. A check with no code of its own, such as a round count out of range, returns invalid_request with the reason in the message.

price_override_not_allowed (400) means the spec sets api_commercial.price_override_acknowledged. That confirmation is for a person in the Builder. An API key or a connected app may set any price at or above the floor without it, so drop the field. validate_mode lists it first in refusals, and save_mode returns it inside mode_invalid's quorum.refusals.

Quote refusal values

ask_genie with a quote answers successfully even when it cannot price the run. The result then carries quote_unavailable in place of quote, set to one of these values or to the /v1/tests or /v1/certify error code that refused the price.

Limits

A key can be given higher request and concurrency limits, and a different input limit. rate_limit_exceeded and concurrency_limit_exceeded send Retry-After in seconds.