Create A Task

POST

browsing

tasks

curl --request POST \
  --url https://api.yutori.com/v1/browsing/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Give me a list of all employees (names and titles) of Yutori.",
    "start_url": "https://yutori.com"
  }'

import requests

response = requests.post(
    "https://api.yutori.com/v1/browsing/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "task": "Give me a list of all employees (names and titles) of Yutori.",
        "start_url": "https://yutori.com"
    }
)
print(response.json())

const response = await fetch("https://api.yutori.com/v1/browsing/tasks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    task: "Give me a list of all employees (names and titles) of Yutori.",
    start_url: "https://yutori.com"
  })
});
const data = await response.json();

{
  "task_id": "<string>",
  "view_url": "<string>",
  "result": "<string>",
  "paused": true,
  "structured_result": {},
  "webhook_url": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

curl --request POST \
  --url https://api.yutori.com/v1/browsing/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Give me a list of all employees (names and titles) of Yutori.",
    "start_url": "https://yutori.com"
  }'

import requests

response = requests.post(
    "https://api.yutori.com/v1/browsing/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "task": "Give me a list of all employees (names and titles) of Yutori.",
        "start_url": "https://yutori.com"
    }
)
print(response.json())

const response = await fetch("https://api.yutori.com/v1/browsing/tasks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    task: "Give me a list of all employees (names and titles) of Yutori.",
    start_url: "https://yutori.com"
  })
});
const data = await response.json();

Advanced Example

Receive structured output on a webhook when the task completes

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/browsing/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Give me a list of all employees (names and titles) of Yutori.",
    "start_url": "https://yutori.com",
    "max_steps": 75,
    "webhook_url": "https://example.com/webhook",
    "output_schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "title": { "type": "string" }
        }
      }
    }
  }'

import requests

response = requests.post(
    "https://api.yutori.com/v1/browsing/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "task": "Give me a list of all employees (names and titles) of Yutori.",
        "start_url": "https://yutori.com",
        "max_steps": 75,
        "webhook_url": "https://example.com/webhook",
        "output_schema": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "title": {"type": "string"}
                }
            }
        }
    }
)
print(response.json())

const response = await fetch("https://api.yutori.com/v1/browsing/tasks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    task: "Give me a list of all employees (names and titles) of Yutori.",
    start_url: "https://yutori.com",
    max_steps: 75,
    webhook_url: "https://example.com/webhook",
    output_schema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          title: { type: "string" }
        }
      }
    }
  })
});
const data = await response.json();

Authorizations

x-api-key

string

header

required

Body

application/json

task

string

required

String describing the browsing task in natural language.

Example:

"Give me a list of all employees (names and titles) of Yutori."

start_url

string

required

URL to open before running the task

Example:

"https://yutori.com"

output_schema

Output Schema · object | null

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

Example:

{
  "items": {
    "properties": {
      "name": {
        "description": "Full name of the employee",
        "type": "string"
      },
      "title": {
        "description": "Job title of the employee",
        "type": "string"
      }
    },
    "type": "object"
  },
  "type": "array"
}

task_spec

TaskSpec · object | null

deprecated

Deprecated but still supported. Use output_schema instead.

Show child attributes

used_deprecated_task_spec

boolean

default:false

max_steps

integer | null

Maximum number of steps the agent can take

Required range: 2 <= x <= 100

Example:

50

agent

enum<string> | null

Which agent to use for the browsing task. Defaults to navigator-n1.5-latest.

Available options:

navigator-n1.5-latest,

claude-sonnet-4-5-computer-use-2025-01-24,

null

Example:

"navigator-n1.5-latest"

require_auth

boolean

default:false

Hint that this task is likely to involve authentication (e.g. logging in or entering passwords). When true, the system will prefer an auth-optimized browser provider when available.

browser

enum<string> | null

Where to run the browser. '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

webhook_url

string | null

Optional webhook URL to receive the agent.run result for the calling user using webhook_format.

Example:

"https://example.com/webhook"

webhook_format

enum<string>

default:scout

Webhook payload format to use when webhook_url is provided. Slack incoming webhook URLs require 'slack'.

Available options:

scout,

slack,

zapier

Example:

"scout"

Response

Successful Response

task_id

string

required

Unique identifier for this browsing task

view_url

string

required

status

enum<string>

required

Available options:

queued,

running,

succeeded,

failed

result

string | null

paused

boolean | null

structured_result

If an output schema was provided, the result formatted as JSON matching that schema

structured_output_status

enum<string> | null

Whether structured output was requested, is still pending, succeeded, or failed

Available options:

not_requested,

pending,

succeeded,

failed

webhook_url

string | null

Echoes the webhook URL configured for this agent.run request, if provided.

rejection_reason

enum<string> | null

If status is 'failed', the specific billing reason for rejection

Available options:

insufficient_prepaid_balance,

budget_exceeded,

subscription_inactive

Get Status And ResultsReturns the current status (queued, running, succeeded, failed) and any results if completed.

curl --request POST \
  --url https://api.yutori.com/v1/browsing/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Give me a list of all employees (names and titles) of Yutori.",
    "start_url": "https://yutori.com"
  }'

import requests

response = requests.post(
    "https://api.yutori.com/v1/browsing/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "task": "Give me a list of all employees (names and titles) of Yutori.",
        "start_url": "https://yutori.com"
    }
)
print(response.json())

const response = await fetch("https://api.yutori.com/v1/browsing/tasks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    task: "Give me a list of all employees (names and titles) of Yutori.",
    start_url: "https://yutori.com"
  })
});
const data = await response.json();

{
  "task_id": "<string>",
  "view_url": "<string>",
  "result": "<string>",
  "paused": true,
  "structured_result": {},
  "webhook_url": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Getting Started

General

Navigator API

Browsing API

Research API

Scouting API

Webhooks

Advanced Example

Authorizations

Body

Response

​Advanced Example

Authorizations

Body

Response

Advanced Example