⌘K

Collections API

Organize debates into named collections. Share curated sets publicly or keep them private.

7 min read

Collections are named groups of debates that you curate. Use them to organise your debates by topic, project, or team — and optionally share them publicly so others can browse your curated set without needing an account.

Base URL

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

Endpoints

Method	Path	Auth	Description
`POST`	`/api/collections`	Required	Create a collection
`GET`	`/api/collections`	Required	List your collections
`GET`	`/api/collections/:id`	Optional	Get a collection with its items
`PATCH`	`/api/collections/:id`	Required (owner)	Update a collection
`DELETE`	`/api/collections/:id`	Required (owner)	Delete a collection
`POST`	`/api/collections/:id/items`	Required (owner)	Add a debate to a collection
`DELETE`	`/api/collections/:id/items/:debateId`	Required (owner)	Remove a debate from a collection
`PATCH`	`/api/collections/:id/items/reorder`	Required (owner)	Reorder debates in a collection

POST /api/collections

POST/api/collections

Create a new collection. Collections are private by default — set isPublic: true to make the collection browsable by anyone with the URL.

Request Body

Name	Type	Required	Description
`name`	`string`	Required	Collection name. 1–100 characters.
`description`	`string`	Optional	Optional description of the collection. Maximum 500 characters.
`isPublic`	`boolean`	Optional	Whether the collection is publicly accessible. Default: false.

Example Requests

bash

curl -X POST https://api.askverdict.ai/api/collections \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Architecture Decisions 2026",
    "description": "Key engineering decisions debated by our platform team.",
    "isPublic": false
  }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Name is empty, too long, or description exceeds 500 characters
`401`	`UNAUTHORIZED`	Missing or invalid API key

GET /api/collections

GET/api/collections

List all collections owned by the authenticated user, ordered by creation date (newest first).

Example Requests

bash

curl "https://api.askverdict.ai/api/collections" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

GET /api/collections/:id

GET/api/collections/:id

Retrieve a single collection with its full list of debates. Public collections are accessible without authentication. Private collections are only accessible to their owner.

Sharing public collections

Set isPublic: true on a collection and share the URL https://askverdict.ai/collections/:id. Anyone — including unauthenticated users — can browse the debates in the collection.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The collection ID.

Example Requests

bash

# Public collection — no auth needed
curl "https://api.askverdict.ai/api/collections/col_8d1e5f2b"
 
# Private collection — owner only
curl "https://api.askverdict.ai/api/collections/col_4f2a9b3c" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

Status	Code	Description
`403`	`FORBIDDEN`	Collection is private and you are not the owner
`404`	`NOT_FOUND`	Collection not found

PATCH /api/collections/:id

PATCH/api/collections/:id

Update a collection's name, description, or visibility. All fields are optional — only the supplied fields are changed.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The collection ID to update.

Request Body

Name	Type	Required	Description
`name`	`string`	Optional	New collection name. 1–100 characters.
`description`	`string \| null`	Optional	New description, or null to clear it. Maximum 500 characters.
`isPublic`	`boolean`	Optional	Change collection visibility.

Example Requests

bash

# Make a collection public
curl -X PATCH "https://api.askverdict.ai/api/collections/col_4f2a9b3c" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "isPublic": true }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Field validation failed
`403`	`FORBIDDEN`	You are not the collection owner
`404`	`NOT_FOUND`	Collection not found

DELETE /api/collections/:id

DELETE/api/collections/:id

Delete a collection. All collection-debate associations are removed. The debates themselves are not deleted.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The collection ID to delete.

Example Request

bash

curl -X DELETE "https://api.askverdict.ai/api/collections/col_4f2a9b3c" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

POST /api/collections/:id/items

POST/api/collections/:id/items

Add a debate to a collection. The debate is appended at the end. You must own both the collection and the debate.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The collection ID.

Request Body

Name	Type	Required	Description
`debateId`	`string (UUID)`	Required	The UUID of the debate to add.

Example Requests

bash

curl -X POST "https://api.askverdict.ai/api/collections/col_4f2a9b3c/items" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "debateId": "d8a3f1c2-4e5b-6789-abcd-ef0123456789" }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	`debateId` is not a valid UUID
`403`	`FORBIDDEN`	You do not own the collection
`404`	`NOT_FOUND`	Collection or debate not found
`409`	`CONFLICT`	Debate is already in this collection

DELETE /api/collections/:id/items/:debateId

DELETE/api/collections/:id/items/:debateId

Remove a debate from a collection. The debate itself is not deleted — only the collection membership is removed.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The collection ID.
`debateId`	`string (UUID)`	Required	The debate UUID to remove from the collection.

Example Request

bash

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

Response

PATCH /api/collections/:id/items/reorder

PATCH/api/collections/:id/items/reorder

Change the display order of debates within a collection. Send the full desired order as an array of debateId + order pairs.

Full order required

You must supply all debates in the collection in the items array. Partial reorders are not supported — missing debates may be moved to unexpected positions.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The collection ID.

Request Body

Name	Type	Required	Description
`items`	`array`	Required	Array of ordering entries. Each entry is { debateId: string (UUID), order: integer >= 0 }. Minimum 1 entry.

Example Requests

bash

curl -X PATCH "https://api.askverdict.ai/api/collections/col_4f2a9b3c/items/reorder" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "debateId": "d8a3f1c2-4e5b-6789-abcd-ef0123456789", "order": 0 },
      { "debateId": "f9b4e2d1-5a6c-7890-bcde-f01234567890", "order": 1 },
      { "debateId": "a1b2c3d4-5e6f-7890-abcd-ef0123456789", "order": 2 }
    ]
  }'

Response

Collection Object Reference

Field	Type	Description
`id`	`string`	Collection identifier
`name`	`string`	Display name
`description`	`string \| null`	Optional description
`isPublic`	`boolean`	`true` if the collection is publicly viewable
`userId`	`string`	ID of the owning user
`createdAt`	`string (ISO 8601)`	Creation timestamp
`updatedAt`	`string (ISO 8601)`	Last modification timestamp
`items`	`CollectionItem[]`	Included only in `GET /collections/:id` — ordered list of debates

CollectionItem Object

Field	Type	Description
`debateId`	`string (UUID)`	ID of the debate
`order`	`integer`	Display order (0-indexed, ascending)
`addedAt`	`string (ISO 8601)`	When the debate was added
`debate`	`object`	Summary of the debate — id, question, status, mode, createdAt

Was this page helpful?

PreviousVoting & Polls API NextSearch & Discovery API