Persistent profiles
Create a profile and pass its profile_id when creating a session. Use browser_version: 150 for the current Chromium binary.
DEVELOPER REFERENCE / REST API v1
Your browser.
One API away.
Create sessions, manage persistent profiles, and build and run Skills. Explore every public REST endpoint with its request and response contract.
GETTING STARTED
Authenticate. Create. Connect.
Use your existing API key from your 0Browser operator in the Authorization: Bearer header. Regular tokens access their own sessions, profiles, groups and automation resources. Instance controls require an admin token.
curl --request POST https://api.0browser.io/api/v1/sessions \
--header "Authorization: Bearer $ZERO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"browser_version":150,"headless":true}'The response contains id and cdp_url. Connect your browser client, then close the session with DELETE /api/v1/sessions/{id} when finished.
Skill automation
Create an Operation → assign profile input → build a Skill → publish its version → create a Run with version_id. Builds and Runs expose event polling and saved evidence. Use operation.update_input in Build or Skill steps to save profile input changes. Runs start with saved input.
Pagination, errors and human control
Core lists return data, total, limit, offset. Automation lists return arrays, capped at 250 documents or 100 Runs/Builds. Events return up to 100 records: pass the latest sequence as after to fetch the next page.
Errors normally include error. A 409 can indicate a stale draft revision, a state conflict or a profile controlled by automation. Pause its Run or stop its Build before manual browser changes. For a Run in human_required, inspect the evidence and use the intervention endpoint to retry, guide or complete a step.
ENDPOINTS
114 endpointsAll endpoints
Sessions5
Create and connect to isolated browsers.
POST/api/v1/sessionsCreate a browser session
/api/v1/sessionsCreate a browser sessionGET/api/v1/sessionsList sessions
/api/v1/sessionsList sessionsGET/api/v1/sessions/{id}Get a session
/api/v1/sessions/{id}Get a sessionDELETE/api/v1/sessions/{id}Close a session
/api/v1/sessions/{id}Close a sessionPOST/api/v1/sessions/{id}/extendRequest session extension
/api/v1/sessions/{id}/extendRequest session extensionProfiles18
Persistent browser identities, tags and lifecycle actions.
POST/api/v1/profilesCreate a profile
/api/v1/profilesCreate a profileGET/api/v1/profilesList profiles
/api/v1/profilesList profilesGET/api/v1/profiles/{id}Get a profile
/api/v1/profiles/{id}Get a profilePUT/api/v1/profiles/{id}Update a profile
/api/v1/profiles/{id}Update a profileDELETE/api/v1/profiles/{id}Delete a profile
/api/v1/profiles/{id}Delete a profilePOST/api/v1/profiles/batchGetResolve many profiles by id
/api/v1/profiles/batchGetResolve many profiles by idPATCH/api/v1/profiles/{id}/metadataMerge profile metadata labels
/api/v1/profiles/{id}/metadataMerge profile metadata labelsGET/api/v1/profiles/{id}/metadataGet profile metadata labels
/api/v1/profiles/{id}/metadataGet profile metadata labelsPOST/api/v1/profiles/{id}/cloneClone a profile
/api/v1/profiles/{id}/cloneClone a profilePOST/api/v1/profiles/{id}/startStart a profile
/api/v1/profiles/{id}/startStart a profilePOST/api/v1/profiles/{id}/stopStop a profile session
/api/v1/profiles/{id}/stopStop a profile sessionGET/api/v1/profiles/{id}/homeGet profile home and mirror state
/api/v1/profiles/{id}/homeGet profile home and mirror statePOST/api/v1/profiles/{id}/syncSync node profile data to the hub
/api/v1/profiles/{id}/syncSync node profile data to the hubPOST/api/v1/profiles/{id}/rotate-proxyRotate proxy and restart
/api/v1/profiles/{id}/rotate-proxyRotate proxy and restartGET/api/v1/profiles/tagsList all profile tags
/api/v1/profiles/tagsList all profile tagsPUT/api/v1/profiles/{id}/tagsReplace profile tags
/api/v1/profiles/{id}/tagsReplace profile tagsPOST/api/v1/profiles/bulk-tagsAdd or remove tags in bulk
/api/v1/profiles/bulk-tagsAdd or remove tags in bulkPOST/api/v1/profiles/bulk-deleteDelete profiles in bulk
/api/v1/profiles/bulk-deleteDelete profiles in bulkGroups5
Classify profiles into account-owned groups.
GET/api/v1/profiles/groupsList profile groups
/api/v1/profiles/groupsList profile groupsPOST/api/v1/profiles/groupsCreate group
/api/v1/profiles/groupsCreate groupPUT/api/v1/profiles/groups/{groupID}Rename group
/api/v1/profiles/groups/{groupID}Rename groupDELETE/api/v1/profiles/groups/{groupID}Delete group
/api/v1/profiles/groups/{groupID}Delete groupPOST/api/v1/profiles/bulk-groupMove profiles to a group
/api/v1/profiles/bulk-groupMove profiles to a groupStorage9
Cookies, local storage and session storage exports and imports.
POST/api/v1/sessions/{id}/cookies/exportExport session cookies and storage
/api/v1/sessions/{id}/cookies/exportExport session cookies and storagePOST/api/v1/sessions/{id}/cookies/importImport session cookies and storage
/api/v1/sessions/{id}/cookies/importImport session cookies and storageDELETE/api/v1/sessions/{id}/cookiesClear session cookies
/api/v1/sessions/{id}/cookiesClear session cookiesPOST/api/v1/sessions/{id}/cookies/save-to-profileSave session storage to its profile
/api/v1/sessions/{id}/cookies/save-to-profileSave session storage to its profilePOST/api/v1/sessions/{id}/cookies/load-from-profileLoad profile storage into its session
/api/v1/sessions/{id}/cookies/load-from-profileLoad profile storage into its sessionGET/api/v1/profiles/{id}/cookiesGet saved profile storage
/api/v1/profiles/{id}/cookiesGet saved profile storagePOST/api/v1/profiles/{id}/cookiesSave profile cookies and storage
/api/v1/profiles/{id}/cookiesSave profile cookies and storageDELETE/api/v1/profiles/{id}/cookiesClear saved profile cookies
/api/v1/profiles/{id}/cookiesClear saved profile cookiesPOST/api/v1/profiles/{id}/cookies/loadLoad cookies into a selected session
/api/v1/profiles/{id}/cookies/loadLoad cookies into a selected sessionExtensions6
Upload extensions and open their sidepanel or popup views.
POST/api/v1/extensionsUpload an extension
/api/v1/extensionsUpload an extensionGET/api/v1/extensionsList extensions
/api/v1/extensionsList extensionsGET/api/v1/extensions/{id}Get an extension
/api/v1/extensions/{id}Get an extensionDELETE/api/v1/extensions/{id}Delete an extension
/api/v1/extensions/{id}Delete an extensionGET/api/v1/sessions/{id}/extensionsList session extension views
/api/v1/sessions/{id}/extensionsList session extension viewsPOST/api/v1/sessions/{id}/extensions/{extensionID}/openOpen an extension view
/api/v1/sessions/{id}/extensions/{extensionID}/openOpen an extension viewFingerprints3
Reusable browser fingerprint configurations.
GET/api/v1/fingerprintsList fingerprints
/api/v1/fingerprintsList fingerprintsPOST/api/v1/fingerprintsCreate a fingerprint
/api/v1/fingerprintsCreate a fingerprintGET/api/v1/fingerprints/{id}Get a fingerprint
/api/v1/fingerprints/{id}Get a fingerprintLive View3
Inspect and stop live viewers. Streaming uses WebSockets.
GET/api/v1/sessions/{id}/liveGet live viewer information
/api/v1/sessions/{id}/liveGet live viewer informationDELETE/api/v1/sessions/{id}/liveStop a live viewer
/api/v1/sessions/{id}/liveStop a live viewerGET/api/v1/live-viewersList active live viewers
/api/v1/live-viewersList active live viewersOperations17
Input schemas and profile assignments. Skills, Builds and Runs belong to an Operation.
GET/api/v1/automation/operationsList operations
/api/v1/automation/operationsList operationsPOST/api/v1/automation/operationsCreate Operation
/api/v1/automation/operationsCreate OperationGET/api/v1/automation/operations/{operationId}Get document and versions
/api/v1/automation/operations/{operationId}Get document and versionsPUT/api/v1/automation/operations/{operationId}Update document draft
/api/v1/automation/operations/{operationId}Update document draftDELETE/api/v1/automation/operations/{operationId}Archive document
/api/v1/automation/operations/{operationId}Archive documentGET/api/v1/automation/operations/{operationId}/versionsList published versions
/api/v1/automation/operations/{operationId}/versionsList published versionsGET/api/v1/automation/operations/{operationId}/assignmentsList assigned profiles and input
/api/v1/automation/operations/{operationId}/assignmentsList assigned profiles and inputPUT/api/v1/automation/operations/{operationId}/assignmentsAssign a profile and input
/api/v1/automation/operations/{operationId}/assignmentsAssign a profile and inputDELETE/api/v1/automation/operations/{operationId}/assignmentsRemove a profile assignment
/api/v1/automation/operations/{operationId}/assignmentsRemove a profile assignmentGET/api/v1/automation/operations/{operationId}/startupGet automatic startup settings and recent attempts
/api/v1/automation/operations/{operationId}/startupGet automatic startup settings and recent attemptsPUT/api/v1/automation/operations/{operationId}/startupConfigure a Skill to run on first profile start
/api/v1/automation/operations/{operationId}/startupConfigure a Skill to run on first profile startPOST/api/v1/automation/operations/{operationId}/parse-inputParse freestyle input with AI
/api/v1/automation/operations/{operationId}/parse-inputParse freestyle input with AIGET/api/v1/automation/profile-operations/{profileId}List Operations assigned to a profile
/api/v1/automation/profile-operations/{profileId}List Operations assigned to a profileGET/api/v1/automation/leases/{profileId}Get current profile control lease
/api/v1/automation/leases/{profileId}Get current profile control leaseSkills9
Editable drafts with immutable published versions and stable input/output contracts.
GET/api/v1/automation/operations/{operationId}/skillsList skills
/api/v1/automation/operations/{operationId}/skillsList skillsPOST/api/v1/automation/operations/{operationId}/skillsCreate Skill
/api/v1/automation/operations/{operationId}/skillsCreate SkillGET/api/v1/automation/operations/{operationId}/skills/{skillId}Get document and versions
/api/v1/automation/operations/{operationId}/skills/{skillId}Get document and versionsPUT/api/v1/automation/operations/{operationId}/skills/{skillId}Update document draft
/api/v1/automation/operations/{operationId}/skills/{skillId}Update document draftDELETE/api/v1/automation/operations/{operationId}/skills/{skillId}Archive document
/api/v1/automation/operations/{operationId}/skills/{skillId}Archive documentGET/api/v1/automation/operations/{operationId}/skills/{skillId}/versionsList published versions
/api/v1/automation/operations/{operationId}/skills/{skillId}/versionsList published versionsGET/api/v1/automation/operations/{operationId}/skills/{skillId}/self-improvementGet automatic self-improvement policy
/api/v1/automation/operations/{operationId}/skills/{skillId}/self-improvementGet automatic self-improvement policyPUT/api/v1/automation/operations/{operationId}/skills/{skillId}/self-improvementConfigure automatic publication of Run improvements
/api/v1/automation/operations/{operationId}/skills/{skillId}/self-improvementConfigure automatic publication of Run improvementsPOST/api/v1/automation/operations/{operationId}/skills/{skillId}/publishPublish a Skill version
/api/v1/automation/operations/{operationId}/skills/{skillId}/publishPublish a Skill versionBuilds7
Agent-assisted Skill authoring against an active profile browser.
GET/api/v1/automation/operations/{operationId}/buildsList builds
/api/v1/automation/operations/{operationId}/buildsList buildsPOST/api/v1/automation/operations/{operationId}/buildsStart a Skill Build chat
/api/v1/automation/operations/{operationId}/buildsStart a Skill Build chatGET/api/v1/automation/operations/{operationId}/builds/{buildId}Get execution state
/api/v1/automation/operations/{operationId}/builds/{buildId}Get execution stateGET/api/v1/automation/operations/{operationId}/builds/{buildId}/eventsRead execution events and evidence
/api/v1/automation/operations/{operationId}/builds/{buildId}/eventsRead execution events and evidencePOST/api/v1/automation/operations/{operationId}/builds/{buildId}/promptSend a message to the Build agent
/api/v1/automation/operations/{operationId}/builds/{buildId}/promptSend a message to the Build agentPOST/api/v1/automation/operations/{operationId}/builds/{buildId}/stopStop the Build agent
/api/v1/automation/operations/{operationId}/builds/{buildId}/stopStop the Build agentPOST/api/v1/automation/operations/{operationId}/builds/{buildId}/accept-draftSave the Build draft to a Skill
/api/v1/automation/operations/{operationId}/builds/{buildId}/accept-draftSave the Build draft to a SkillRuns7
Execute a published Skill version; inspect evidence and handle human-required steps.
GET/api/v1/automation/session-runs/{sessionId}Get compact Run progress for a session
/api/v1/automation/session-runs/{sessionId}Get compact Run progress for a sessionGET/api/v1/automation/operations/{operationId}/runsList runs
/api/v1/automation/operations/{operationId}/runsList runsPOST/api/v1/automation/operations/{operationId}/runsRun a published Skill
/api/v1/automation/operations/{operationId}/runsRun a published SkillGET/api/v1/automation/operations/{operationId}/runs/{runId}Get execution state
/api/v1/automation/operations/{operationId}/runs/{runId}Get execution stateGET/api/v1/automation/operations/{operationId}/runs/{runId}/eventsRead execution events and evidence
/api/v1/automation/operations/{operationId}/runs/{runId}/eventsRead execution events and evidencePOST/api/v1/automation/operations/{operationId}/runs/{runId}/interveneIntervene in a Run
/api/v1/automation/operations/{operationId}/runs/{runId}/interveneIntervene in a RunPOST/api/v1/automation/operations/{operationId}/runs/{runId}/apply-proposalApply a reviewed improvement to a Skill draft
/api/v1/automation/operations/{operationId}/runs/{runId}/apply-proposalApply a reviewed improvement to a Skill draftAI Account7
Account-specific AI configuration, encrypted secrets and available tools.
GET/api/v1/automation/settingsGet AI account configuration
/api/v1/automation/settingsGet AI account configurationPUT/api/v1/automation/settingsSave AI account configuration
/api/v1/automation/settingsSave AI account configurationDELETE/api/v1/automation/settingsRemove AI account configuration
/api/v1/automation/settingsRemove AI account configurationGET/api/v1/automation/secretsList secret metadata
/api/v1/automation/secretsList secret metadataPOST/api/v1/automation/secretsCreate an encrypted secret
/api/v1/automation/secretsCreate an encrypted secretDELETE/api/v1/automation/secrets/{secretId}Delete an encrypted secret
/api/v1/automation/secrets/{secretId}Delete an encrypted secretGET/api/v1/automation/toolsList available automation tools
/api/v1/automation/toolsList available automation toolsInstances3
Administrator-only infrastructure actions.
GET/api/v1/instancesList instancesADMIN
/api/v1/instancesList instancesPOST/api/v1/instances/scaleSpawn additional instancesADMIN
/api/v1/instances/scaleSpawn additional instancesDELETE/api/v1/instances/{id}Stop an instanceADMIN
/api/v1/instances/{id}Stop an instanceSystem2
Public health and metrics endpoints.
GET/healthCheck API health
/healthCheck API healthGET/metricsGet metrics placeholder
/metricsGet metrics placeholderCDP & live view
Connect to the returned cdp_url using Puppeteer or Playwright. WebSockets accept the Authorization header; browser clients that cannot set headers can use a URL-encoded token query parameter. This query authentication applies only to WebSocket routes.
import { chromium } from "playwright";
// session is the response from POST /api/v1/sessions.
const browser = await chromium.connectOverCDP(session.cdp_url, {
headers: { Authorization: `Bearer ${process.env.ZERO_API_KEY}` },
});
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();
await page.goto("https://example.com");wss://api.0browser.io/cdp/{sessionId}/browserBrowser-level CDP for Puppeteer and Playwright. Use the returned cdp_url.
wss://api.0browser.io/cdp/{sessionId}Legacy page-level CDP connection.
wss://api.0browser.io/live/{sessionId}Live viewer stream. Optional targetId selects an extension target.
wss://api.0browser.io/wsSession event stream.
wss://api.0browser.io/api/v1/sessions/{id}/agent/streamAgent lifecycle stream. Authenticate with token=sk_...; send {operation,input}. One request/socket; events started/completed/error. Disconnect or {action:cancel} cancels execution.
For extensions, list a session’s extension entries, call its open endpoint, then use the returned targetId on the live connection. The REST spec documents HTTP endpoints; WebSocket message protocols are separate.
Schemas
Request and response models, including Skill steps, cases and executable success conditions. The downloadable specification includes every schema and reference.