> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Research

> Run deep web research with source synthesis (asynchronous).

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.

<Warning>
  Research is async. Poll the job status with [Get Job Status](/api-reference/jobs/get) or use `theo.waitForJob()` in the SDK.
</Warning>

## Authentication

Requires a Bearer token. See [Authentication](/api-reference/authentication).

## Request Body

<ParamField body="prompt" type="string" required>
  The research question or topic.
</ParamField>

<ParamField body="depth" type="string" default="advanced">
  Research depth. `"basic"` for quick summaries, `"advanced"` for comprehensive multi-source analysis.
</ParamField>

<ParamField body="max_sources" type="integer" default="10">
  Maximum number of sources to consult (1–50).
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  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
    }'
  ```

  ```typescript SDK theme={null}
  const job = await theo.research({
    prompt: "Compare React, Vue, and Svelte for enterprise apps in 2026",
    depth: "advanced",
    max_sources: 10,
  });

  // Poll until complete (check every 3s, timeout after 2min)
  const result = await theo.waitForJob(job.job_id, 3000, 120_000);
  console.log(result.result); // Full research report with citations
  ```
</CodeGroup>

## Response (HTTP 202)

<ResponseField name="id" type="string">
  Unique research request ID (prefixed `res_`).
</ResponseField>

<ResponseField name="job_id" type="string">
  Job ID for polling status.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"queued"` on creation.
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="poll_url" type="string">
  Relative URL to poll for job status.
</ResponseField>

### Example Response

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

## Errors

| Status | Code                | Description                                   |
| ------ | ------------------- | --------------------------------------------- |
| 400    | `missing_prompt`    | `prompt` is required                          |
| 401    | `invalid_api_key`   | Missing or invalid API key                    |
| 503    | `queue_unavailable` | Research queue is not available — retry later |