Skip to main content
POST
/
v1
/
deepresearch
/
tasks
curl --request POST \
  --url https://api.valyu.ai/v1/deepresearch/tasks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input": "What are the latest developments in quantum computing?",
  "model": "lite"
}
'
{
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "running",
  "model": "lite",
  "created_at": "2025-01-15T10:30:00.000Z",
  "metadata": {},
  "public": false,
  "webhook_secret": "a1b2c3d4e5f6..."
}

Authorizations

​
x-api-key
string
header
required

Your Valyu API key. Get one at platform.valyu.ai

Body

application/json
​
input
string
required

Research query or task description

Example:

"What are the key differences between RAG and fine-tuning for LLMs?"

​
model
enum<string>
default:lite

Research mode. 'lite' is faster and good for straightforward questions. 'heavy' provides more thorough analysis for complex research.

Available options:
lite,
heavy
Example:

"lite"

​
output_formats
(enum<string> | object)[]

Output formats. Use ['markdown'], ['markdown', 'pdf'], or a JSON schema object for structured output. Cannot mix JSON schema with markdown/pdf.

Available options:
markdown,
pdf
Example:
["markdown"]
​
strategy
string | null

Natural language strategy instructions prepended to the system prompt

Example:

"Focus on peer-reviewed sources and recent publications"

​
search
object

Search configuration parameters

​
urls
string<uri>[]

URLs to extract content from (max 10)

Maximum array length: 10
Example:
["https://example.com/article"]
​
files
object[]

File attachments (PDFs, images, documents). Max 10 files.

Maximum array length: 10
​
mcp_servers
object[]

MCP server configurations for custom tools (max 5 servers)

Maximum array length: 5
​
code_execution
boolean
default:true

Enable/disable code execution during research

​
previous_reports
string[]

Previous deep research IDs to use as context (max 3)

Maximum array length: 3
​
webhook_url
string<uri>

HTTPS URL for webhook notifications. When provided, Valyu will POST the full task result to this URL when the task completes or fails. The request includes X-Webhook-Signature and X-Webhook-Timestamp headers for verification. HTTP URLs are rejected—only HTTPS is supported.

​
metadata
object

Custom metadata for tracking

Response

Task created successfully

​
deepresearch_id
string<uuid>

Unique task identifier

Example:

"f992a8ab-4c91-4322-905f-190107bd5a5b"

​
status
enum<string>

Current task status

Available options:
queued,
running,
completed,
failed,
cancelled
​
model
enum<string>

Research mode used

Available options:
lite,
heavy
​
created_at
string<date-time>

Task creation timestamp

​
metadata
object

Custom metadata provided with the request

​
public
boolean

Whether the task is publicly accessible

​
webhook_secret
string

32-byte cryptographic secret (64-character hex string) for verifying webhook signatures. Only returned once in the creation response—store it securely. Use this secret to verify the HMAC-SHA256 signature in the X-Webhook-Signature header of incoming webhook requests.

​
message
string

Additional status message (e.g., if queued)