Browser - Naïve

All browser routes are per-tenant-user and mounted under /v1/users/:user_id/browser. The subject is resolved + cross-tenant-guarded, and the browser primitive must be enabled in the user’s Account Kit. Use default as the user_id to target the workspace’s default user. Auth:

Agent-driving routes (create/navigate/act/extract/observe/screenshot/signup/login/close, save-credential, save-login) require an agent API key (Authorization: Bearer nv_sk_…).
Human-only routes (live-view, grant, revoke) require a dashboard session cookie — an agent key is rejected.

act and navigate require an Idempotency-Key header.

Sessions

List sessions

GET /v1/users/{user_id}/browser/sessions

{
  "sessions": [
    {
      "session_id": "…",
      "status": "active",
      "allowed_domains": ["example.com"],
      "context_backed": false,
      "credits_consumed": 8.35,
      "created_at": "…",
      "last_used_at": "…",
      "timeout_at": "…",
      "closed_at": null
    }
  ]
}

Create a session

POST /v1/users/{user_id}/browser/sessions

Field	Type	Notes
`allowed_domains`	string[]	Required. Allowlist (default-deny). `["*"]` = unrestricted.
`allow_writes`	boolean	Permit write/destructive actions. Default false.
`timeout_minutes`	number	Hard TTL (default 15, max 30).
`context_name`	string	Reopen a saved login by name (requires a grant).
`human_login`	boolean	Open a human first-login session.
`allow_extract`	boolean	On a saved-login session, permit reads.
`proxy`	boolean	Residential proxy egress (requires scoped `allowed_domains`).

Returns 201 with { session_id, status, timeout_at, allow_writes, allowed_domains }. Opening a session costs 0 credits; a time floor is charged at close.

Get / close a session

GET    /v1/users/{user_id}/browser/sessions/{id}
DELETE /v1/users/{user_id}/browser/sessions/{id}

The status view never returns vendor pointers, connect URLs, or live-view links.

Driving a session

POST /v1/users/{user_id}/browser/sessions/{id}/navigate    # { "url": "..." }  (Idempotency-Key)
POST /v1/users/{user_id}/browser/sessions/{id}/act         # { "instruction": "..." } (Idempotency-Key)
POST /v1/users/{user_id}/browser/sessions/{id}/extract     # { "instruction": "..." }
POST /v1/users/{user_id}/browser/sessions/{id}/observe     # { "instruction": "..." }
POST /v1/users/{user_id}/browser/sessions/{id}/screenshot  # → { url, expires_in: 300 }

navigate enforces the allowlist + an SSRF denylist. act rejects write-looking instructions unless the session was created with allow_writes. extract/observe/screenshot are read-restricted + redacted on a logged-in (context-backed) session unless opened with allow_extract. act returns 200 only if the action actually happened. If the browser could not perform it — no matching element, or the click did nothing — that is 502 provider_error, not a 200 carrying success: false. The page is unchanged, the attempt is still billed, and details carries the same action_taken, url, credits_used and credits_remaining a success would have returned. Call observe to list what is actually actionable on the current page, then retry naming one of those elements. Self-contained: each opens its own write-enabled session scoped to the URL’s host, drives the form with the credential filled server-side (the password is never sent to the model or returned), and closes the session.

POST /v1/users/{user_id}/browser/signup

{ "service": "figma.com", "url": "https://www.figma.com/signup" }

Generates a strong password, stores { email, password } in the user’s Vault under login:<service>, fills + submits the registration form. Sensitive: when the kit requires approval, responds 202 with { "status": "pending_approval", "approval_id": "…" } and runs only after approval. Optional allowed_domains, timeout_minutes.

POST /v1/users/{user_id}/browser/login

{ "service": "figma.com", "url": "https://www.figma.com/login" }

Reads the vaulted credential for the service and fills + submits the login form. Returns 404 if no credential is stored. Optional allowed_domains, timeout_minutes.

Save a credential

POST /v1/users/{user_id}/browser/credentials

{ "service": "figma.com", "email": "agent@my-inbox.usenaive.app", "password": "…", "username": "optional" }

Stores a user-provided credential in the Vault under login:<service> so a later login can use it server-side. Use this instead of typing a password into a form via act (the value never has to pass through the model). email and password are required; username is optional. Returns 201 with { "service": "figma.com", "saved": true }.

Saved logins (Tier B)

POST   /v1/users/{user_id}/browser/sessions/{id}/context        # save a completed human login (agent)
POST   /v1/users/{user_id}/browser/contexts/{name}/grants       # grant an agent/role access (HUMAN-only)
DELETE /v1/users/{user_id}/browser/contexts/{name}              # revoke + delete the saved login (HUMAN-only)

Grant body: { "grantee_type": "agent" | "role", "grantee_id": "<agent uuid or role name>" }. Grants and revocation are human-only (session cookie); an agent key is rejected. Revoke is irreversible and affects every grantee.

Live view (human-only)

GET /v1/users/{user_id}/browser/sessions/{id}/live-view   # → { live_view_url }

Returns an embeddable Browserbase live-view URL for an active/in_use session, generated on demand and never persisted. The URL is unauthenticated and grants control, so it is only served to an authenticated human (dashboard) — never on any agent surface. Embed it in a sandboxed iframe (the dashboard Browser tab does this).

​Sessions

​List sessions

​Create a session

​Get / close a session

​Driving a session

​Autonomous signup & login

​Signup (approval-gated)

​Login

​Save a credential

​Saved logins (Tier B)

​Live view (human-only)