Skip to main content
POST
Add a follow-up

Authorizations

x-api-key
string
header
required

Path Parameters

thread_id
string
required

Opaque Thread id.

Pattern: ^[A-Za-z0-9_-]+$

Body

application/json

POST /v1/threads/{thread_id}/interactions body (thread_id is the path).

input_message
string
required

The follow-up task. Earlier interactions are used as context automatically — don't restate them.

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

Depth for this follow-up.

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.