Verdict API

The Verdict API lets you create AI-powered debates and receive structured verdicts programmatically. This page is a comprehensive guide — from setup to production.

Authentication

All API requests require an API key via the Authorization header:

Authorization: Bearer vrd_your_api_key

Keys are created in the Developer Portal → API Keys. Keys start with vrd_ and are shown once at creation.

See Authentication for details on key management and BYOK setup.

Your First Verdict

curl -X POST https://api.askverdict.ai/v1/verdicts \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Should we use PostgreSQL or MongoDB for our new SaaS product?",
    "mode": "balanced"
  }'

Endpoints at a Glance

Debate Modes

Streaming (SSE)

The stream endpoint delivers events via Server-Sent Events as the debate unfolds:

curl -N https://api.askverdict.ai/v1/verdicts/DEBATE_ID/stream \
  -H "Authorization: Bearer vrd_your_api_key"

Event Types

See Stream Verdict and SSE Events Guide for details.

Verdict Response Structure

When a debate completes, the verdict object contains:

{
  "recommendation": "PROCEED",
  "oneLiner": "Use PostgreSQL for your relational data needs.",
  "confidence": 82,
  "narrative": "After examining both options...",
  "arguments": [
    {
      "agent": "Database Architect",
      "stance": "support",
      "keyPoints": ["ACID compliance", "Complex joins support"]
    }
  ],
  "keyEvidence": [...],
  "decisionMatrix": [...],
  "nextSteps": ["Set up PostgreSQL with connection pooling", ...],
  "revisitTriggers": ["If write throughput exceeds 50K ops/sec", ...]
}

Recommendation Values

Webhooks

Receive real-time notifications when debates complete:

curl -X POST https://api.askverdict.ai/api/user-webhooks \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/askverdict",
    "events": ["debate.completed", "verdict.delivered"]
  }'

Webhook payloads are signed with HMAC-SHA256. Verify the X-AskVerdict-Signature header.

See Webhook Guide and User Webhooks API for setup and verification.

Rate Limits

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1708444800

When rate limited (429), wait until the reset timestamp before retrying.

Credit Costs

BYOK subscribers use their own API keys and are not charged credits per debate. See Billing & Credits for plans and pricing.

Error Handling

All errors return a consistent format:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for balanced mode (need 3, have 1)"
  }
}

Common error codes: UNAUTHORIZED, VALIDATION_ERROR, INSUFFICIENT_CREDITS, RATE_LIMITED, NOT_FOUND, PROVIDER_ERROR.

Implement exponential backoff for 429 and 5xx errors. See Error Reference for the complete list.

SDKs & Tools

Integrations

• Slack Integration — Get verdicts in Slack channels
• Discord Integration — Bot commands for Discord
• Notion Integration — Auto-sync verdicts to Notion
• Zapier Integration — Connect to 5,000+ apps

Next Steps

• Quick Start Guide — First verdict in 5 minutes
• Decision Intelligence Guide — Outcome tracking and quality scores
• Team Workspaces — Collaborative decision making
• Best Practices — Tips for effective debates