Consensus Runs

The Consensus endpoint runs the same prompt N times in parallel and returns the response that the majority of runs agreed on. This uses the Self-Consistency technique (Wang et al., 2023) to improve answer reliability for factual, analytical, and reasoning tasks.

POST /ai/sessions/:sessionId/consensus

Authentication: Bearer JWT
Required entitlement: ai.consensus.run
Response type: Synchronous JSON (not streamed)

Request

POST /ai/sessions/sess_abc123/consensus
Authorization: Bearer <token>
Content-Type: application/json

{
  "prompt": "What are the three most important considerations when designing a distributed cache?",
  "n": 3,
  "voteStrategy": "majority",
  "modelKey": "claude-sonnet-4-6"
}

Field	Type	Required	Description
prompt	string (max 4000)	Yes	The prompt to run N times.
n	integer (2–5)	No	Number of parallel sub-runs. Default: 3.
voteStrategy	'majority' | 'unanimous'	No	Voting rule. Default: 'majority'.
modelKey	string	No	Model to use. Falls back to cheapest active model.

Response

{
  "consensusId": "cns_uuid",
  "winner": "The three most important considerations are: 1. Cache invalidation strategy...",
  "voteCount": 2,
  "totalRuns": 3,
  "agreedOnWinner": true,
  "strategy": "majority",
  "subResults": [
    {
      "runId": "run_1",
      "response": "The three most important considerations are: 1. Cache invalidation strategy...",
      "durationMs": 1842
    },
    {
      "runId": "run_2",
      "response": "When designing a distributed cache, the key factors are: cache eviction...",
      "durationMs": 2103
    },
    {
      "runId": "run_3",
      "response": "The three most important considerations are: 1. Cache invalidation strategy...",
      "durationMs": 1991
    }
  ]
}

Field	Description
consensusId	Unique ID for this consensus run.
winner	The response text that the most sub-runs agreed on.
voteCount	Number of sub-runs that matched the winner.
totalRuns	Total sub-runs attempted.
agreedOnWinner	true if voteCount > totalRuns / 2 (majority) or voteCount === totalRuns (unanimous).
strategy	The voting strategy used.
subResults	All individual sub-run results, including errors.

Error Responses

Status	Cause
400	n < 2 or n > 5, or request body validation failed.
403	Missing ai.consensus.run entitlement.
500	All sub-runs failed.

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/consensus \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the three most important considerations when designing a distributed cache?",
    "n": 3,
    "voteStrategy": "majority",
    "modelKey": "claude-sonnet-4-6"
  }'

JavaScript

const sessionId = process.env.SESSION_ID; // from a previous session-creation call

const response = await fetch(`${BASE_URL}/ai/sessions/${sessionId}/consensus`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "What are the three most important considerations when designing a distributed cache?",
    n: 3,
    voteStrategy: "majority",
    modelKey: "claude-sonnet-4-6",
  }),
});
const data = await response.json();

Python

import requests, os

session_id = os.environ["SESSION_ID"]  # from a previous session-creation call
response = requests.post(
    f"{os.environ['BASE_URL']}/ai/sessions/{session_id}/consensus",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "prompt": "What are the three most important considerations when designing a distributed cache?",
        "n": 3,
        "voteStrategy": "majority",
        "modelKey": "claude-sonnet-4-6",
    },
)
data = response.json()

---

Notes

• Consensus is synchronous — the response is returned only after all N sub-runs complete. Expect 5–10 seconds at n=3.
• Credit cost is approximately n × the cost of a single message.
• When agreedOnWinner = false, the winner is the plurality response — surface an "uncertain" badge in the UI.
• Sub-run failures are included as subResults[i].error. Voting proceeds on the successful runs.
• Consensus runs do not appear in the session message history.

UI Recommendations

• Show winner as the primary response.
• Provide a "Show all runs" toggle that renders subResults as a comparison list.
• When agreedOnWinner = false, display a visual uncertainty indicator.
• Display voteCount / totalRuns as a confidence metric (e.g. "2/3 agreed").