API Overview

The AskVerdict API is a RESTful JSON API for creating and managing AI-powered debates.

Base URL

https://api.askverdict.ai

All endpoints are prefixed with /v1/.

Authentication

Every request requires an API key passed via the Authorization header:

Authorization: Bearer vrd_your_api_key

See Authentication for details on creating keys and BYOK setup.

Request Format

• All request bodies use Content-Type: application/json
• Query parameters use standard URL encoding
• Dates are ISO 8601 format

Response Format

All responses follow a consistent structure:

{
  "debate": { ... },
  "verdict": { ... }
}

Error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Question is required"
  }
}

HTTP Status Codes

Rate Limits

Default rate limit is 60 requests per minute per API key. Headers included in every response:

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

Pagination

List endpoints support pagination via query parameters:

Response includes pagination metadata:

{
  "debates": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3
  }
}

Endpoints

Next Steps

• Create a Verdict — Full POST /v1/verdicts reference
• Stream Events — Real-time SSE streaming
• API User Profile — Verify API key identity and plan context
• API Key Usage — Track per-key request volume and endpoint usage
• Health Checks — Public and service-level readiness endpoints
• Attachments — File and URL context for debates
• Sharing — Share links and public token access
• Error Codes — Comprehensive error reference