⌘K

Scheduled Debates API

Automate recurring debates on a daily, weekly, or monthly cadence.

8 min read

Scheduled debates let you automate recurring debate runs on a question at a fixed cadence — daily, weekly, or monthly. The scheduler fires the debate engine at the computed UTC time and applies the same billing rules as a manually created debate.

Base URL

All endpoints below are relative to https://api.askverdict.ai. All scheduled debate endpoints require authentication via Authorization: Bearer <your_api_key>.

Endpoints

Method	Path	Description
`GET`	`/api/scheduled-debates`	List your schedules (paginated)
`POST`	`/api/scheduled-debates`	Create a schedule
`GET`	`/api/scheduled-debates/:id`	Get a single schedule
`PATCH`	`/api/scheduled-debates/:id`	Update a schedule
`DELETE`	`/api/scheduled-debates/:id`	Delete a schedule

How Scheduling Works

When you create a schedule, the server computes nextRunAt — the next UTC datetime when the debate should fire based on your frequency, timeOfDay, and (for weekly/monthly) the target dayOfWeek or dayOfMonth.

The scheduler polls for due schedules, creates the debate, and immediately recomputes the next nextRunAt for the following period. Schedules with maxRuns set are automatically deactivated when the run limit is reached.

UTC-only scheduling

All times are computed in UTC. Timezone-aware scheduling (e.g. "every Monday at 9 AM EST") is planned for a future release. Set timezone to the IANA identifier you intend to use — the field is persisted but currently UTC is used for all computation.

POST /api/scheduled-debates

POST/api/scheduled-debates

Create a new schedule. The schedule is activated immediately and the first run is computed from the current time.

Request Body

Name	Type	Required	Description
`question`	`string`	Required	The debate question to run on each occurrence. 10–500 characters.
`frequency`	`"daily" \| "weekly" \| "monthly"`	Required	How often the debate runs.
`dayOfWeek`	`integer (0–6)`	Optional	Required when frequency is "weekly". Day of week (0 = Sunday, 6 = Saturday).
`dayOfMonth`	`integer (1–31)`	Optional	Required when frequency is "monthly". Day of the month to run the debate.
`timeOfDay`	`string (HH:MM)`	Optional	UTC time to run the debate. Must match HH:MM format. Default: "09:00".
`timezone`	`string`	Optional	IANA timezone identifier (e.g. "America/New_York"). Reserved for future use — currently all times are UTC. Default: "UTC".
`mode`	`"fast" \| "balanced" \| "thorough"`	Optional	Debate depth for each run. Defaults to fast if not set.
`context`	`string`	Optional	Background context injected into every scheduled debate run. Maximum 2000 characters.
`maxRuns`	`integer (1–1000)`	Optional	Maximum number of times this schedule should fire before auto-deactivating. Omit for indefinite recurrence.

Example Requests

bash

# Weekly debate every Monday at 09:00 UTC
curl -X POST https://api.askverdict.ai/api/scheduled-debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the most critical engineering risk this week?",
    "frequency": "weekly",
    "dayOfWeek": 1,
    "timeOfDay": "09:00",
    "mode": "balanced"
  }'
 
# Daily debate, limited to 30 runs
curl -X POST https://api.askverdict.ai/api/scheduled-debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Should we deploy the pending database migration today?",
    "frequency": "daily",
    "timeOfDay": "08:00",
    "mode": "fast",
    "maxRuns": 30
  }'

Response

Frequency Rules

Frequency	Required field	Behaviour
`daily`	None	Fires every day at `timeOfDay` UTC
`weekly`	`dayOfWeek` (0–6)	Fires on the specified weekday at `timeOfDay` UTC
`monthly`	`dayOfMonth` (1–31)	Fires on the specified day of each month at `timeOfDay` UTC

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing required fields, `dayOfWeek` absent for weekly, `dayOfMonth` absent for monthly, or `question` outside length limits
`401`	`UNAUTHORIZED`	Missing or invalid API key

GET /api/scheduled-debates

GET/api/scheduled-debates

List all of your scheduled debates. Supports pagination and optional active/inactive filtering.

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.
`active`	`"true" \| "false"`	Optional	Filter by active status. Omit to return all schedules.

Example Requests

bash

# All schedules
curl "https://api.askverdict.ai/api/scheduled-debates" \
  -H "Authorization: Bearer vrd_your_api_key"
 
# Only active schedules
curl "https://api.askverdict.ai/api/scheduled-debates?active=true" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

GET /api/scheduled-debates/:id

GET/api/scheduled-debates/:id

Retrieve a single schedule by ID. Only accessible to the schedule owner.

Path Parameters

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

Example Request

bash

curl "https://api.askverdict.ai/api/scheduled-debates/sched_3f2a1b0c" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

PATCH /api/scheduled-debates/:id

PATCH/api/scheduled-debates/:id

Update a schedule. All fields are optional — only the supplied fields are changed. If any timing fields (frequency, dayOfWeek, dayOfMonth, timeOfDay, timezone) are changed, nextRunAt is recomputed automatically.

Pause a schedule

Set active: false to pause a schedule without deleting it. Set active: true to resume it. The nextRunAt is recomputed from the current time when a paused schedule is resumed.

Path Parameters

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

Request Body

Name	Type	Required	Description
`question`	`string`	Optional	Updated debate question. 10–500 characters.
`mode`	`"fast" \| "balanced" \| "thorough" \| null`	Optional	Updated debate mode.
`context`	`string \| null`	Optional	Updated context. Pass null to clear it.
`frequency`	`"daily" \| "weekly" \| "monthly"`	Optional	Updated frequency. If changing to weekly, dayOfWeek is also required.
`dayOfWeek`	`integer (0–6) \| null`	Optional	Updated day of week for weekly schedules.
`dayOfMonth`	`integer (1–31) \| null`	Optional	Updated day of month for monthly schedules.
`timeOfDay`	`string (HH:MM)`	Optional	Updated time of day in HH:MM format (UTC).
`timezone`	`string`	Optional	Updated IANA timezone identifier.
`active`	`boolean`	Optional	Pause (false) or resume (true) the schedule.
`maxRuns`	`integer \| null`	Optional	Updated maximum run limit. Pass null to remove the limit.

Example Requests

bash

# Pause a schedule
curl -X PATCH "https://api.askverdict.ai/api/scheduled-debates/sched_3f2a1b0c" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
 
# Change to daily at 08:00 UTC
curl -X PATCH "https://api.askverdict.ai/api/scheduled-debates/sched_3f2a1b0c" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "frequency": "daily", "timeOfDay": "08:00" }'

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

Example Request

bash

curl -X DELETE "https://api.askverdict.ai/api/scheduled-debates/sched_3f2a1b0c" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

Status	Code	Description
`403`	`FORBIDDEN`	Schedule belongs to a different user
`404`	`NOT_FOUND`	Schedule not found

Schedule Object Reference

Field	Type	Description
`id`	`string`	Schedule identifier
`userId`	`string`	ID of the owning user
`question`	`string`	The debate question run each cycle
`mode`	`"fast" \| "balanced" \| "thorough" \| null`	Debate mode used for each run
`context`	`string \| null`	Optional background context for debates
`frequency`	`"daily" \| "weekly" \| "monthly"`	Recurrence frequency
`dayOfWeek`	`integer (0–6) \| null`	Target weekday for weekly schedules
`dayOfMonth`	`integer (1–31) \| null`	Target day for monthly schedules
`timeOfDay`	`string (HH:MM)`	UTC time of day
`timezone`	`string`	IANA timezone identifier (persisted, currently UTC-only)
`active`	`boolean`	Whether the schedule is currently running
`maxRuns`	`integer \| null`	Maximum run cap, or null for unlimited
`runCount`	`integer`	Total number of debates created by this schedule
`nextRunAt`	`string (ISO 8601)`	UTC datetime of the next scheduled run
`lastRunAt`	`string (ISO 8601) \| null`	UTC datetime of the most recent run, or null if never run
`createdAt`	`string (ISO 8601)`	When the schedule was created
`updatedAt`	`string (ISO 8601)`	When the schedule was last updated

Was this page helpful?

PreviousUser Webhooks NextAPI Keys

Scheduled Debates API

Endpoints

How Scheduling Works

POST /api/scheduled-debates

Request Body

Example Requests

Response

Frequency Rules

Error Responses

GET /api/scheduled-debates

Query Parameters

Example Requests

Response

GET /api/scheduled-debates/:id

Path Parameters

Example Request

Response

PATCH /api/scheduled-debates/:id

Path Parameters

Request Body

Example Requests

Response

DELETE /api/scheduled-debates/:id

Path Parameters

Example Request

Response

Error Responses

Schedule Object Reference

Product

Company

Use Cases

Teams

Content

Developer

Policies

Agreements