⌘K

Voting & Polls API

Vote on debate arguments and create audience polls to gauge community opinion alongside AI verdicts.

8 min read

AskVerdict has two distinct voting systems layered on top of debates:

Argument votes — readers agree or disagree with individual AI agent claims inside a completed debate.
Debate polls — the debate owner creates multi-option audience polls to capture human opinion before or after the AI verdict.

Both systems support unauthenticated read access for public debates. Write operations require a valid API key.

Base URL

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

Argument Votes

Argument votes let readers rate individual claims made by AI agents during a debate. Each vote is keyed by a claimId — the identifier of the specific agent message — and can be "agree", "disagree", or "neutral" (which removes the vote).

Endpoints

Method	Path	Auth	Description
`GET`	`/api/debates/:debateId/votes`	Optional	Get vote tallies for all claims in a debate
`POST`	`/api/debates/:debateId/votes`	Required	Cast or update a vote on a claim
`DELETE`	`/api/debates/:debateId/votes/:claimId`	Required	Remove your vote on a claim

GET /api/debates/:debateId/votes

GET/api/debates/:debateId/votes

Retrieve aggregated agree/disagree tallies for every claim in a debate. If you are authenticated, your own vote is included in each entry.

Public debate access

This endpoint works without authentication for public debates. For private debates, you must be the owner to access votes.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID whose claim votes to retrieve.

Example Requests

bash

# Public debate — no auth needed
curl "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/votes"
 
# Authenticated — your own votes are included
curl "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/votes" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

The response is a votes map keyed by claimId. Each entry contains agree/disagree counts and, when authenticated, your own vote.

Neutral votes

neutral votes are stored server-side for analytics purposes but are not surfaced in tally counts — only agree and disagree are returned. Setting your vote to "neutral" via POST is equivalent to removing it.

POST /api/debates/:debateId/votes

POST/api/debates/:debateId/votes

Cast a vote on a specific claim. If you have already voted on this claim, the existing vote is updated (upsert). Posting vote: 'neutral' removes your vote entirely.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID containing the claim.

Request Body

Name	Type	Required	Description
`claimId`	`string`	Required	The identifier of the AI agent claim to vote on.
`vote`	`"agree" \| "disagree" \| "neutral"`	Required	Your vote. "neutral" removes an existing vote rather than storing a neutral marker.

Example Requests

bash

curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/votes" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "claimId": "claim_abc123",
    "vote": "agree"
  }'

Response

When vote: "neutral" is sent, the existing vote is removed and the response is:

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing `claimId`, invalid vote value, or malformed body
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FORBIDDEN`	Debate is private and you are not the owner
`404`	`NOT_FOUND`	Debate not found

DELETE /api/debates/:debateId/votes/:claimId

DELETE/api/debates/:debateId/votes/:claimId

Remove your vote on a specific claim. Safe to call even if no vote exists — returns success regardless.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID.
`claimId`	`string`	Required	The claim ID to remove your vote from.

Example Request

bash

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

Response

Debate Polls

Polls are created by the debate owner to ask a question with 2–6 predefined options. Any authenticated user who can view the debate can cast a vote. Polls can be closed by the owner to freeze results.

Endpoints

Method	Path	Auth	Description
`GET`	`/api/debates/:debateId/polls`	Optional	List polls with tallies and your vote
`POST`	`/api/debates/:debateId/polls`	Required (owner)	Create a poll
`POST`	`/api/debates/:debateId/polls/:pollId/vote`	Required	Cast or change a poll vote
`PATCH`	`/api/debates/:debateId/polls/:pollId`	Required (owner)	Close a poll
`DELETE`	`/api/debates/:debateId/polls/:pollId`	Required (owner)	Delete a poll

GET /api/debates/:debateId/polls

GET/api/debates/:debateId/polls

List all polls for a debate with per-option vote tallies. If authenticated, your own vote is included in each poll.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID whose polls to retrieve.

Example Requests

bash

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

Response

POST /api/debates/:debateId/polls

POST/api/debates/:debateId/polls

Create a new poll on a debate. Only the debate owner can create polls. Between 2 and 6 options are required.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID to attach the poll to.

Request Body

Name	Type	Required	Description
`question`	`string`	Required	The poll question. Minimum 1 character, maximum 200 characters.
`options`	`string[]`	Required	Array of option labels. Minimum 2, maximum 6. Each option must be 1–200 characters.

Example Requests

bash

curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/polls" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which approach do you prefer?",
    "options": [
      "Rewrite everything",
      "Incremental migration",
      "Keep the monolith"
    ]
  }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Question missing, fewer than 2 options, more than 6 options, or option text too long
`403`	`FORBIDDEN`	You are not the debate owner
`404`	`NOT_FOUND`	Debate not found

POST /api/debates/:debateId/polls/:pollId/vote

POST/api/debates/:debateId/polls/:pollId/vote

Cast or change a vote on a poll. One vote per user per poll — re-voting changes your previous selection.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID.
`pollId`	`string`	Required	The poll ID to vote on.

Request Body

Name	Type	Required	Description
`optionId`	`string`	Required	The ID of the option to vote for. Must match an option in the poll's options array.

Example Requests

bash

curl -X POST "https://api.askverdict.ai/api/debates/d8a3f1c2-4e5b-6789-abcd-ef0123456789/polls/poll_7a3b2c1d/vote" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "optionId": "opt_cc3dd4" }'

Response

Returns the updated poll with fresh tallies and your vote reflected.

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing `optionId` or `optionId` does not exist in this poll
`403`	`FORBIDDEN`	Debate is private and you are not the owner
`404`	`NOT_FOUND`	Debate or poll not found
`409`	`POLL_CLOSED`	The poll has been closed — no more votes accepted

PATCH /api/debates/:debateId/polls/:pollId

PATCH/api/debates/:debateId/polls/:pollId

Close a poll to stop accepting new votes. Only the debate owner can close polls. Closed polls remain visible with their final tallies.

Path Parameters

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID.
`pollId`	`string`	Required	The poll ID to close.

Example Request

bash

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

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The debate ID.
`pollId`	`string`	Required	The poll ID to delete.

Example Request

bash

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

Response

Error Responses

Status	Code	Description
`403`	`FORBIDDEN`	You are not the debate owner
`404`	`NOT_FOUND`	Poll or debate not found

Poll Object Reference

Field	Type	Description
`id`	`string`	Poll identifier
`debateId`	`string`	UUID of the parent debate
`question`	`string`	The poll question text
`options`	`PollOption[]`	Array of `{ id, label }` objects
`status`	`"open" \| "closed"`	Whether the poll is accepting votes
`createdAt`	`string (ISO 8601)`	When the poll was created
`closedAt`	`string \| null`	When the poll was closed, or null if still open
`tallies`	`Record<string, number>`	Per-option vote counts keyed by option ID
`totalVotes`	`integer`	Sum of all votes cast
`userVote`	`string \| null`	The option ID of your current vote, or null if not voted

Was this page helpful?

PreviousDebates API NextCollections API