---
title: "Create A Task"
method: POST
path: "/v1/browsing/tasks"
tags: ["Browsing"]
---

# Create A Task

`POST /v1/browsing/tasks`

## Request

- Base URL: `https://api.yutori.com`
- URL: `https://api.yutori.com/v1/browsing/tasks`
- Auth: API key in header `x-api-key`

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

## Request body

- AgentRunRequest
  - `output_schema` object, nullable: JSON Schema for structured output. Takes precedence over task_spec if both provided.
  - `task_spec` TaskSpec
    - `output_schema` JsonSchemaSpec
      - `type` 'json'
      - `json_schema` object, nullable: A JSON Schema object defining the structure
  - `used_deprecated_task_spec` boolean
  - `task` string, required: String describing the browsing task in natural language.
  - `start_url` string, required: URL to open before running the task
  - `max_steps` integer, 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_auth` boolean: 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_url` string, 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'.

## Response `200`

Successful Response

- AgentRunResponse
  - `task_id` string, required: Unique identifier for this browsing task
  - `view_url` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `result` string, nullable
  - `paused` boolean, nullable
  - `structured_result` union: If an output schema was provided, the result formatted as JSON matching that schema
    - object
    - unknown[]
      - unknown
  - `structured_output_status` 'not_requested' | 'pending' | 'succeeded' | 'failed', nullable: Whether structured output was requested, is still pending, succeeded, or failed
  - `webhook_url` string, nullable: Echoes the webhook URL configured for this agent.run request, if provided.
  - `rejection_reason` 'insufficient_prepaid_balance' | 'budget_exceeded' | 'subscription_inactive'

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/yutori/apis/yutori-api.md) - [All operations](https://skmtc.dev/yutori/apis/yutori-api/llms.txt) - [OpenAPI document](https://skmtc.dev/yutori/apis/yutori-api/revisions/ef669f82d5bc?raw)