Browser Workflows

Browser Workflows is a separate control plane for reusable browser automation. The hierarchy is:

workspace → project → environment → workflow → immutable version → run

Authoring lifecycle

1. Create or select a workspace, project, and environment (development, staging, or production).
2. Create a workflow with an ordered declarative definition and output schema.
3. Create a draft version, validate it, publish the immutable version, then activate it.
4. Start a run or batch with the active version and poll its status.
5. Validate the result, inspect the action trace, and read masked evidence when evidence:read is available.

The initial workflow contract is a linear sequence of typed steps: navigate, click, fill, select, wait_for_selector, assert, extract, and download. It does not provide branches, loops, arbitrary JavaScript, or an arbitrary graph. A version is immutable after publish; changes create a new version.

Authentication and scopes

The Console uses the Client API and the signed-in user session. Server-to-server integrations use a Browser Workflow API key under /api/v1/browser/projects/{projectId}/environments/{environmentId}. Assign only the scopes required by the integration, for example workflows:read, workflows:write, runs:read, runs:write, batches:read, batches:write, evidence:read, webhooks:write, or cdp:connect.

Every non-GET write is idempotent when Idempotency-Key is supplied. Reuse a key only for the same operation and payload. 409 can mean stale optimistic-concurrency version, immutable published version, terminal run, budget conflict, or idempotency conflict; refetch the resource before offering a retry.

Runs, batches, and evidence

Runs move through queued, running, succeeded, failed, cancelled, or expired. The run DTO includes result, action_trace, result_metadata, quality_state, error_code, attempt_count, and expires_at. Batch endpoints return { items, next_cursor }, expose failure clusters, and support retrying failed items without replaying successful work.

Evidence is tenant-private and masked. An evidence item describes id, run_id, kind (masked_screenshot or masked_html), content_type, byte_length, sha256, expires_at, and a signed download_url. Do not persist signed URLs beyond their expiry.

Webhooks and CDP

Webhooks deliver terminal events at least once. Use an https:// endpoint, verify the signature and timestamp, and deduplicate on the event ID. A replay retains the stable event ID and must be safe for the consumer to process again.

Managed CDP sessions require cdp:connect and return session_id, run_id, status, expires_at, and a one-time wss:// websocket_url. Connect before expiry, keep the token out of logs, and complete the session through the matching API route with optional CDP metadata.