---
title: "Chat with LLM-controlled browser"
method: POST
path: "/browsers/{browserId}/chat"
---

# Chat with LLM-controlled browser

`POST /browsers/{browserId}/chat`

## Request

- Base URL: `https://oyabrowser.com`
- URL: `https://oyabrowser.com/browsers/{browserId}/chat`
- Auth: HTTP bearer

Send a conversation to the LLM which uses browser tools to complete tasks. The LLM autonomously calls analyze_page, click, type, etc. until the task is done.

## Path parameters

- `browserId` string, required

## Request body

- object
  - `messages` object[], required: OpenAI-format chat messages
    - `role` 'user' | 'assistant' | 'system', required
    - `content` string, required
  - `data` object: Task values the agent may read, referred to as {{name}} in the prompt; a value may be a file() to upload
  - `secrets` object: Task values the agent never sees; typed through {{name}} placeholders
  - `schema` object: A JSON schema for the answer. The agent then finishes by returning data in this shape, answered as `data`

## Response `200`

Chat response

- object
  - `text` string: LLM's final text response
  - `toolCalls` object[]: Tools the LLM called during execution
    - `name` string
    - `args` object
  - `replayable` boolean: Whether the run acted on a page and can be saved as a playbook (POST /api/browsers/{browserId}/playbooks)
  - `failed` boolean: Whether the agent reports it could not do the task (its reply starts with FAILED:, or it ran out of steps)
  - `data` unknown
  - `usage` object: The tokens the run used, every model call included, as the provider reported them. Left out when the model reported none.
    - `input` integer: Prompt tokens, cached ones included
    - `output` integer: Completion tokens, reasoning included

## Other responses

- `400`: Invalid request
- `404`: Browser not connected
- `500`: Chat error

---

[API](https://skmtc.dev/oyabrowser/apis/oya-browser-api.md) · [All operations](https://skmtc.dev/oyabrowser/apis/oya-browser-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oyabrowser/apis/oya-browser-api/revisions/748c4b34f8e4?raw)