Uploads a file to the `uploads` directory of the persistent file storage (files the agent can upload).

Upload File

Location

Message

Error Type

ValidationError

Body_upload_file_storage_upload_post

OAuth2PasswordBearer

FileUploadResponse

HTTPValidationError

nottelabs

Quickstart

Python SDK

Sessions

Web Agents

Enterprise-grade credential management for your Sessions & Agents

Vaults

Self-service identities for web automation (account creation, 2FA,etc.)

Persona

Notte BUA

Route your automation traffic with precision & control

Proxies

Connect to Notte Sessions using CDP in Playwright

Replay and inspect your automation sessions

Session Replay

Upload and manage cookies for your sessions

Cookies

Extending AI Systems with Browser Control Capabilities

MCP Server

Integrate OpenAI CUA with Notte Browser Sessions

OpenAI CUA

Integrate Notte with Cursor through MCP Server

Cursor

Get debug information for a session including WebSocket endpoints for CDP, recording, and logs.

The debug URL can be opened in a browser for live session monitoring (only availble when session is active)

Session Debug Info

Retrieve the WebP format visual replay of a session's execution.

Detect available actions on a webpage within the session's environment.

Returns a snapshot of the current state including available actions, metadata, and optional screenshot.

The optional `url` parameter is used to navigate to a specific URL before observing the page.
If not provided, the session will remain on the current page.

Observe

Execute an action in the browser session and observe the resulting state.

The step endpoints should only be used after a previous observe (or another step) call.
Observations give you a snapshot of the current state, including available actions.
Stepping allows you to execute an action and observe the resulting state.

Example of a step request:
```json
{
    "action_id": "I1",
    "value": "Paris",
}
```

Returns a new observation of the new state after executing the specified action.

Step

Extract content from a webpage within the session's environment.

Supports various extraction modes including link scraping and main content extraction.
Can optionally use LLM for more sophisticated content extraction.

Scrape

List all sessions for the authenticated user.

By default, returns the last 10 active sessions.
Sessions are ordered by creation date (newest first).
No pagination is currently supported.

List Sessions

Start a new browser session.
Configure timeout, max steps, proxies, and browser type in the request.

Important information:
* The maximum session duration is set to 30 minutes and cannot be changed.
* However, the `session_timeout` parameter in the request allows you to specify a timeout for the session steps (defaults to 3 minutes). This timeout is triggered on session inactivity, i.e when no operation (i.e agents, scrape, observe, steps, etc.) is performed for a while.
* You can turn on proxies in the request to increase the chances of bypassing bot detection mechanisms (for an additional cost).
* Different browser types are available with different security measures in place to prevent detection. If you are flagged as a bot try to switch to chrome or firefox instead of chromium

Start Session

Get the current status of a session, including its metadata and state.

You can retrieve the status of a session at any time whether it is active or not.

Session states also contain all steps (i.e actions and observations) performed during the session.
You can use this information to reconstruct the session execution and diagnose potential issues.

Session Status

Manually close an active session.
The session will be marked as closed and resources will be released.

Only sessions that are active can be stopped (othertherise a 404 error is returned).

Note: billing is based on session durations (i.e session start and stop times).

Stop Session

Get cookies that are in the currently running session

Get Cookies

Upload cookies to a session. These cookies will be available throughout the session duration.

Note: Cookies are not saved or processed by Notte. Ensure cookies are valid for your target domain and not expired.
For local cookie generation, use a headful browser session and save the cookies using the provided script.

Set Cookies

Initiates a new agent task execution.

This endpoint starts an agent that will perform the specified task. The agent can optionally navigate
to a provided URL before attempting to solve the task.

This agent is non-blocking and will return immediately. You should periodically check the status of the agent
until it is `closed`.

Important points:
* Remember that you can attach a `vault_id` to the agent to allow it to access credentials stored in your vault.
* Sometimes LLM providers have outages or cluster issues. Try to switch to a different reasoning model if that occurs.
* Not all models support vision. Check `litellm` documentation for more details.
* You can debug your agent execution by checking the `replay` endpoint.

Start Agent

Retrieves the current status of a specific agent.

Parameters:
- agent_id: Unique identifier of the agent to check

The most important fields are:
- success: Whether the agent task was successful (None if still running)
- answer: The answer to the agent task (None if still running)

Also you can check the `steps` field to better understand which actions where taken by the agent.

Get Agent Status

Forcefully terminates a running agent task.

> **Note:** a agent manually stopped will result in a failure for the agent to solve the task.

Furthermore, you can only stop an agent if it is still running, otherwise a 404 error will be raised.

Stop Agent

Retrieves the visual replay of an agent's execution session (in WebP format).

Returns:
- FileResponse: WebP format file containing the session replay
- HTTPException(404): If no replay is found for the specified agent

Get Agent Replay

Retrieves a list of all agents associated with the authenticated user.

Parameters:
- request: AgentListRequest containing:
    - only_active: Whether to only return active agents
    - limit: Maximum number of agents to return

List Agents

Saves an agent's trajectories as a frequent workflow to be used later.

Save Agent

BUA acts similarly to the typical [computer-use completion model](https://platform.openai.com/docs/models/computer-use-preview).
At a high level, BUA will look at a screenshot and the DOM elements of the browser interface and output an action, that can easily be executed from any browser driver.

The Notte Reasoning Agent then looks at the user's task and Web page content to decide what action(s) to take to take next. This is the output of this endpoint.

Browser Using Agent Completions

Create a vault for storing card / credentials

This vault can only be accessed by the user & api key that created it.
Keep the vault id secret and store it safely. It will only be displayed once.

Returns:
- `vault_id`: ID of the created vault

Create Vault

Get stored credentials for provided url

Only the root domain of the url is matching against the credentials. I.e

```python
url = "https://www.github.com/login"
```
will be used to match any request for `*.github.com/*` (subdomains are also matching).

> **Note:** credentials are encrypted and only you can access them.

Get Credentials

Add credentials to the vault for a specific url

Only the root domain of the url is matching against the credentials. I.e

```python
url = "https://www.github.com/login"
```
will be used to match any request for `*.github.com/*` (subdomains are also matching).

> **Note:** credentials are encrypted and only you can access them.

Credentials include:
    - username: if no email defined
    - email: if no username defined
    - password: the password to store
    - mfa_secret: optional, the mfa secret to store

Returns:
- `status`: status of the created credentials (one of `success`, `error`)

Add Credentials

Delete Credentials

List Credentials

Delete provided vault

> All credentials and credit cards stored in the vault will be deleted.

Delete Vault

Get Credit Card

Store a credit card within the vault

All credit card details are encrypted and only you can access them.

Set Credit Card

Delete Credit Card

List Vaults

Improve Prompt

Nudge Prompt

Get Usage

Get Usage Logs

Returns a temporary URL which can be used to download a file from file storage attached to a session.

The session must have a FileStorage object attached to it when it was created (otherwise a 404 error is returned).
The file must exist in the storage (otherwise a 404 error is returned).

Note: For closed sessions use `/download` instead.

Download File

Gets a list of all the filenames in the `downloads` directory (files the agent downloaded) for a session.

The session must have a FileStorage object attached to it when it was created (otherwise a 404 error is returned).

Note: For closed sessions use `/download/list` instead.

List Files Download

Returns a temporary URL which can be used to download a file from file storage attached to a session.

The session must have had a FileStorage object attached to it when it was created (otherwise a 404 error is returned).
The file must exist in the storage (otherwise a 404 error is returned).

Note: For active sessions use `/{session_id}/download` instead.

Download File Fallback

Gets a list of all the filenames in the `downloads` directory (files the agent downloaded) for a session.

The session must have had a FileStorage object attached to it when it was created (otherwise a 404 error is returned).

Note: For active sessions use `/download/list` instead.

List Files Download Fallback

Gets a list of all the filenames in the `uploads` directory (files the agent can upload).

List Files Upload

Provide the health status of the service.

The response includes:
- the status of the service
- the current version
- a description of the service

Health Check

Scrape the url provided in the request body.
Note that a session is automatically created and closed when the scrape is done.

If you need more control over the session creation (i.e proxy, etc.). You should manage the session manually
and use the `sessions/{session_id}/page/scrape` endpoint.

debug

page

sessions

agents

bua

vaults

prompts

usage

API Reference

health

scrape

Upload File

Authorizations

Body

Response