---
title: "Start a browser"
method: POST
path: "/browsers/start"
---

# Start a browser

`POST /browsers/start`

## Request

- Base URL: `https://oyabrowser.com`
- URL: `https://oyabrowser.com/browsers/start`
- Auth: HTTP bearer

Starts a browser as one of the caller's personas: on the key's provider, in a sandbox, or on a CDP endpoint the caller names (any Chrome with --remote-debugging-port). Answers 201 with the browser's id and its gateway CDP URL. A second start on an endpoint another browser already holds answers 409 endpoint_in_use; the body names the holder's id when it is yours.

## Request body

- object
  - `persona` string: A persona id, or "auto" for a fresh one.
  - `provider` string: cdp, oya-cloud, oya-selfhosted, or a vendor; defaults to the key's configured provider.
  - `wsUrl` string: For provider cdp: the ws://, wss:// or http:// address of the debugging port.
  - `name` string: A display name for the browser.

## Response `201`

The browser is ready to drive.

- object
  - `id` string
  - `provider` string
  - `persona` string
  - `status` string
  - `cdpUrl` string: The gateway CDP URL for this browser.

## Other responses

- `400`: A field was malformed; the body names it.
- `409`: Endpoint already held by a running browser (endpoint_in_use), or the session may not go on.
- `429`: The key or persona is at its browser quota.
- `502`: The provider or endpoint could not be reached.

---

[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)