Skip to main content
POST
/
api
/
v1
/
research
Create Research
curl --request POST \
  --url https://api.example.com/api/v1/research \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "depth": "<string>",
  "max_sources": 123
}
'
{
  "id": "<string>",
  "job_id": "<string>",
  "status": "<string>",
  "created": "<string>",
  "poll_url": "<string>"
}
Run deep web research with multi-source synthesis and citations. This is an asynchronous endpoint — it returns a job ID immediately (HTTP 202) and research is conducted in the background.
Research is async. Poll the job status with Get Job Status or use theo.waitForJob() in the SDK.

​
Authentication

Requires a Bearer token. See Authentication.

​
Request Body

​
prompt
string
required
The research question or topic.
​
depth
string
default:"advanced"
Research depth. "basic" for quick summaries, "advanced" for comprehensive multi-source analysis.
​
max_sources
integer
default:"10"
Maximum number of sources to consult (1–50).

​
Request Examples

curl -X POST https://www.hitheo.ai/api/v1/research \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compare React, Vue, and Svelte for enterprise apps in 2026",
    "depth": "advanced",
    "max_sources": 10
  }'

​
Response (HTTP 202)

​
id
string
Unique research request ID (prefixed res_).
​
job_id
string
Job ID for polling status.
​
status
string
Always "queued" on creation.
​
created
string
ISO 8601 timestamp.
​
poll_url
string
Relative URL to poll for job status.

​
Example Response

{
  "id": "res_abc123",
  "job_id": "job_xyz789",
  "status": "queued",
  "created": "2026-04-10T12:00:00Z",
  "poll_url": "/api/v1/jobs/job_xyz789"
}

​
Errors

StatusCodeDescription
400missing_promptprompt is required
401invalid_api_keyMissing or invalid API key
503queue_unavailableResearch queue is not available — retry later