Skip to main content
POST
Start a Thread

Authorizations

x-api-key
string
header
required

Body

application/json

POST /v1/threads body.

input_message
string
required

The complete research brief. The agent is autonomous and asks no follow-up questions, so include the whole task in one message.

Required string length: 1 - 10000
mode
enum<string>
default:pro

Agent depth. pro (~20 papers) for almost all requests; deep (~50 papers, structured report) requires a paid plan.

Available options:
pro,
deep
filters
ThreadFilters · object | null

Global filters applied to every search the agent runs (shared /v1/search vocabulary).

Field set must match the filter fields of features/quick_search/schema.py:QuickSearchSearchParams (the RFC says the two surfaces share one filter schema); parity is pinned by schema_test.py. Values are validated here, not just typed: downstream parsers silently drop unknown domain/study-type values, and an expensive agent run must not execute without a restriction the caller asked for.

attachments
ThreadAttachments · object | null

Scope the research to specific papers/collections.

skill
enum<string> | null

Run a named research workflow (a Skill) instead of the agent's open-ended plan. Requires mode deep. Leave unset for normal research. Options: literature-review: a multi-paper synthesis of the literature on a topic; searches from several angles, follows citations, and investigates contradictory evidence. citation-snowballing: expands from known seed papers by following backward and forward citations; attach or name the seed papers. find-citations: finds research to support, qualify, or challenge the uncited claims in a draft; put the draft in input_message. verify-citations: audits whether the citations already in a draft support their claims and suggests the smallest fix for weak ones; put the cited draft in input_message or attach it. Refused with 422 outside deep mode, with an organization API key, or when the skill needs input the request didn't include, and with 403 feature_not_allowed when skills aren't enabled for your account yet.

Available options:
literature-review,
citation-snowballing,
find-citations,
verify-citations

Response

Successful Response

POST /v1/threads and POST /v1/threads/{thread_id}/interactions.

thread_id
string
required
interaction_id
string
required
status
enum<string>
required

Always running on dispatch.

Available options:
running,
idle,
failed
mode
enum<string>
required
Available options:
pro,
deep
url
string
required

Deep-link to the Thread on consensus.app.

poll_after_seconds
integer
required

Recommended wait between GET /v1/threads/{thread_id} polls.

max_wait_seconds
integer
required

Suggested polling ceiling before giving up (~180 pro, ~600 deep).

created_at
string<date-time> | null
title
string | null

Auto-generated Thread title.