> ## 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.
# Get Started
```bash cURL theme={null}
curl --request POST \
--url https://api.yutori.com/v1/chat/completions \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"model": "n1.5-latest",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Click on the search bar and type Yutori."
},
{
"type": "image_url",
"image_url": {
"url": "https://docs.yutori.com/assets/google_homepage_2024.jpg"
}
}
]
}
]
}'
```
```python Python theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://api.yutori.com/v1",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="n1.5-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Click on the search bar and type Yutori."
},
{
"type": "image_url",
"image_url": {
"url": "https://docs.yutori.com/assets/google_homepage_2024.jpg"
}
}
]
}
]
)
```
```javascript JavaScript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.yutori.com/v1",
apiKey: "YOUR_API_KEY",
});
const response = await client.chat.completions.create({
model: "n1.5-latest",
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Click on the search bar and type Yutori.",
},
{
type: "image_url",
image_url: {
url: "https://docs.yutori.com/assets/google_homepage_2024.jpg",
},
},
],
},
],
});
```
```json 200 theme={null}
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"model": "n1.5-latest",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I can see the Google homepage. I'll click on the search bar to begin searching for Yutori.",
"tool_calls": [
{
"id": "chatcmpl-tool-abc123",
"type": "function",
"function": {
"name": "left_click",
"arguments": "{\"coordinates\": [640, 400]}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 1234,
"completion_tokens": 56,
"total_tokens": 1290
},
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
## Overview
The **Navigator** API provides a computer-use model family that predicts actions to interact with a browser. Given a task in natural language, the current screenshot, and the full action history, the model predicts the next action to take to accomplish the task.
The API follows the OpenAI `chat.completions` format. The latest model is:
| Model | API model id | Description |
| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Navigator n1.5** | `n1.5-latest` | Computer-use model with expanded action space, selectable tool sets, and JSON structured output. [Details →](/reference/n1-5) |
Want to try Navigator without writing code?
* [**Navigator Browser Extension**](/reference/navigator-browser-extension) — test and explore in your own local browser
* [**Yutori Local**](https://api.yutori.com/download/desktop) — Mac desktop app that gives our agents access to a browser on your computer, enabling login-required workflows and local browsing tasks
## Screenshot Requirements
Screenshots should capture only the browser content itself. Do **not** include the operating system UI, window title bars, browser tabs, URL bars, or other chrome elements.
For the best performance, render screenshots in **WXGA (1280×800, 16:10)**. The model should generalize well to most other resolutions, but grounding accuracy may degrade with extreme aspect ratios.
We recommend using the **WebP** format for screenshots, as it offers significantly better compression than PNG — especially for multi-step trajectories with many images.
The [Python SDK](https://github.com/yutori-ai/yutori-sdk-python) provides helpers that handle resizing, WebP conversion, and base64 encoding:
```bash theme={null}
pip install yutori
```
```python theme={null}
from yutori.navigator import screenshot_to_data_url, playwright_screenshot_to_data_url
# From raw screenshot bytes (any format)
image_url = screenshot_to_data_url(screenshot_bytes)
# Or directly from a Playwright page
image_url = playwright_screenshot_to_data_url(page)
# Async variant also available
# image_url = await aplaywright_screenshot_to_data_url(page)
```
See [`yutori.navigator.images`](https://github.com/yutori-ai/yutori-sdk-python/blob/main/yutori/navigator/images.py) for full options (custom resolution, quality settings).
## Coordinate System
All Navigator models output **normalized coordinates in a 1000×1000 space**. Convert to absolute pixel coordinates before executing actions in your browser:
```python theme={null}
from yutori.navigator import denormalize_coordinates
pixel_x, pixel_y = denormalize_coordinates(
coordinates=[640, 400],
width=viewport_width,
height=viewport_height,
)
```
See [`yutori.navigator.coordinates`](https://github.com/yutori-ai/yutori-sdk-python/blob/main/yutori/navigator/coordinates.py) for the inverse `normalize_coordinates` function.
## Response Format
Actions are returned via the `tool_calls` field in the response message:
```json theme={null}
{
"choices": [
{
"message": {
"role": "assistant",
"content": "I'll click on the search bar.",
"tool_calls": [
{
"id": "chatcmpl-tool-abc123",
"type": "function",
"function": {
"name": "left_click",
"arguments": "{\"coordinates\": [640, 400]}"
}
}
]
},
"finish_reason": "tool_calls"
}
]
}
```
The `content` field contains the model's reasoning, `tool_calls` contains the predicted action(s), and `request_id` is a unique identifier useful for debugging.
When the model intends to stop, it returns a response with only `content` text and no `tool_calls`. This `content` field is the model's final response to the task.
## Multi-Turn Conversations
The model expects full chat history to best predict the next action. We do not recommend removing **any** messages when constructing requests. For longer trajectories, we suggest dropping *only* old screenshots while keeping every message intact.
Always keep a **minimum of the 2 most recent screenshots**, and **never send a request with no screenshot at all**. Requests that carry only stale screenshots (or none) sharply degrade grounding and can cause the model to loop or hallucinate.
The Python SDK provides `create_trimmed` / `acreate_trimmed` (in `yutori.navigator`) which strip older screenshots automatically while preserving recent ones and all text — by default keeping the **6 most recent** screenshots (and always the latest), and only trimming when a request would otherwise exceed the size limit.
Include the assistant's previous response with its `tool_calls`, followed by tool results with the new screenshot:
```python theme={null}
response = client.chat.completions.create(
model="n1.5-latest",
messages=[
# Initial user message with task and first screenshot
{
"role": "user",
"content": [
{"type": "text", "text": "Search for Yutori on Google."},
{"type": "image_url", "image_url": {"url": f"data:image/webp;base64,{screenshot_1}"}}
]
},
# Assistant's response with tool call
{
"role": "assistant",
"content": "I can see the Google homepage. I'll click on the search bar.",
"tool_calls": [
{
"id": "chatcmpl-tool-123",
"type": "function",
"function": {
"name": "left_click",
"arguments": "{\"coordinates\": [500, 465]}"
}
}
]
},
# Tool result with current URL and new screenshot
{
"role": "tool",
"tool_call_id": "chatcmpl-tool-123",
"content": [
{"type": "text", "text": "Clicked 1x with left\nCurrent URL: https://www.google.com/"},
{"type": "image_url", "image_url": {"url": f"data:image/webp;base64,{screenshot_2}"}}
]
}
]
)
```
The tool result can be a short description of what the tool did or whether it was successful. Including the current URL in the tool response is important for better attribution of information sources.
If the tool extracts additional information (e.g. `extract_elements`, `execute_js`), the raw output of the tool can be provided as the tool result so the model also has visibility of the extracted information.
## Custom Tools
You can provide additional tools alongside the built-in browser actions using the `tools` parameter. Custom tools are appended after the default tool set.
```python theme={null}
response = client.chat.completions.create(
model="n1.5-latest",
messages=[...],
tools=[
{
"type": "function",
"function": {
"name": "extract_content_and_links",
"description": "Extracts page content and hyperlinks relevant to the user task. This operation is strictly read-only and never interacts with or alters the page.",
"parameters": {"type": "object", "properties": {}, "required": []}
}
}
]
)
```
Results of custom tool calls should also be provided as a tool response so the model can use it for subsequent decisions:
```python theme={null}
{
"role": "tool",
"tool_call_id": "chatcmpl-tool-456",
"content": [
{
"type": "text",
"text": "Visible buttons and links:\n- About https://about.google/\n- Store https://store.google.com/\n- Gmail https://mail.google.com/\nCurrent page URL: https://www.google.com/"
},
{
"type": "image_url",
"image_url": {"url": f"data:image/webp;base64,{screenshot}"}
}
]
}
```
## Tool Choice
Control whether tool calls are parsed into the `tool_calls` array:
* `"auto"` (default): Parses and returns tool calls as a structured `tool_calls` list
* `"none"`: Returns the raw model response as content text (tool calls may still appear inside `` XML tags in content)
## Prompting Guidance
We use a default system prompt when none is provided, and generally **do not recommend providing custom system prompts** — extra behavioral instructions may degrade results.
Instead, place additional instructions in the **first user message**, after the main task description:
```json theme={null}
{
"messages": [
{
"role": "user",
"content": "Click the login button. Additional instructions: be careful with popups."
}
]
}
```
We also recommend **not interrupting trajectory execution** with additional user messages, except to force the model to stop and summarize:
```python theme={null}
messages.append({
"role": "user",
"content": f"Stop here. Summarize your current progress and list all findings relevant to: {task}"
})
```
## Structured Decoding
By default, the API uses a `structural_tag` response format to enforce valid tool call generation via guided decoding. You do **not** need to provide this yourself — the API generates it automatically based on the active model and tool set. If custom tools are included in your request, their schemas are automatically incorporated.
We do not recommend overriding the `response_format` unless you also set `tool_choice="none"` to work with the raw model output directly.
## OpenAPI
````yaml POST /v1/chat/completions
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.yutori.com
description: Production
security:
- ApiKeyAuth: []
paths:
/v1/chat/completions:
post:
tags:
- Chat Completions
summary: Create Chat Completion
operationId: create_chat_completion_v1_chat_completions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
components:
schemas:
ChatCompletionRequest:
properties:
messages:
items:
anyOf:
- $ref: '#/components/schemas/ChatCompletionDeveloperMessageParam'
- $ref: '#/components/schemas/ChatCompletionSystemMessageParam'
- $ref: '#/components/schemas/ChatCompletionUserMessageParam'
- $ref: '#/components/schemas/ChatCompletionAssistantMessageParam'
- $ref: '#/components/schemas/ChatCompletionToolMessageParam'
- $ref: '#/components/schemas/ChatCompletionFunctionMessageParam'
- $ref: '#/components/schemas/ChatCompletionToolImageMessageParam'
- $ref: '#/components/schemas/ChatCompletionObservationMessageParam'
type: array
title: Messages
model:
type: string
enum:
- n1.5-latest
- n1.5-20260428
title: Model
max_completion_tokens:
type: integer
title: Max Completion Tokens
default: 1572
temperature:
anyOf:
- type: number
- type: 'null'
title: Temperature
default: 0.3
top_p:
anyOf:
- type: number
- type: 'null'
title: Top P
repetition_penalty:
anyOf:
- type: number
- type: 'null'
title: Repetition Penalty
description: >-
Penalizes token repetition. 1.0 = no penalty, >1.0 = less
repetition. Only supported by vLLM-backed models.
presence_penalty:
anyOf:
- type: number
- type: 'null'
title: Presence Penalty
frequency_penalty:
anyOf:
- type: number
- type: 'null'
title: Frequency Penalty
tools:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Tools
description: >-
Additional tools to extend the default browser action tools. Tools
are merged with the built-in browser actions (left_click, scroll,
type, etc.).
tool_choice:
anyOf:
- type: string
- additionalProperties: true
type: object
- type: 'null'
title: Tool Choice
description: >-
Controls whether tool calls are parsed from the response. Model
always decides whether to call a tool. 'none' treats the response as
text-only, but tool calls may be present inside `` tags,
'auto' (default) parses tool calls automatically as `tool_calls`
list in response.
default: auto
response_format:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Response Format
description: An object specifying the format that the model must output.
tool_set:
anyOf:
- type: string
- type: 'null'
title: Tool Set
description: >-
Named tool set (n1.5+ models only). 'browser_tools_core-20260403'
(default): coordinate-based tools.
'browser_tools_expanded-20260403': adds extract_elements, find,
set_element_value, execute_js.
disable_tools:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Disable Tools
description: >-
List of tool names to remove from the selected tool set (n1.5+
models only).
json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Schema
description: >-
JSON Schema for structured output (n1.5+ models only). Appended to
your task message. Model returns JSON in ```json fences, parsed and
returned as 'parsed_json' in the response.
prev_request_id:
anyOf:
- type: string
- type: 'null'
title: Prev Request Id
description: >-
The `request_id` returned by the previous Navigator call in this
conversation. Echo it back on each subsequent call to link the calls
into one conversation for usage reporting.
additionalProperties: true
type: object
title: ChatCompletionRequest
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ChatCompletionDeveloperMessageParam:
properties:
content:
anyOf:
- type: string
- items:
$ref: '#/components/schemas/ChatCompletionContentPartTextParam'
type: array
title: Content
role:
type: string
const: developer
title: Role
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- content
- role
title: ChatCompletionDeveloperMessageParam
ChatCompletionSystemMessageParam:
properties:
content:
anyOf:
- type: string
- items:
$ref: '#/components/schemas/ChatCompletionContentPartTextParam'
type: array
title: Content
role:
type: string
const: system
title: Role
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- content
- role
title: ChatCompletionSystemMessageParam
ChatCompletionUserMessageParam:
properties:
content:
anyOf:
- type: string
- items:
anyOf:
- $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
- $ref: '#/components/schemas/ChatCompletionContentPartImageParam'
- $ref: >-
#/components/schemas/ChatCompletionContentPartInputAudioParam
- $ref: '#/components/schemas/File'
type: array
title: Content
role:
type: string
const: user
title: Role
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- content
- role
title: ChatCompletionUserMessageParam
ChatCompletionAssistantMessageParam:
properties:
role:
type: string
const: assistant
title: Role
audio:
anyOf:
- $ref: '#/components/schemas/Audio'
- type: 'null'
content:
anyOf:
- type: string
- items:
anyOf:
- $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
- $ref: '#/components/schemas/ChatCompletionContentPartRefusalParam'
type: array
- type: 'null'
title: Content
function_call:
anyOf:
- $ref: '#/components/schemas/FunctionCall'
- type: 'null'
name:
type: string
title: Name
refusal:
anyOf:
- type: string
- type: 'null'
title: Refusal
tool_calls:
items:
anyOf:
- $ref: >-
#/components/schemas/ChatCompletionMessageFunctionToolCallParam
- $ref: '#/components/schemas/ChatCompletionMessageCustomToolCallParam'
type: array
title: Tool Calls
additionalProperties: true
type: object
required:
- role
title: ChatCompletionAssistantMessageParam
ChatCompletionToolMessageParam:
properties:
content:
anyOf:
- type: string
- items:
$ref: '#/components/schemas/ChatCompletionContentPartTextParam'
type: array
title: Content
role:
type: string
const: tool
title: Role
tool_call_id:
type: string
title: Tool Call Id
additionalProperties: true
type: object
required:
- content
- role
- tool_call_id
title: ChatCompletionToolMessageParam
ChatCompletionFunctionMessageParam:
properties:
content:
anyOf:
- type: string
- type: 'null'
title: Content
name:
type: string
title: Name
role:
type: string
const: function
title: Role
additionalProperties: true
type: object
required:
- content
- name
- role
title: ChatCompletionFunctionMessageParam
ChatCompletionToolImageMessageParam:
properties:
role:
type: string
const: tool
title: Role
content:
anyOf:
- type: string
- items:
anyOf:
- $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
- $ref: '#/components/schemas/ChatCompletionContentPartImageParam'
type: array
title: Content
tool_call_id:
type: string
title: Tool Call Id
additionalProperties: true
type: object
required:
- role
- content
- tool_call_id
title: ChatCompletionToolImageMessageParam
ChatCompletionObservationMessageParam:
properties:
role:
type: string
const: observation
title: Role
content:
anyOf:
- type: string
- items:
anyOf:
- $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
- $ref: '#/components/schemas/ChatCompletionContentPartImageParam'
type: array
title: Content
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- role
- content
title: ChatCompletionObservationMessageParam
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
ChatCompletionContentPartTextParam:
properties:
text:
type: string
title: Text
type:
type: string
const: text
title: Type
additionalProperties: true
type: object
required:
- text
- type
title: ChatCompletionContentPartTextParam
ChatCompletionContentPartImageParam:
properties:
image_url:
$ref: '#/components/schemas/ImageURL'
type:
type: string
const: image_url
title: Type
additionalProperties: true
type: object
required:
- image_url
- type
title: ChatCompletionContentPartImageParam
ChatCompletionContentPartInputAudioParam:
properties:
input_audio:
$ref: '#/components/schemas/InputAudio'
type:
type: string
const: input_audio
title: Type
additionalProperties: true
type: object
required:
- input_audio
- type
title: ChatCompletionContentPartInputAudioParam
File:
properties:
file:
$ref: '#/components/schemas/FileFile'
type:
type: string
const: file
title: Type
additionalProperties: true
type: object
required:
- file
- type
title: File
Audio:
properties:
id:
type: string
title: Id
additionalProperties: true
type: object
required:
- id
title: Audio
ChatCompletionContentPartRefusalParam:
properties:
refusal:
type: string
title: Refusal
type:
type: string
const: refusal
title: Type
additionalProperties: true
type: object
required:
- refusal
- type
title: ChatCompletionContentPartRefusalParam
FunctionCall:
properties:
arguments:
type: string
title: Arguments
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- arguments
- name
title: FunctionCall
ChatCompletionMessageFunctionToolCallParam:
properties:
id:
type: string
title: Id
function:
$ref: '#/components/schemas/Function'
type:
type: string
const: function
title: Type
additionalProperties: true
type: object
required:
- id
- function
- type
title: ChatCompletionMessageFunctionToolCallParam
ChatCompletionMessageCustomToolCallParam:
properties:
id:
type: string
title: Id
custom:
$ref: '#/components/schemas/Custom'
type:
type: string
const: custom
title: Type
additionalProperties: true
type: object
required:
- id
- custom
- type
title: ChatCompletionMessageCustomToolCallParam
ImageURL:
properties:
url:
type: string
title: Url
detail:
type: string
enum:
- auto
- low
- high
title: Detail
additionalProperties: true
type: object
required:
- url
title: ImageURL
InputAudio:
properties:
data:
type: string
title: Data
format:
type: string
enum:
- wav
- mp3
title: Format
additionalProperties: true
type: object
required:
- data
- format
title: InputAudio
FileFile:
properties:
file_data:
type: string
title: File Data
file_id:
type: string
title: File Id
filename:
type: string
title: Filename
additionalProperties: true
type: object
title: FileFile
Function:
properties:
arguments:
type: string
title: Arguments
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- arguments
- name
title: Function
Custom:
properties:
input:
type: string
title: Input
name:
type: string
title: Name
additionalProperties: true
type: object
required:
- input
- name
title: Custom
securitySchemes:
ApiKeyAuth:
type: apiKey
name: x-api-key
in: header
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Use Authorization: Bearer '
````