API & Webhooks

The Consensable API lets you run synthesis queries and receive results programmatically. Webhooks let your server receive a notification each time a synthesis completes.

Authentication

API keys are managed from the Developer section of your account page. Keys start with cnsk_ and are shown once at creation — store them securely. Lost keys cannot be recovered; revoke and create a new one instead.

Pass your API key in the Authorization header:

Authorization: Bearer cnsk_your_api_key_here

API access is available on Plus plans and above. Free plan keys are rejected with 403.

Errors

Errors are returned as JSON with an error field describing the problem.

429 responses include a limitType field (hourly, credits, cooldown, or seat_cap) and the relevant limit / used values.

Rate Limits

The same credit and rate limits that apply to the web UI apply to API requests — they are counted together against your account.

1 credit = $0.001 of AI cost (rounded up per query). The 5-second per-user cooldown applies regardless of whether the request comes from the web UI or the API.

API Keys

Request body

Response — 201

{
  "id":        "550e8400-e29b-41d4-a716-446655440000",
  "name":      "CI pipeline",
  "key":       "cnsk_a1b2c3d4e5f6...",   // shown once only
  "keyPrefix": "cnsk_a1b2c3",
  "createdAt": "2026-03-30T12:00:00.000Z"
}

Response — 200

{
  "keys": [
    {
      "id":          "550e8400-...",
      "name":        "CI pipeline",
      "keyPrefix":   "cnsk_a1b2c3",
      "createdAt":   "2026-03-30T12:00:00.000Z",
      "lastUsedAt":  "2026-03-30T14:22:00.000Z",
      "revokedAt":   null
    }
  ]
}

Synthesise

Request body

SSE event stream

Each event has a type field. Parse each data: line as JSON.

Minimal example (Node.js)

const response = await fetch('https://consensable.com/api/synthesise', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    question:   'Is remote work more productive than office work?',
    mode:       'ask',
    debaterIds: ['anthropic/claude-3-5-sonnet', 'openai/gpt-4o', 'google/gemini-pro-1.5'],
    chairId:    'anthropic/claude-3-5-sonnet'
  })
})

const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  buffer += decoder.decode(value, { stream: true })
  const lines = buffer.split('\n')
  buffer = lines.pop()   // keep incomplete line
  for (const line of lines) {
    if (!line.startsWith('data: ')) continue
    const event = JSON.parse(line.slice(6))
    if (event.type === 'result') console.log(event.synthesised_answer)
    if (event.type === 'result_saved') console.log('Saved as', event.id)
    if (event.type === 'error') throw new Error(event.message)
  }
}

Available models

On Plus / Starter plans, only the 8 curated standard models are available. On Pro and above, the full OpenRouter catalog is accessible — use GET /api/models/search?q=… to search it (requires auth).

Results

Webhook Endpoints

Register an HTTPS URL to receive event notifications. Webhook endpoints are managed from the Developer section of your account page, or via the API below.

Request body

Response — 201

{
  "id":        "7f3d9b2a-...",
  "name":      "My integration",
  "url":       "https://example.com/hook",
  "events":    ["synthesis.completed"],
  "isActive":  true,
  "secret":    "a1b2c3d4...",   // 64-char hex — shown once only
  "createdAt": "2026-03-30T12:00:00.000Z"
}

Delivery response fields

Webhook Events

synthesis.completed

Sent after every successful synthesis — whether triggered from the web UI or the API.

{
  "id":        "d4e5f6a7-...",          // unique delivery ID
  "event":     "synthesis.completed",
  "createdAt": "2026-03-30T14:22:00.000Z",
  "data": {
    "resultId":  "9c1b2a3d-...",
    "question":  "Is remote work more productive?",  // truncated to 500 chars
    "mode":      "ask",
    "verdict":   "Likely yes, with caveats",
    "isPrivate": false,
    "createdAt": "2026-03-30T14:22:00.000Z"
  }
}

Use data.resultId with GET /api/results/:id (authenticated) or GET /api/public/results/:id (public only) to fetch the full result.

Signing & Verification

Every delivery includes an X-Consensable-Signature header. Verify it to confirm the request came from Consensable and was not tampered with.

Header format

X-Consensable-Signature: t=1743340920,v1=a1b2c3d4e5f6...
X-Consensable-Event: synthesis.completed

The signature is HMAC-SHA256 of {timestamp}.{raw_request_body} using your endpoint's signing secret.

Verification — Node.js

const crypto = require('crypto')

function verifyWebhook(rawBody, signatureHeader, secret) {
  // Parse header: "t=1743340920,v1=abc123..."
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('=', 2))
  )
  const timestamp = parts.t
  const received  = parts.v1

  if (!timestamp || !received) throw new Error('Invalid signature header')

  // Reject requests older than 5 minutes
  const age = Math.abs(Date.now() / 1000 - Number(timestamp))
  if (age > 300) throw new Error('Webhook timestamp too old')

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  if (!crypto.timingSafeEqual(
    Buffer.from(received, 'hex'),
    Buffer.from(expected, 'hex')
  )) throw new Error('Signature mismatch')
}

// Express example — requires raw body (before express.json() parses it)
app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    verifyWebhook(
      req.body.toString(),
      req.headers['x-consensable-signature'],
      process.env.WEBHOOK_SECRET
    )
  } catch (err) {
    return res.status(400).json({ error: err.message })
  }
  const event = JSON.parse(req.body)
  console.log('Received:', event.event, event.data.resultId)
  res.status(200).end()
})

Verification — Python

import hashlib, hmac, time

def verify_webhook(raw_body: bytes, signature_header: str, secret: str):
    parts = dict(p.split('=', 1) for p in signature_header.split(','))
    timestamp = parts.get('t')
    received  = parts.get('v1')
    if not timestamp or not received:
        raise ValueError('Invalid signature header')

    age = abs(time.time() - int(timestamp))
    if age > 300:
        raise ValueError('Webhook timestamp too old')

    signed   = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(received, expected):
        raise ValueError('Signature mismatch')

Delivery & Retries

Consensable considers a delivery successful when your endpoint returns any 2xx HTTP status within 10 seconds. Anything else (non-2xx, timeout, or connection error) is treated as a failure and retried.

After 5 failed attempts the delivery is marked as permanently failed. The full attempt history is visible in the delivery log for each endpoint.

Make your endpoint idempotent. Use data.id (the delivery UUID) as an idempotency key — the same delivery may be retried and your server may receive it more than once if it returned a non-2xx status even after processing the payload.

Respond quickly — return 200 immediately and process the payload asynchronously if needed. Slow responses that hit the 10-second timeout will be retried.