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

# Create A Task

`POST /v1/browsing/tasks`

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/fastapi.md) · [All operations](https://skmtc.dev/yutori/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yutori/fastapi/revisions/ef669f82d5bc/schema)