Sign in

v1

latestOpenAPI 3.1.02026-07-26194149.1 KB
Browsing

Create A Task

Launches a website navigation agent to execute the task on a cloud browser.

post/v1/browsing/tasks

Request body

output_schemaobject nullable

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

used_deprecated_task_specboolean
taskstring required

String describing the browsing task in natural language.

start_urlstring required

URL to open before running the task

max_stepsinteger nullable

Maximum number of steps the agent can take

agent'navigator-n1.5-latest' | 'claude-sonnet-4-5-computer-use-2025-01-24' | 'null' nullable

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

require_authboolean

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'cloud' | 'local' nullable

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.

webhook_urlstring nullable

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

webhook_format'scout' | 'slack' | 'zapier'

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

Example request

{
  "output_schema": {
    "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": "Give me a list of all employees (names and titles) of Yutori.",
  "start_url": "https://yutori.com",
  "max_steps": 50,
  "agent": "navigator-n1.5-latest",
  "webhook_url": "https://example.com/webhook",
  "webhook_format": "scout"
}

Response

Successful Response

task_idstring required

Unique identifier for this browsing task

view_urlstring required
status'queued' | 'running' | 'succeeded' | 'failed' required
resultstring nullable
pausedboolean nullable
structured_output_status'not_requested' | 'pending' | 'succeeded' | 'failed' nullable

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

webhook_urlstring nullable

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

rejection_reason'insufficient_prepaid_balance' | 'budget_exceeded' | 'subscription_inactive'