Threads & Messages

Research is organized into threads -- conversations containing user queries and synthesized research results.

POST /v1/threads -- Create Thread and Start Research

Creates a new thread, adds a user message, and dispatches a research job.

Request

curl -X POST https://parallect.ai/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the latest advances in CRISPR gene therapy?",
    "budget": "M",
    "mode": "methodical",
    "providers": ["perplexity", "gemini"]
  }'

Parameters

Field	Type	Required	Description
`message`	string	Yes	The research query
`budget`	string	No	Budget tier: `XXS`, `XS`, `S`, `M` (default), `L`, `XL`
`mode`	string	No	`fast` (default) or `methodical`
`providers`	string[]	No	Override default providers. Options: `perplexity`, `gemini`, `gemini-lite`, `openai`, `openai-mini`, `grok`, `grok-premium`, `anthropic`
`spidering`	boolean	No	Enable topic spidering (default: false)

Response (201)

{
  "id": "<thread_id>",
  "title": "What are the latest advances in CRISPR gene th...",
  "message": {
    "id": "<message_id>",
    "role": "user",
    "content": "What are the latest advances in CRISPR gene therapy?"
  },
  "job": {
    "id": "<job_id>",
    "status": "pending",
    "budgetTier": "M",
    "budgetCapCents": 1500,
    "researchMode": "methodical",
    "spideringEnabled": false
  },
  "createdAt": "2026-03-16T10:00:00Z"
}

GET /v1/threads -- List Threads

curl https://parallect.ai/api/v1/threads?limit=20&offset=0 \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Field	Type	Default	Description
`limit`	number	20	Max results (max 100)
`offset`	number	0	Pagination offset

Response

{
  "threads": [
    {
      "id": "<thread_id>",
      "title": "What are the latest advances...",
      "createdAt": "2026-03-16T10:00:00Z",
      "updatedAt": "2026-03-16T10:05:00Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

GET /v1/threads/:threadId -- Get Thread Details

Returns the thread with its messages and job summaries.

curl https://parallect.ai/api/v1/threads/THREAD_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "<thread_id>",
  "title": "What are the latest advances...",
  "createdAt": "2026-03-16T10:00:00Z",
  "updatedAt": "2026-03-16T10:05:00Z",
  "messages": [
    {
      "id": "<message_id>",
      "role": "user",
      "content": "What are the latest advances in CRISPR gene therapy?",
      "costCents": null,
      "createdAt": "2026-03-16T10:00:00Z"
    }
  ],
  "jobs": [
    {
      "id": "<job_id>",
      "status": "completed",
      "budgetTier": "M",
      "query": "What are the latest advances in CRISPR gene therapy?",
      "totalCustomerCostCents": 406,
      "durationSeconds": 187,
      "createdAt": "2026-03-16T10:00:00Z",
      "completedAt": "2026-03-16T10:03:07Z"
    }
  ]
}

The thread detail endpoint returns job summaries (status, costs, timing). To get the full job with synthesis, claims, and provider steps, use the job detail endpoint.

DELETE /v1/threads/:threadId -- Delete Thread

Delete a thread and all its associated data.

curl -X DELETE https://parallect.ai/api/v1/threads/THREAD_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "deleted": true
}

GET /v1/threads/:threadId/messages -- List Messages

Retrieve all messages in a thread, ordered chronologically.

curl https://parallect.ai/api/v1/threads/THREAD_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "messages": [
    {
      "id": "<message_id>",
      "role": "user",
      "content": "What are the latest advances in CRISPR gene therapy?",
      "costCents": null,
      "createdAt": "2026-03-16T10:00:00Z"
    }
  ]
}

POST /v1/threads/:threadId/messages -- Add Message

Add a new message to an existing thread. Adding a message does not automatically start a new research job -- use the pursue endpoint or create a new thread to trigger research.

Request

curl -X POST https://parallect.ai/api/v1/threads/THREAD_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you elaborate on delivery mechanisms?"
  }'

Parameters

Field	Type	Required	Description
`message`	string	Yes	The message content

Response (201)

{
  "id": "<message_id>",
  "threadId": "<thread_id>",
  "role": "user",
  "content": "Can you elaborate on delivery mechanisms?",
  "createdAt": "2026-03-16T10:15:00Z"
}

Threads & Messages

On this page