⌘K

Debates API

Create, manage, and control AI debates — full CRUD plus lifecycle commands.

12 min read

Debates are the core resource in AskVerdict. Each debate runs a multi-agent AI panel that argues a question from different perspectives and produces a structured verdict. Debates are asynchronous — you create one, then stream or poll for results.

Base URL

All endpoints below are relative to https://api.askverdict.ai. Authenticate every request with Authorization: Bearer <your_api_key>.

Endpoints

Method	Path	Description
`POST`	`/api/debates`	Create and start a new debate
`GET`	`/api/debates`	List your debates (paginated)
`GET`	`/api/debates/:id`	Get a single debate by ID
`DELETE`	`/api/debates/:id`	Soft-delete a debate
`POST`	`/api/debates/:id/commands`	Send a lifecycle command to a running debate
`POST`	`/api/debates/:id/retry`	Retry a failed debate
`POST`	`/api/debates/:id/fork`	Fork a public debate with a modified question
`GET`	`/api/debates/:id/analytics`	Get per-debate analytics
`PATCH`	`/api/debates/:id/workspace`	Move a debate into or out of a workspace

POST /api/debates

POST/api/debates

Create a new debate and start the AI engine. Returns immediately with a debate ID and stream URL — the engine runs in the background.

Request Body

Name	Type	Required	Description
`question`	`string`	Required	The question or decision to debate. Minimum 10 characters, maximum 2000 characters.
`mode`	`"fast" \| "balanced" \| "thorough"`	Optional	Debate depth. fast = 1 credit, balanced = 3 credits, thorough = 8 credits. Default: fast.
`context`	`string`	Optional	Additional background context for the AI agents. Maximum 5000 characters.
`agentCount`	`integer`	Optional	Number of AI agents to participate. Between 2 and 7 inclusive.
`maxRounds`	`integer`	Optional	Maximum debate rounds before forcing a verdict. Between 1 and 5 inclusive.
`enableSearch`	`boolean`	Optional	Allow agents to perform web searches for up-to-date information.
`attachmentIds`	`string[]`	Optional	Array of uploaded file attachment UUIDs to include as document context. Maximum 5 attachments. Requires BYOK Pro plan.
`workspaceId`	`string (UUID)`	Optional	Scope the debate to a workspace. You must be a member with write access.
`preset`	`string`	Optional	Model configuration preset. Options: hackathon, balanced, economy, deepseek, groq, mixed. Maximum 50 characters.
`skipCache`	`boolean`	Optional	Force a fresh debate run even if a cached verdict exists for the same question.

Choosing a mode

Use fast for quick directional answers. Use balanced for most production decisions. Reserve thorough for high-stakes or complex trade-off analysis — it runs more rounds with deeper agent reasoning.

Example Requests

bash

curl -X POST https://api.askverdict.ai/api/debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Should we rewrite our monolith as microservices?",
    "mode": "balanced",
    "context": "6-year-old Node.js app, team of 12 engineers, 200k daily active users. Main pain points: deploy coupling and database contention.",
    "agentCount": 4,
    "maxRounds": 3
  }'

Response

Free plan debates

On the free plan, a judgeModel field is also returned in the response (e.g. "judgeModel": "haiku-4-5"). Free debates use a lighter model to control costs.

After receiving debateId, connect to streamUrl via SSE to watch the debate unfold in real time. See the Stream API reference for event shapes.

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Request body failed schema validation
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FORBIDDEN`	Not a member of the specified workspace, or insufficient workspace role
`429`	`MONTHLY_LIMIT_REACHED`	Free plan monthly debate limit reached. Response includes `limit` and `upgradeUrl`
`429`	`CONCURRENT_LIMIT`	Too many active debates running simultaneously. Response includes `activeCount` and `limit`
`429`	`QUOTA_EXCEEDED`	Insufficient credits for the selected mode

GET /api/debates

GET/api/debates

List your debates in reverse-chronological order. Supports pagination, status filtering, and workspace scoping.

Query Parameters

Name	Type	Required	Description
`page`	`integer`	Optional	Page number, 1-indexed. Default: 1.
`limit`	`integer`	Optional	Results per page. Between 1 and 100. Default: 20.
`status`	`"pending" \| "running" \| "paused" \| "completed" \| "failed"`	Optional	Filter by debate status. Omit to return all statuses.
`sortBy`	`"createdAt" \| "completedAt"`	Optional	Field to sort by. Default: createdAt.
`sortOrder`	`"asc" \| "desc"`	Optional	Sort direction. Default: desc.
`workspaceId`	`string (UUID)`	Optional	Filter to debates belonging to a specific workspace. You must be a member.

Example Requests

bash

# List completed debates, newest first
curl "https://api.askverdict.ai/api/debates?status=completed&page=1&limit=20" \
  -H "Authorization: Bearer vrd_your_api_key"
 
# List workspace debates
curl "https://api.askverdict.ai/api/debates?workspaceId=ws-uuid-here" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

GET /api/debates/:id

GET/api/debates/:id

Retrieve a single debate by its UUID. Only the owning user can access a private debate.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The debate ID returned from the create endpoint.

Example Requests

bash

curl "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Debate Status Values

Status	Description
`pending`	Created, engine starting up
`running`	Agents actively debating
`paused`	Paused via command — resumes on `resume` command
`completed`	Verdict reached, `verdict` field populated
`failed`	Engine error — use the retry endpoint to re-run

Error Responses

Status	Code	Description
`401`	`UNAUTHORIZED`	Invalid API key
`404`	`NOT_FOUND`	Debate does not exist or belongs to another user

DELETE /api/debates/:id

DELETE/api/debates/:id

Soft-delete a debate. The debate is hidden from list results but not permanently removed from storage.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The debate ID to delete.

Example Request

bash

curl -X DELETE "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

POST /api/debates/:id/commands

POST/api/debates/:id/commands

Send a real-time lifecycle command to an actively running debate. Commands take effect within the current or next round.

Debate must be running

This endpoint returns 409 DEBATE_NOT_RUNNING if the debate engine is not currently active (e.g. the debate is completed, failed, or the server restarted). Check status with GET /api/debates/:id before sending commands.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The running debate ID.

Request Body

The body is a discriminated union on the type field.

Pause

Name	Type	Required	Description
`type`	`"pause"`	Required	Pause the debate after the current agent response completes.

Resume

Name	Type	Required	Description
`type`	`"resume"`	Required	Resume a paused debate.

Name	Type	Required	Description
`type`	`"skip"`	Required	Skip remaining rounds and force the judge to produce a verdict immediately.

Inject

Name	Type	Required	Description
`type`	`"inject"`	Required	Inject a message or evidence into the debate context. Agents see it in the next round.
`payload.content`	`string`	Required	The content to inject. Must be non-empty.

Example Requests

bash

# Pause
curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/commands" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "pause" }'
 
# Skip to verdict
curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/commands" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "skip" }'
 
# Inject new evidence
curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/commands" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inject",
    "payload": {
      "content": "Update: the engineering team confirmed migration would take 18 months, not 6."
    }
  }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Unknown command type or missing required payload
`404`	`NOT_FOUND`	Debate not found or not owned by user
`409`	`DEBATE_NOT_RUNNING`	Engine is not currently active for this debate

POST /api/debates/:id/retry

POST/api/debates/:id/retry

Re-run a failed debate from scratch. Clears previous events, resets status to pending, and relaunches the engine with the original question and mode.

Only failed debates can be retried

Retrying a debate that is not in failed status returns 409 DEBATE_NOT_FAILED. If the engine is already running for the debate ID, 409 DEBATE_ALREADY_RUNNING is returned instead.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The ID of the failed debate to retry.

Example Request

bash

curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/retry" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Debate not found or not owned by user
`409`	`DEBATE_NOT_FAILED`	Debate is not in failed status
`409`	`DEBATE_ALREADY_RUNNING`	Engine is already running for this debate

POST /api/debates/:id/fork

POST/api/debates/:id/fork

Fork a public debate into your account, optionally changing the question. The forked debate runs as a fresh debate under your billing.

Billing applies to forks

Forking counts against your quota and billing the same as creating a new debate. Forks always run in fast mode.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The ID of the public debate to fork.

Request Body

Name	Type	Required	Description
`modifiedQuestion`	`string`	Optional	Override the source debate question. Maximum 500 characters. If omitted, the original question is used.

Example Request

bash

curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/fork" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "modifiedQuestion": "Should a startup with 3 engineers rewrite their monolith as microservices?"
  }'

Response

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Source debate not found or not public
`429`	`MONTHLY_LIMIT_REACHED`	Free plan monthly limit reached
`429`	`QUOTA_EXCEEDED`	Insufficient credits

GET /api/debates/:id/analytics

GET/api/debates/:id/analytics

Retrieve per-debate analytics alongside your overall debate averages. Only the debate owner can access this endpoint.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The debate ID to retrieve analytics for.

Example Request

bash

curl "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/analytics" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Debate not found or not owned by the authenticated user

PATCH /api/debates/:id/workspace

PATCH/api/debates/:id/workspace

Move a debate into a workspace, or back to your personal account by setting workspaceId to null. You must own the debate and have write access to the target workspace.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	The debate ID to move.

Request Body

Name	Type	Required	Description
`workspaceId`	`string (UUID) \| null`	Required	UUID of the destination workspace, or null to move the debate back to your personal account.

Example Requests

bash

# Move into a workspace
curl -X PATCH "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/workspace" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "workspaceId": "ws-uuid-here" }'
 
# Move back to personal account
curl -X PATCH "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/workspace" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "workspaceId": null }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Body missing or `workspaceId` is not a valid UUID or null
`403`	`FORBIDDEN`	Not a workspace member, or role does not have write access
`404`	`NOT_FOUND`	Debate not found or not owned by user

Debate Object Reference

The debate object is returned by GET /api/debates and GET /api/debates/:id.

Field	Type	Description
`id`	`string`	UUID of the debate
`question`	`string`	The question that was debated
`status`	`string`	Current lifecycle status — see status values
`mode`	`"fast" \| "balanced" \| "thorough" \| null`	Depth setting used
`fundingSource`	`"free_tier" \| "user_credits" \| "byok"`	How the debate was funded
`isPublic`	`boolean`	Whether the debate is publicly accessible
`agentCount`	`integer \| null`	Number of agents that participated (set after completion)
`roundCount`	`integer \| null`	Number of rounds completed (set after completion)
`createdAt`	`string (ISO 8601)`	When the debate was created
`completedAt`	`string (ISO 8601) \| null`	When the debate finished, or null if still running
`ownerId`	`string`	User ID of the debate owner
`workspaceId`	`string \| null`	Workspace UUID if scoped, otherwise null
`verdict`	`Verdict \| null`	Structured verdict object — null until `status` is `completed`
`cost`	`DebateCost \| null`	Credit cost breakdown — null until `status` is `completed`

Verdict Object

Field	Type	Description
`recommendation`	`string`	The panel's final recommendation
`confidence`	`number`	Confidence score between 0 and 1
`summary`	`string`	Narrative summary of the debate outcome
`agentsUsed`	`string[]`	Model identifiers for each agent that participated
`totalRounds`	`integer`	Number of rounds that ran before verdict

Funding Sources

Value	Description
`free_tier`	Monthly free debate allowance (uses lighter Haiku model)
`user_credits`	Deducted from your credit balance at debate creation
`byok`	Bring-your-own-key — your provider API keys are used, not billed by AskVerdict

BYOK keys

Pass your provider API keys per-request via the X-Provider-Keys header as a JSON object: {"anthropic":"sk-ant-...","openai":"sk-..."}. Keys are never stored server-side.

Was this page helpful?

PreviousErrors NextVoting & Polls API