Browser

The option object, guards and lifetime are in the Browser guide. This page is the routes.

A computer created with a browser block carries one browser session. The first action opens it; DELETE closes it. Every route below takes the computers:write scope unless it says otherwise. Three routes — live view, granting and revoking a saved login — answer only a signed-in dashboard session: an API key gets 403 forbidden whatever its scopes.

The browser session object

string

Unique id (e.g. brw_01H...).

string

Always browser_session.

string | null

The computer the browser runs on.

string | null

The agent session whose browser tool opened it; null for a browser opened over the API.

string

creating, active, closed or error.

string[]

The allow-list every action is checked against.

string

us-west, us-east, eu-central or ap-southeast.

string | null

The saved login (bct_) this session reopened, if any.

boolean

true when the session carries a saved login — extract, observe, links and screenshot then need allow_extract.

string

When the session closes on its own (timeout_minutes after it opened). A sweep on the platform clock closes and bills any session past it within a minute; the row is then closed like one you deleted.

string

When the browser came up.

string | null

When it closed; null while open.

string

Creation timestamp.

The live-view URL and the upstream connect URL are bearer credentials. Neither is a field on this object, and neither appears in a tool result, an event or a log.

Perform an action

POST /v1/computers/{id}/browser/actions — opens the browser lazily on the first call. The body is one action, discriminated on action. Idempotency-Key is required for goto and act and optional elsewhere.

`action`	body	how it runs
`goto`	`{ url }`	deterministic
`click`	`{ selector }`	deterministic
`type`	`{ selector, text }`	deterministic; credential-shaped `text` is refused
`extract`	`{ instruction?, selector?, schema? }`	selector only → the element’s text; with `instruction`/`schema` → model-driven, shaped to `schema`
`act`	`{ instruction, variables? }`	model-driven; `%name%` placeholders are filled from `variables`
`observe`	`{ instruction }`	model-driven → candidate elements
`links`	`{ contains?, limit? }`	deterministic; `limit` defaults to 50, max 200
`screenshot`	`{}`	deterministic → a `fil_` file

curl https://api.vetta.sh/v1/computers/cmp_01H.../browser/actions \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Idempotency-Key: 5f3b0e2e-1" \
  -H "Content-Type: application/json" \
  -d '{ "action": "act", "instruction": "search for %term%", "variables": { "term": "vetta" } }'

Every action answers the same object:

string

Always browser_action.

string

The action that ran.

string

The page URL after the action.

string | null

extract without a schema: the text read.

unknown | null

extract with a schema: the data, in that shape.

object[] | null

links: [{ href, text }].

object[] | null

observe: [{ selector, description }].

string | null

screenshot: the fil_ id of the PNG. Never the bytes.

boolean

Always true on a 200. An act that did nothing is a 502 provider_error, not a 200 with false.

variables values are never echoed — not in the result, not in the event, not in the audit row.

What is refused

Guard	Error
Page URL off the allow-list, or a private, loopback or metadata host — checked before and after every action	`403 forbidden`, `param: url`
Write-looking `act`, `click` or `type` (submit, purchase, delete, send, pay, confirm) without `allow_writes`	`403 forbidden`, `param: allow_writes`
Credential-shaped `type.text` or `act.instruction` (password, token and key patterns; vault values are sealed and never compared) — credentials travel only through login	`400 validation_failed`, `param: text` / `instruction`
`extract`, `observe`, `links` or `screenshot` on a context-backed session without `allow_extract`	`403 forbidden`, `param: allow_extract`
An `act` the automation could not perform	`502 provider_error`
A `context_name` the calling agent has no grant for	`403 forbidden`, `param: context_name`
A `context_name` that names a saved login on more than one identity — the lookup is organization-wide by name, and a computer’s options carry no identity to pick one	`400 validation_failed`, `param: context_name`

Name saved logins uniquely across the organization if more than one identity will hold them: shop-ava rather than two shops. A name is unique per identity at save time, so the collision only arises across identities.

Read the session

GET /v1/computers/{id}/browser → the browser session, or 404 not_found when none is open.

Close the session

DELETE /v1/computers/{id}/browser — idempotent. The closed browser session (status: closed, closed_at set), or 204 when nothing was open. Closing settles the session’s minutes on the browser line item, capped at timeout_at, and, on a session opened with persist_context or human_login, writes its cookies and storage into the saved login.

Live view

GET /v1/computers/{id}/browser/live-view — dashboard session only. A browser_live_view ({ object, url, expires_at }) for the one browser currently open; the URL is a bearer credential and is never logged or put in an event. An API key gets 403 forbidden. The dashboard’s Browser tab on a computer renders it, and lists every browser the computer ever drove — see Browser sessions. Never hand the URL to an agent or store it. POST /v1/computers/{id}/browser/context → 201 browser_context A saved login is bound when a browser opens: the engine attaches it at session start and flushes cookies and storage into it at close. This call therefore has two moments:

No browser open on the computer — creates the empty saved login under name, owned by an identity. Open the next browser with context_name (and human_login or persist_context) to fill it.
A browser open with that context_name — marks the login saved and releases the human_login lock; the same bct_ comes back and the close persists the login.

On a browser open without that context the call is 400 validation_failed (param: context_name): nothing that browser holds can reach the saved login.

string

required

1–64 characters; unique per identity.

string

required

The idn_ that owns the saved login.

string

What the login is for, e.g. figma.com.

string

bct_ id.

string

Always browser_context.

string

The owning identity.

string

The name a later context_name reopens.

string | null

As given.

string

Creation timestamp.

string | null

When a session last reopened it.

POST /v1/browser/contexts/{name}/grants — dashboard session only → 201 browser_grant A saved login is default-deny: a session may reopen it only when its agent — or the agent’s member role — holds a grant. The same grantee twice is a 200 replay of the existing grant; a new one reaches your webhooks as browser.context.granted. Over the REST API, an owner or admin dashboard session — or an API key holding the admin scope — opens every saved login of the organization without a grant; a member session, and any other API key, needs the member role grant; an agent’s browser tool needs a grant by its agt_ id or by role.

string

required

The identity that owns {name}.

string

required

agent or role.

string

required

An agt_ id, or owner / admin / member.

string

bgr_ id.

string

Always browser_grant.

string

The bct_ granted.

string

agent or role.

string

As given.

string

Creation timestamp.

DELETE /v1/browser/contexts/{name}?identity_id=idn_... — dashboard session only. Deletes the saved login and every grant on it. identity_id is required. Webhooks receive browser.context.revoked { context_id }.

Log in with a saved credential

POST /v1/computers/{id}/browser/login → browser_action Reads the identity’s vault credential login:<service> and fills the form through %username% and %password% placeholders. The plaintext never enters the model or a result.

string

required

The credential’s service, e.g. figma.com.

string

required

The sign-in page.

string

required

Whose vault to read.

POST /v1/computers/{id}/browser/signup → browser_action Generates a password, stores it as login:<service> in the identity’s vault, then runs the sign-up flow with it. When an agent’s browser tool does this, the session always pauses for a person to confirm — see Tools.

string

required

The service being joined.

string

required

The sign-up page.

string

required

Whose vault receives the credential.

string

required

The address to register.

Save a credential

POST /v1/browser/credentials → the vault credential’s metadata Seals login:<service> into the identity’s vault so login can use it. The reply is metadata — no route ever returns the value.

string

required

Whose vault.

string

required

The service, e.g. figma.com.

string

required

The account’s email.

string

required

Write-only.

string

When the site signs in by username rather than email.

Errors

forbidden, validation_failed, not_found, context_locked (409 — a human_login flow holds the saved login for 15 minutes), provider_error (502), computer_unavailable, rate_limited, feature_not_configured. See Errors.

Introduction

Core resources

Platform

Identity

The browser session object

Perform an action

What is refused

Read the session

Close the session

Live view

Log in with a saved credential

Save a credential

Errors

​The browser session object

​Perform an action

​What is refused

​Read the session

​Close the session

​Live view

​Save a login

​Grant a saved login

​Revoke a saved login

​Log in with a saved credential

​Sign up

​Save a credential

​Errors

The browser session object

Perform an action

What is refused

Read the session

Close the session

Live view

Save a login

Grant a saved login

Revoke a saved login

Log in with a saved credential

Sign up

Save a credential

Errors