Skip to main content
POST
/
v1
/
research
/
tasks
curl --request POST \
  --url https://api.yutori.com/v1/research/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
  }'

{
  "task_id": "<string>",
  "view_url": "<string>",
  "status": "queued",
  "webhook_url": "<string>",
  "mode": "deep"
}
curl --request POST \
  --url https://api.yutori.com/v1/research/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
  }'

​
Local Browser Example

Set browser: "local" to run browser tasks through the user’s desktop app (Yutori Local), which has access to their logged-in sessions.
curl --request POST \
  --url https://api.yutori.com/v1/research/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "Go to my LinkedIn profile and get my most recent post.",
    "browser": "local"
  }'

​
Advanced Example

Configure structured output with output_schema to receive data in a specific JSON schema format, and optionally add webhook notifications.
curl --request POST \
  --url https://api.yutori.com/v1/research/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases.",
    "user_timezone": "America/Los_Angeles",
    "webhook_url": "https://example.com/webhook",
    "output_schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "source_url": { "type": "string" }
        }
      }
    }
  }'

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
query
string
required
String describing the research task in natural language.
Example:

"What are the latest developments in quantum computing from the past week?"

​
mode
enum<string>
default:deep

Research mode. fast trades quality for latency.

Available options:
deep,
fast
Examples:

"deep"

"fast"

​
user_timezone
string
default:America/Los_Angeles

User's timezone for contextual awareness (e.g. 'America/Los_Angeles')

Example:

"America/Los_Angeles"

​
user_location
string | null
default:San Francisco, CA, US

User's coarse location in the format: city, region_code, country_name

Example:

"San Francisco, CA, US"

​
browser
enum<string> | null

Where to run browser tasks. 'cloud' (default) uses Yutori's cloud browser. 'local' uses the user's desktop app (Yutori Local) with their existing logged-in sessions. Requires the desktop app to be running.

Available options:
cloud,
local
​
output_schema
Output Schema · object

JSON Schema for structured output. Takes precedence over task_spec if both provided.

Example:
{
  "items": {
    "properties": {
      "title": {
        "description": "Title of the development",
        "type": "string"
      },
      "summary": {
        "description": "Brief summary",
        "type": "string"
      },
      "source_url": {
        "description": "URL for more details",
        "type": "string"
      }
    },
    "type": "object"
  },
  "type": "array"
}
​
task_spec
TaskSpec · object
deprecated

Deprecated but still supported. Use output_schema instead.

​
skip_email
boolean
default:true
If true, email notifications will be skipped and only webhook notifications will be sent.
    Default: true (sends webhooks only).
Example:

true

​
webhook_url
string | null

Optional webhook URL to receive results when the research task completes

Example:

"https://example.com/webhook"

​
webhook_format
enum<string>
default:scout

Webhook payload format. Slack incoming webhook URLs require 'slack'.

Available options:
scout,
slack,
zapier
Example:

"scout"

​
used_deprecated_task_spec
boolean
default:false

Response

Successful Response

Response for creating a research task.

​
task_id
string
required

Unique identifier for this research task

​
view_url
string
required

URL to view task progress and results

​
status
enum<string>
required

Current status of the research task

Available options:
queued,
running,
succeeded,
failed
​
webhook_url
string | null

Echoes the webhook URL configured for this task, if provided

​
mode
enum<string> | null

Echoes the research mode configured for this task, if provided

Available options:
deep,
fast