> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yutori.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create A Task
> Launches a website navigation agent to execute the task on a cloud browser.
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
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())
```
```javascript JavaScript theme={null}
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
Configure structured output with `output_schema` to receive data in a specific JSON schema format, and optionally add webhook notifications.
```bash cURL theme={null}
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" }
}
}
}
}'
```
```python Python theme={null}
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())
```
```javascript JavaScript theme={null}
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();
```
## OpenAPI
````yaml POST /v1/browsing/tasks
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.yutori.com
description: Production
security:
- ApiKeyAuth: []
paths:
/v1/browsing/tasks:
post:
tags:
- Browsing
summary: Create A Task
description: >-
Launches a website navigation agent to execute the task on a cloud
browser.
operationId: agent_run_endpoint_v1_browsing_tasks_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentRunRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
AgentRunRequest:
properties:
output_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Output Schema
description: >-
JSON Schema for structured output. Takes precedence over task_spec
if both provided.
examples:
- 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:
anyOf:
- $ref: '#/components/schemas/TaskSpec'
- type: 'null'
description: Deprecated but still supported. Use output_schema instead.
deprecated: true
used_deprecated_task_spec:
type: boolean
title: Used Deprecated Task Spec
default: false
hidden: true
task:
type: string
title: Task
description: String describing the browsing task in natural language.
examples:
- Give me a list of all employees (names and titles) of Yutori.
start_url:
type: string
title: Start Url
description: URL to open before running the task
examples:
- https://yutori.com
max_steps:
anyOf:
- type: integer
maximum: 100
minimum: 2
- type: 'null'
title: Max Steps
description: Maximum number of steps the agent can take
examples:
- 50
agent:
anyOf:
- type: string
- type: 'null'
enum:
- navigator-n1.5-latest
- claude-sonnet-4-5-computer-use-2025-01-24
- null
title: Agent
description: >-
Which agent to use for the browsing task. Defaults to
navigator-n1.5-latest.
examples:
- navigator-n1.5-latest
require_auth:
type: boolean
title: Require Auth
description: >-
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.
default: false
browser:
anyOf:
- type: string
enum:
- cloud
- local
- type: 'null'
title: Browser
description: >-
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:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Optional webhook URL to receive the agent.run result for the calling
user using webhook_format.
examples:
- https://example.com/webhook
webhook_format:
type: string
enum:
- scout
- slack
- zapier
title: Webhook Format
description: >-
Webhook payload format to use when webhook_url is provided. Slack
incoming webhook URLs require 'slack'.
default: scout
examples:
- scout
type: object
required:
- task
- start_url
title: AgentRunRequest
AgentRunResponse:
properties:
task_id:
type: string
title: Task Id
description: Unique identifier for this browsing task
view_url:
type: string
title: View Url
status:
type: string
enum:
- queued
- running
- succeeded
- failed
title: Status
result:
anyOf:
- type: string
- type: 'null'
title: Result
paused:
anyOf:
- type: boolean
- type: 'null'
title: Paused
structured_result:
anyOf:
- additionalProperties: true
type: object
- items: {}
type: array
- type: 'null'
title: Structured Result
description: >-
If an output schema was provided, the result formatted as JSON
matching that schema
structured_output_status:
anyOf:
- type: string
enum:
- not_requested
- pending
- succeeded
- failed
- type: 'null'
title: Structured Output Status
description: >-
Whether structured output was requested, is still pending,
succeeded, or failed
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Echoes the webhook URL configured for this agent.run request, if
provided.
rejection_reason:
anyOf:
- $ref: '#/components/schemas/RejectionReason'
- type: 'null'
description: If status is 'failed', the specific billing reason for rejection
type: object
required:
- task_id
- view_url
- status
title: AgentRunResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
TaskSpec:
properties:
output_schema:
anyOf:
- $ref: '#/components/schemas/JsonSchemaSpec'
- type: 'null'
type: object
title: TaskSpec
RejectionReason:
type: string
enum:
- insufficient_prepaid_balance
- budget_exceeded
- subscription_inactive
title: RejectionReason
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
JsonSchemaSpec:
properties:
type:
type: string
const: json
title: Type
default: json
json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Schema
description: A JSON Schema object defining the structure
type: object
title: JsonSchemaSpec
securitySchemes:
ApiKeyAuth:
type: apiKey
name: x-api-key
in: header
````