Skip to main content
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": 7,
      "created_at": "…",
      "last_used_at": "…",
      "timeout_at": "…",
      "closed_at": null
    }
  ]
}

​
Create a session

POST /v1/users/{user_id}/browser/sessions
FieldTypeNotes
allowed_domainsstring[]Required. Allowlist (default-deny). ["*"] = unrestricted.
allow_writesbooleanPermit write/destructive actions. Default false.
timeout_minutesnumberHard TTL (default 15, max 30).
context_namestringReopen a saved login by name (requires a grant).
human_loginbooleanOpen a human first-login session.
allow_extractbooleanOn a saved-login session, permit reads.
proxybooleanResidential 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.

​
Autonomous signup & login

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.

​
Signup (approval-gated)

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.

​
Login

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