Ant0 Download

Local API

The REST and WebSocket API of the Ant0 background service, version 0.1.0. Everything the desktop app does is one of these calls on your own computer.

Updated Sep 7, 2026

Overview

Local API of the Ant0 daemon. Bearer token from ~/.ant0/ant0d.token; GET /v1/health, /openapi.json and /docs are open. Profile :id parameters accept the UUID or the exact profile name.

Base URL
http://127.0.0.1:27100 (the port is ANT0D_PORT or the value in ant0d.pid; loopback only, never exposed to the network)
Format
JSON request and response bodies; Content-Type: application/json. Timestamps are RFC 3339 in UTC.
Ids
UUIDs. Profile and proxy {id} parameters also accept the exact name.
Document
GET /openapi.json on the running service returns this specification (OpenAPI 3.1).

Authentication

Every route except GET /v1/health and GET /openapi.json requires Authorization: Bearer <token>. The token is generated when the service is first started and stored in ant0d.token in the data folder (%LOCALAPPDATA%\Ant0 on Windows, ~/.local/share/ant0 on Linux); the desktop app's Automation screen shows it with a copy button. The WebSocket event stream takes the same token as ?token= or in the header. 

curl -s http://127.0.0.1:27100/v1/profiles \
  -H "Authorization: Bearer $(cat ~/.local/share/ant0/ant0d.token)"

Errors

Failures answer with a JSON ApiError: a stable code (profile.not_found, proxy.in_use, licence.profile_limit, …), a human message and, where useful, details. Status codes follow HTTP: 400 invalid input, 401 missing or wrong token, 404 unknown id or name, 409 conflict (a name in use, a running profile), 423 locked by the plan, 503 the service is not ready.

Operations

51 operations in 10 groups.

health

Liveness and the API document itself. These routes need no token.

GET /openapi.json

This OpenAPI 3.1 document

No token required

Open (no bearer token). @ant0/api-client is generated from it.

Responses
200

OpenAPI document

application/json

Field Type Description

GET /v1/health

Daemon liveness

No token required

Open (no bearer token). Clients use it to find a running daemon.

Responses
200

application/json

Field Type Description
ok required true
version required string
pid required integer
uptime_s required number
home required string

POST /v1/daemon/shutdown

Stop every running profile gracefully and exit the daemon

Answers 202 at once, then runs the same shutdown the SIGTERM handler uses: every running browser is closed (CDP Browser.close, then the OS-specific fallback), the API and database are closed, ant0d.pid is removed and the process exits with code 0 (within 10 s at most: a guard then exits anyway and reports the step that hung on stderr). The desktop app calls this on exit and before a restart.

Responses
202

application/json

Field Type Description
stopping required integermin 0 Number of running profiles being stopped gracefully before the daemon exits.
401

ApiError

browsers

Installed Ant0 Browser releases: list, install with progress, set the default, remove.

GET /v1/browsers

Installed releases, newest first

Responses
200

application/json

Field Type Description
items required array<InstalledBrowser>
401

ApiError

PUT /v1/browsers/default

Set the default release

The release profiles without a pinned browser.version launch. Must be installed (404 browser.not_found). Answers the updated list.

Request body required · application/json
Field Type Description
version required stringpattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ An installed release version.
Responses
200

application/json

Field Type Description
items required array<InstalledBrowser>
400

ApiError

401

ApiError

404

ApiError

GET /v1/browsers/available

Version a release channel currently serves

Contacts the release store (the only outbound host besides proxies).

Parameters
Name In Type Description
channel query string default "stable"
Responses
200

application/json

Field Type Description
channel required string
version required string
chromium required string
installed required boolean
size_bytes required integer | null Download size of this platform's archive, from the release manifest; null when the manifest could not be read.

one of

  1. integer min 0

  2. null

400

ApiError

401

ApiError

502

ApiError

POST /v1/browsers/install

Start a background install

Answers 202 immediately. Progress streams as browser.install events; poll GET /v1/browsers/jobs/{id} for the outcome. Installing an already installed version completes at once.

Request body required · application/json
Field Type Description
channel stringdefault "stable" · pattern ^[a-z0-9][a-z0-9-]{0,63}$
version stringpattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ Pin a release; omitted = the channel's current version.
Responses
202

application/json

Field Type Description
job_id required string (uuid)
400

ApiError

401

ApiError

GET /v1/browsers/jobs/{id}

Status of an install job

Parameters
Name In Type Description
id required path string
Responses
200

application/json

InstallJob

400

ApiError

401

ApiError

404

ApiError

DELETE /v1/browsers/{version}

Remove an installed release

409 browser.in_use while a running profile uses it; 409 browser.is_default when it is the default and nothing else is installed (otherwise the newest remaining release becomes the default).

Parameters
Name In Type Description
version required path string
Responses
204
400

ApiError

401

ApiError

404

ApiError

409

ApiError

profiles

The profile list, single and bulk operations, start and stop, the identity a profile presents.

GET /v1/profiles

List profiles

Pinned first, then by name. total counts every match regardless of paging. Live profiles only; ?trashed=true lists the trash instead (see also GET /v1/trash).

Parameters
Name In Type Description
q query string Case-insensitive substring of the name.
group query string
tag query string
limit query integer default 100
offset query integer default 0
trashed query boolean default false true: only profiles in the trash; false (default): only live profiles.
Responses
200

application/json

Field Type Description
items required array<ProfileSummary>
total required integermin 0
400

ApiError

401

ApiError

POST /v1/profiles

Create a profile

Only name is required. network.proxy may carry an inline proxy (object, { url } or { line }) that becomes a shared proxy referenced by proxy_id. With a licence a synthetic profile is claimed at the cloud first, which issues its persona: 403 licence.profile_limit / licence.required / workspace.*, 409 profile.claimed, 503 licence.offline when the cloud is unreachable.

Request body required · application/json

ProfileCreate

Responses
201

Canonical stored profile document (schema "ant0-profile/v1"). Runtime state (running, pid, cdp url) is not part of the manifest.

application/json

ProfileManifest

400

ApiError

401

ApiError

403

ApiError

404

ApiError

409

ApiError

503

ApiError

POST /v1/profiles/bulk

Create many profiles

{ csv } (header row + one profile per row; row numbers count the header as 1) or { items } (row numbers start at 1). Rows are independent; failures are reported per row and the rest are created.

Request body required · application/json

one of

  1. Field Type Description
    csv required string Header row + one profile per row (see CLI docs).
  2. Field Type Description
    items required array<ProfileCreate>min items 1
Responses
201

application/json

Field Type Description
created required array<string (uuid)>
errors required array<object>
Field Type Description
row required integer
message required string
400

ApiError

401

ApiError

POST /v1/profiles/bulk-update

Update many profiles

Ids (UUID or exact name, at most 50) are processed one after another; a failing id is reported with its error code and the rest proceed. 400 when there are more than 50. patch.group replaces (null clears the folder), tags_add then tags_remove edit the tags, pinned replaces. Trashed profiles are updated too.

Request body required · application/json
Field Type Description
ids required array<string>min items 1 · max items 50 Profile ids (UUID or exact name), at most 50.
patch required object group replaces (null clears); tags_add then tags_remove edit the tag list; pinned replaces.
Field Type Description
group string | null

one of

  1. string min length 1 · max length 120

  2. null

tags_add array<string>
tags_remove array<string>
pinned boolean
Responses
200

application/json

Field Type Description
updated required integermin 0 Ids the operation succeeded for.
errors required array<object>
Field Type Description
id required string The id as sent.
error required string API error code, e.g. profile.not_found.
message required string
400

ApiError

401

ApiError

POST /v1/profiles/bulk-start

Start many profiles

Ids (UUID or exact name, at most 50) are processed one after another; a failing id is reported with its error code and the rest proceed. 400 when there are more than 50. Each start waits for its DevTools endpoint like POST /v1/profiles/{id}/start; updated counts the browsers now running.

Request body required · application/json
Field Type Description
ids required array<string>min items 1 · max items 50 Profile ids (UUID or exact name), at most 50.
Responses
200

application/json

Field Type Description
updated required integermin 0 Ids the operation succeeded for.
errors required array<object>
Field Type Description
id required string The id as sent.
error required string API error code, e.g. profile.not_found.
message required string
400

ApiError

401

ApiError

POST /v1/profiles/bulk-stop

Stop many profiles

Ids (UUID or exact name, at most 50) are processed one after another; a failing id is reported with its error code and the rest proceed. 400 when there are more than 50. Graceful stop; updated counts the browsers stopped.

Request body required · application/json
Field Type Description
ids required array<string>min items 1 · max items 50 Profile ids (UUID or exact name), at most 50.
Responses
200

application/json

Field Type Description
updated required integermin 0 Ids the operation succeeded for.
errors required array<object>
Field Type Description
id required string The id as sent.
error required string API error code, e.g. profile.not_found.
message required string
400

ApiError

401

ApiError

GET /v1/profiles/{id}

Profile manifest plus runtime

id is the profile UUID or its exact name. runtime is the live session or null; deleted_at is set while in the trash; platform as in the list summaries.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Responses
200

profile-manifest-v1 plus runtime (the live session, or null when stopped), deleted_at (RFC 3339 while in the trash, else null) and platform (the OS persona the browser presents, as in ProfileSummary).

application/json

ProfileDetail

400

ApiError

401

ApiError

404

ApiError

409

ApiError

PATCH /v1/profiles/{id}

Update a profile

id is the profile UUID or its exact name. Objects merge, arrays and scalars replace.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Request body required · application/json

ProfileInput

Responses
200

Canonical stored profile document (schema "ant0-profile/v1"). Runtime state (running, pid, cdp url) is not part of the manifest.

application/json

ProfileManifest

400

ApiError

401

ApiError

404

ApiError

409

ApiError

DELETE /v1/profiles/{id}

Move a profile to the trash (or delete it for good)

id is the profile UUID or its exact name. Moves the profile to the trash, where it stays restorable for trash_retention_days (7) before the sweeper purges it. ?permanent=true deletes the row, launch history and user data immediately (and releases the cloud claim, PHASE3 §9; the trash keeps it). 409 profile.running while it runs.

Parameters
Name In Type Description
permanent query boolean default false Skip the trash: delete the row, launch history and user data for good. Default: move to the trash (7-day retention).
purge query boolean default false Deprecated alias of permanent (contract v1.2 and earlier).
id required path string Profile id (UUID) or exact profile name.
Responses
204
400

ApiError

401

ApiError

404

ApiError

409

ApiError

POST /v1/profiles/{id}/restore

Restore a profile from the trash

id is the profile UUID or its exact name. 404 profile.not_trashed when the profile is not in the trash.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Responses
200

Canonical stored profile document (schema "ant0-profile/v1"). Runtime state (running, pid, cdp url) is not part of the manifest.

application/json

ProfileManifest

400

ApiError

401

ApiError

404

ApiError

409

ApiError

POST /v1/profiles/{id}/duplicate

Duplicate a profile

id is the profile UUID or its exact name. Copies the manifest under a new id (new synthetic persona, claimed like a create); user data is not copied.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Request body required · application/json
Field Type Description
name stringmin length 1 · max length 120
Responses
201

Canonical stored profile document (schema "ant0-profile/v1"). Runtime state (running, pid, cdp url) is not part of the manifest.

application/json

ProfileManifest

400

ApiError

401

ApiError

403

ApiError

404

ApiError

409

ApiError

503

ApiError

GET /v1/profiles/{id}/identity

Persona the profile presents

id is the profile UUID or its exact name. Generates and persists a synthetic persona when missing.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Responses
200

application/json

Field Type Description
mode required "synthetic" | "captured" | "native"

one of

  1. "synthetic"

  2. "captured"

  3. "native"

persona required null | object persona-profile-v2 (SDK); null for native mode.
source required object | null

one of

  1. Field Type Description
    kind required string
    version required string

  2. null

persisted required boolean
warnings required array<object>
Field Type Description
code required string
message required string
400

ApiError

401

ApiError

404

ApiError

409

ApiError

500

ApiError

POST /v1/profiles/{id}/start

Start the browser

id is the profile UUID or its exact name. Resolves when the DevTools endpoint is up. 409 profile.already_running.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Request body required · application/json
Field Type Description
headless boolean
start_urls array<string (uri)>
extra_args array<string>
timeout_s numbermin 1 · max 600
Responses
200

A running browser session: the response of POST /v1/profiles/:id/start and the element of GET /v1/sessions.

application/json

Session

400

ApiError

401

ApiError

404

ApiError

409

ApiError

500

ApiError

POST /v1/profiles/{id}/stop

Stop the browser

id is the profile UUID or its exact name. Graceful (Browser.close, SIGTERM, SIGKILL) unless force. 409 profile.not_running.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Request body required · application/json
Field Type Description
force boolean SIGKILL immediately.
Responses
204
400

ApiError

401

ApiError

404

ApiError

409

ApiError

GET /v1/profiles/{id}/status

Run state

id is the profile UUID or its exact name. session is null unless running.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Responses
200

application/json

Field Type Description
state required "starting" | "running" | "stopping" | "stopped" | "crashed"

one of

  1. "starting"

  2. "running"

  3. "stopping"

  4. "stopped"

  5. "crashed"

session required Session | null

one of

  1. Session

  2. null

400

ApiError

401

ApiError

404

ApiError

409

ApiError

cookies

Import, export and clear a running profile's cookies through the browser.

GET /v1/profiles/{id}/cookies

Export cookies

id is the profile UUID or its exact name. Reads the running browser over CDP; 409 profile.not_running otherwise (v1 does not launch a hidden browser for exports). json is the Cookie-Editor shape, netscape is cookies.txt.

Parameters
Name In Type Description
format query string default "json"
id required path string Profile id (UUID) or exact profile name.
Responses
200

Serialized cookies in the requested format.

application/json, text/plain

array of object

400

ApiError

401

ApiError

404

ApiError

409

ApiError

502

ApiError

POST /v1/profiles/{id}/cookies

Import cookies

id is the profile UUID or its exact name. Running profile: set over CDP immediately (applied: "now"). Stopped profile: queued on disk and applied on the next start (applied: "next_start"). Accepts Cookie-Editor/EditThisCookie JSON, Puppeteer/Playwright arrays and Netscape cookies.txt; format: auto sniffs.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Request body required · application/json
Field Type Description
format required "auto" | "json" | "netscape"default "auto"

one of

  1. "auto"

  2. "json"

  3. "netscape"

data required stringmin length 1 Cookie-Editor/EditThisCookie/Puppeteer JSON or Netscape cookies.txt text.
Responses
200

application/json

Field Type Description
imported required integermin 0
applied required "now" | "next_start" now: set over CDP in the running browser; next_start: queued on disk.

one of

  1. "now"

  2. "next_start"

400

ApiError

401

ApiError

404

ApiError

409

ApiError

502

ApiError

DELETE /v1/profiles/{id}/cookies

Clear cookies

id is the profile UUID or its exact name. Running profile: clears every cookie in the browser. Stopped profile: discards a queued import; 409 profile.not_running when nothing was queued.

Parameters
Name In Type Description
id required path string Profile id (UUID) or exact profile name.
Responses
204
400

ApiError

401

ApiError

404

ApiError

409

ApiError

502

ApiError

sessions

Running browser sessions with their CDP endpoints.

GET /v1/sessions

Running sessions

Profiles whose DevTools endpoint is up, with their CDP endpoints.

Responses
200

application/json

Field Type Description
items required array<Session>
401

ApiError

trash

Profiles waiting to be purged (7 days), and emptying the trash.

GET /v1/trash

List trashed profiles

Same ordering, filters and paging as GET /v1/profiles; every item carries deleted_at and purge_at (= deleted_at + trash_retention_days).

Parameters
Name In Type Description
q query string Case-insensitive substring of the name.
group query string
tag query string
limit query integer default 100
offset query integer default 0
Responses
200

application/json

Field Type Description
items required array<TrashedProfileSummary>
total required integermin 0
trash_retention_days required integermin 1 Days a trashed profile survives before the hourly sweeper purges it.
400

ApiError

401

ApiError

DELETE /v1/trash

Empty the trash

Purges every trashed profile (row, launch history, user data). Answers how many went.

Responses
200

application/json

Field Type Description
purged required integermin 0
401

ApiError

proxies

Shared proxy objects: create from URLs or provider lines, check, change IP.

GET /v1/proxies

List proxies

Parameters
Name In Type Description
q query string
tag query string
Responses
200

application/json

Field Type Description
items required array<Proxy>
400

ApiError

401

ApiError

POST /v1/proxies

Create one proxy, or many from provider lines

Body is the object form, { url }, { line }, or { lines } (bulk). Single forms answer the created proxy; { lines } answers { created, errors } with 1-based line numbers for rows that failed.

Request body required · application/json

one of

  1. ProxyCreate

  2. scheme://user:pass@host:port

    Field Type Description
    url required stringmin length 1 · max length 2048

  3. Provider export line: host:port:user:pass, scheme://host:port:user:pass, ...

    Field Type Description
    line required stringmin length 1 · max length 2048

  4. Bulk: one provider line per row; blank and # lines are skipped.

    Field Type Description
    lines required stringmin length 1
Responses
201

application/json

one of

  1. Proxy

  2. Field Type Description
    created required array<Proxy>
    errors required array<object>
    Field Type Description
    line required integer
    message required string
400

ApiError

401

ApiError

GET /v1/proxies/{id}

Get a proxy

Parameters
Name In Type Description
id required path string
Responses
200

Stored proxy document (schema "ant0-proxy/v1"). Passwords are never stored inline; password_ref points at the secrets table.

application/json

Proxy

400

ApiError

401

ApiError

404

ApiError

PATCH /v1/proxies/{id}

Update a proxy

password: string replaces the stored secret, null or "" removes it, absent keeps it. Server fields (id, password_ref, last_check, timestamps) are not patchable.

Parameters
Name In Type Description
id required path string
Request body required · application/json
Field Type Description
name stringmin length 1 · max length 120
type "http" | "https" | "socks5"

one of

  1. "http"

  2. "https"

  3. "socks5"

host stringmin length 1 · max length 253
port integermin 1 · max 65535
username stringmax length 512
password string | null

one of

  1. string max length 4096

  2. null

change_ip_url stringmax length 2048
session_pattern stringmax length 512
provider stringmax length 80
udp boolean
tags array<string>
notes stringmax length 4000
Responses
200

Stored proxy document (schema "ant0-proxy/v1"). Passwords are never stored inline; password_ref points at the secrets table.

application/json

Proxy

400

ApiError

401

ApiError

404

ApiError

DELETE /v1/proxies/{id}

Delete a proxy

409 proxy.in_use (details.profiles lists the ids) while profiles reference it.

Parameters
Name In Type Description
id required path string
Responses
204
400

ApiError

401

ApiError

404

ApiError

409

ApiError

POST /v1/proxies/{id}/check

Probe the proxy

http/https: exit-IP echo through the proxy plus geo lookup; socks5: timed TCP connect. Never fails for a bad proxy (ok: false + error). Stored as last_check.

Parameters
Name In Type Description
id required path string
Responses
200

Stored proxy document (schema "ant0-proxy/v1"). Passwords are never stored inline; password_ref points at the secrets table.

application/json

ProxyCheck

400

ApiError

401

ApiError

404

ApiError

POST /v1/proxies/{id}/change-ip

Request a new exit IP

GETs the provider's change_ip_url and reports the HTTP status. 400 when the proxy has no change_ip_url; 502 proxy.change_ip_failed when the request fails.

Parameters
Name In Type Description
id required path string
Responses
200

application/json

Field Type Description
status required integer HTTP status the provider answered.
400

ApiError

401

ApiError

404

ApiError

502

ApiError

extensions

The extension library shared by profiles.

GET /v1/extensions

List the extension library

Every unpacked extension under <home>/extensions/<id>/ with its manifest data, icon (inline data URL when ≤ 64 KB) and the profiles using it.

Responses
200

application/json

Field Type Description
items required array<Extension>
401

ApiError

POST /v1/extensions

Add an extension to the library

path is an absolute local path to an unpacked extension folder (with manifest.json), a .zip, or a .crx. The extension is copied/extracted into the library. Answers 201 with existing: false, or 200 with existing: true when the same id is already present. 400 extension.invalid for a bad path, archive or manifest.

Request body required · application/json
Field Type Description
path required stringmin length 1 · max length 4096 Absolute local path: an unpacked extension folder (with manifest.json), a .zip, or a .crx (v2/v3).
Responses
200

application/json

Field Type Description
id required string Library id: the Web Store id when the manifest has a key, else <slug>-<8 hex>.
name required string
version required string
description required string May be empty.
manifest_version required 2 | 3

one of

  1. 2

  2. 3

icon_path required string | null Absolute path of the largest manifest icon, or null.

one of

  1. string

  2. null

icon_data_url required string | null The icon as a base64 data: URL when it is at most 64 KB; else null.

one of

  1. string

  2. null

path required string Absolute library folder; this is what launch.extensions holds.
size_bytes required integermin 0
added_at required string (date-time)
used_by required array<string (uuid)> Profiles (live and trashed) whose launch.extensions include path.
existing required boolean True when the library already had this id (nothing was copied).
201

application/json

Field Type Description
id required string Library id: the Web Store id when the manifest has a key, else <slug>-<8 hex>.
name required string
version required string
description required string May be empty.
manifest_version required 2 | 3

one of

  1. 2

  2. 3

icon_path required string | null Absolute path of the largest manifest icon, or null.

one of

  1. string

  2. null

icon_data_url required string | null The icon as a base64 data: URL when it is at most 64 KB; else null.

one of

  1. string

  2. null

path required string Absolute library folder; this is what launch.extensions holds.
size_bytes required integermin 0
added_at required string (date-time)
used_by required array<string (uuid)> Profiles (live and trashed) whose launch.extensions include path.
existing required boolean True when the library already had this id (nothing was copied).
400

ApiError

401

ApiError

GET /v1/extensions/{id}

Get an extension

Parameters
Name In Type Description
id required path string
Responses
200

application/json

Extension

400

ApiError

401

ApiError

404

ApiError

DELETE /v1/extensions/{id}

Remove an extension from the library

409 extension.in_use (details.profile_ids) while profiles reference it; ?force=true first removes the path from those profiles' launch.extensions and reports them in updated_profiles.

Parameters
Name In Type Description
force query boolean default false Also remove the path from every profile's launch.extensions instead of answering 409 extension.in_use.
id required path string
Responses
200

application/json

Field Type Description
id required string
updated_profiles required array<string (uuid)> Profiles whose launch.extensions were rewritten (only with force).
400

ApiError

401

ApiError

404

ApiError

409

ApiError

GET /v1/extensions/{id}/icon

The extension's largest icon

Binary image with its content type (png/jpeg/gif/webp/svg/ico). 404 extension.not_found when the extension has no icon file.

Parameters
Name In Type Description
id required path string
Responses
200

Icon bytes

image/png, image/jpeg, image/gif, image/webp, image/svg+xml

400

image/png, image/jpeg, image/gif, image/webp, image/svg+xml

401

image/png, image/jpeg, image/gif, image/webp, image/svg+xml

404

image/png, image/jpeg, image/gif, image/webp, image/svg+xml

licence

Account state on this computer (from 0.2.0): sign-in, refresh, the keep list, launch tickets.

GET /v1/licence

Licence state

state: signed_out, active, grace (offline past expires_at, before grace_until: existing profiles start, nothing is created), locked (past grace, no token, or the workspace lapsed), suspended. used counts live and trashed profiles. keep lists the profiles that stay startable while used exceeds limits.profiles. mode: off means nothing is enforced (development).

Responses
200

What the daemon knows about its licence: the response of GET /v1/licence and of every licence mutation. Never carries tokens.

application/json

LicenceState

401

ApiError

POST /v1/licence/refresh

Ask the cloud for a fresh licence now

Runs the hourly POST /licence immediately and answers the resulting state (200 even when the cloud is unreachable: online: false, last_error, and the stored token keeps applying until grace_until).

Responses
200

What the daemon knows about its licence: the response of GET /v1/licence and of every licence mutation. Never carries tokens.

application/json

LicenceState

401

ApiError

POST /v1/licence/sign-in

Sign in to the Ant0 cloud (CLI users)

Forwards the credentials to api.ant0.link, registers this device and fetches the first licence. Cloud errors keep their code and status: 401 auth.invalid_credentials, 401 auth.totp_required (retry with totp), 401 auth.totp_invalid, 403 device.limit, 409 device.free_used, 429 auth.rate_limited; 503 licence.offline when the cloud does not answer. The desktop app signs in itself and uses POST /v1/licence/session.

Request body required · application/json

Credentials are forwarded to the cloud once and never stored; the daemon keeps the resulting refresh token.

Field Type Description
email required string (email)min length 3 · max length 320
password required stringmin length 1 · max length 1024
totp stringpattern ^[0-9]{6}$|^[A-Za-z0-9-]{8,16}$ 6-digit TOTP code or a recovery code, when 2FA is enabled.
Responses
200

What the daemon knows about its licence: the response of GET /v1/licence and of every licence mutation. Never carries tokens.

application/json

LicenceState

400

ApiError

401

ApiError

403

ApiError

409

ApiError

429

ApiError

500

ApiError

503

ApiError

POST /v1/licence/sign-out

Sign out

Revokes the cloud session (best effort) and forgets the session and licence token; the state becomes signed_out. The keep list is kept locally.

Responses
204
401

ApiError

POST /v1/licence/session

Adopt a cloud session (desktop shell)

The desktop app performs the sign-in itself and hands the daemon the refresh token bound to this device; the daemon exchanges it for an access token and fetches the licence. 401 when the cloud rejects the token. With device_keys the daemon first adopts the shell's keypairs as its own, so both processes hold the one device key the licence names; keys the daemon generated itself are replaced (logged once).

Request body required · application/json
Field Type Description
refresh required stringmin length 16 · max length 4096 A refresh token the desktop shell obtained for this device.
device_keys object The shell's device keypairs. The daemon adopts them as its own — <home>/device/keys.json, 0600 — replacing keys it generated itself, so the licence names one key and no re-registration ping-pong follows. Loopback only, bearer-authenticated; never logged, never echoed. Omitted by CLI-only clients.
Field Type Description
sign_priv required stringpattern ^[A-Za-z0-9+/]{43}=$ Ed25519 private seed (32 raw bytes, standard base64).
kx_priv required stringpattern ^[A-Za-z0-9+/]{43}=$ X25519 private scalar (32 raw bytes, standard base64).
Responses
200

What the daemon knows about its licence: the response of GET /v1/licence and of every licence mutation. Never carries tokens.

application/json

LicenceState

400

ApiError

401

ApiError

500

ApiError

503

ApiError

POST /v1/licence/keep

Choose the profiles that stay startable over the plan limit

"lapsed to Free": while used exceeds limits.profiles, only these profiles may start; the others answer 423 profile.locked (visible, exportable). Stored locally and mirrored to the cloud when online. At most limits.profiles ids (403 licence.profile_limit); 404 profile.not_found for an unknown id.

Request body required · application/json
Field Type Description
profile_ids required array<string (uuid)>max items 1000 Profiles that stay startable while the plan allows fewer profiles than exist.
Responses
200

What the daemon knows about its licence: the response of GET /v1/licence and of every licence mutation. Never carries tokens.

application/json

LicenceState

400

ApiError

401

ApiError

403

ApiError

404

ApiError

POST /v1/licence/integrity

Record the shell's integrity hashes for the next heartbeat

the desktop shell reports shell_sha256 (its executable) and bundle_sha256 (its webview bundle) after start; the daemon keeps them in memory and sends them, with its own sidecar_sha256, in every hourly POST /devices/heartbeat. Nothing is verified locally.

Request body required · application/json

Hashes the desktop shell attests for itself (shell_sha256: the shell executable; bundle_sha256: the webview bundle). Kept in memory and sent with the next heartbeat; the daemon adds sidecar_sha256 itself when it runs as a sidecar.

Field Type Description
shell_sha256 stringpattern ^[0-9a-fA-F]{64}$ SHA-256, hex.
bundle_sha256 stringpattern ^[0-9a-fA-F]{64}$ SHA-256, hex.
Responses
204
400

ApiError

401

ApiError

GET /v1/licence/ticket

Engine launch ticket

launch = lic . b64url(claim) . b64url(csig) for --ant0-launch=, valid 15 min, bound to engine (the release version the engine reports). For SDKs launching the engine directly; the daemon's own launches attach one automatically. 403 licence.required without a usable licence, 403 workspace.suspended when suspended.

Parameters
Name In Type Description
engine required query string Release version the ticket is for, e.g. 149.0.7827.114-ant0.1 (must equal the running engine's version).
Responses
200

application/json

Field Type Description
launch required string lic . b64url(claim) . b64url(csig): pass as --ant0-launch=<launch>. Contains the licence token; treat as a secret of this device.
engine required string
expires_at required string (date-time)
400

ApiError

401

ApiError

403

ApiError

events

The event stream: profile state, install progress, proxy checks, licence changes.

GET /v1/events

Event stream (WebSocket) or recent events (HTTP)

Upgrade to WebSocket to receive the buffered recent events followed by live Ant0Event JSON frames (profile.state, browser.install, asset.install, proxy.check, daemon.log). A plain GET returns the buffered events. ?token= may replace the Authorization header on this route.

Parameters
Name In Type Description
since query string Only replay buffered events at or after this time.
limit query integer default 50
token query string Bearer token for WebSocket clients that cannot set headers.
Responses
200

application/json

Field Type Description
items required array<Ant0Event>
400

ApiError

401

ApiError

Schemas

39 named schemas referenced by the operations above.

Ant0Event Ant0 event v1

One event on the WebSocket /v1/events stream (JSON lines). Discriminated on "type".

one of

  1. Ant0EventProfileState

  2. Ant0EventProfileLifecycle

  3. Ant0EventBrowserInstall

  4. Ant0EventAssetInstall

  5. Ant0EventProxyCheck

  6. Ant0EventLicenceChanged

  7. Ant0EventDaemonLog

Ant0EventAssetInstall

Field Type Description
type required "asset.install"
asset required "population-model" | "fontpack"
phase required "download" | "verify" | "done" | "error"
message string
at required Ant0EventAt

Ant0EventAt

string (date-time)

Ant0EventBrowserInstall

Field Type Description
type required "browser.install"
version required stringmin length 1
phase required "resolve" | "download" | "verify" | "extract" | "done" | "error"
bytes integermin 0
total integermin 0
message string
code string With phase error: the daemon-side failure code (download_interrupted, checksum_mismatch, store_unreachable, disk_full, release_signature, release_error, install_failed, …).
at required Ant0EventAt

Ant0EventDaemonLog

Field Type Description
type required "daemon.log"
level required "info" | "warn" | "error"
message required string
at required Ant0EventAt

Ant0EventLicenceChanged

The licence state changed: sign-in/out, a refresh, a plan change, entering offline grace, lock or suspension. Read GET /v1/licence for the full picture.

Field Type Description
type required "licence.changed"
state required "signed_out" | "active" | "grace" | "locked" | "suspended"
plan required string | null
at required Ant0EventAt

Ant0EventProfileLifecycle

Trash lifecycle: moved to the trash, restored from it, or purged (row and directory gone).

Field Type Description
type required "profile.trashed" | "profile.restored" | "profile.purged"
profile_id required stringmin length 1
at required Ant0EventAt

Ant0EventProfileState

Field Type Description
type required "profile.state"
profile_id required stringmin length 1
state required "starting" | "running" | "stopping" | "stopped" | "crashed"
pid integermin 1
cdp_url string (uri)
exit_code integer | null
at required Ant0EventAt

Ant0EventProxyCheck

Field Type Description
type required "proxy.check"
proxy_id required stringmin length 1
ok required boolean
at required Ant0EventAt

ApiError

Field Type Description
error required string Namespaced, client-stable code: validation_failed, unauthorized, not_found, profile.not_found, profile.name_taken, profile.ambiguous_name, profile.already_running, profile.not_running, profile.running, profile.trashed, profile.not_trashed, proxy.not_found, proxy.in_use, proxy.change_ip_failed, browser.not_found, browser.not_installed, browser.in_use, browser.install_failed, browser.store_unavailable, browser.download_interrupted, browser.checksum_mismatch, job.not_found, identity.generation_failed, launch.failed, launch.timeout, cookies.invalid, cookies.cdp_failed, cookies.too_large, extension.not_found, extension.invalid, extension.in_use, extension.exists, storage.full, storage.readonly, storage.io, internal; Phase 3 (licence): auth.invalid_credentials, auth.totp_required, auth.totp_invalid, auth.email_unverified, auth.rate_limited, device.limit, device.unknown, device.fingerprint_unavailable, licence.required, licence.expired, licence.offline, licence.profile_limit, licence.feature, licence.invalid, workspace.suspended, workspace.lapsed, profile.locked, ticket.invalid.
message required string
details any Ajv issues for validation_failed; { code, path } for storage.*; { code } (the daemon-side install code) for browser.* install failures.

Extension

Field Type Description
id required string Library id: the Web Store id when the manifest has a key, else <slug>-<8 hex>.
name required string
version required string
description required string May be empty.
manifest_version required 2 | 3

one of

  1. 2

  2. 3

icon_path required string | null Absolute path of the largest manifest icon, or null.

one of

  1. string

  2. null

icon_data_url required string | null The icon as a base64 data: URL when it is at most 64 KB; else null.

one of

  1. string

  2. null

path required string Absolute library folder; this is what launch.extensions holds.
size_bytes required integermin 0
added_at required string (date-time)
used_by required array<string (uuid)> Profiles (live and trashed) whose launch.extensions include path.

InstallJob

Field Type Description
job_id required string (uuid)
status required "running" | "done" | "error"

one of

  1. "running"

  2. "done"

  3. "error"

channel required string
version required string | null Known once the channel resolved (immediately when pinned).

one of

  1. string

  2. null

phase required "download" | "verify" | "extract" | null Latest progress phase; null before the download starts.

one of

  1. "download"

  2. "verify"

  3. "extract"

  4. null

bytes required integer | null Progress in the phase's unit (bytes for download/verify, entries for extract).

one of

  1. integer min 0

  2. null

total required integer | null Total in the same unit; 0 when unknown (no Content-Length).

one of

  1. integer min 0

  2. null

browser required InstalledBrowser | null

one of

  1. InstalledBrowser

  2. null

error required ApiError | null

one of

  1. ApiError

  2. null

created_at required string (date-time)
finished_at required string (date-time) | null

one of

  1. string (date-time)

  2. null

InstalledBrowser

Field Type Description
version required string Release version, e.g. 149.0.7827.114-ant0.1.
chromium required string
target required string windows-x64 or linux-x64.
path required string Install directory.
executable required string
installed_at required string (date-time)
size_bytes required integermin 0
default required boolean True for exactly one installed release: the one unpinned profiles launch (PUT /v1/browsers/default; newest installed when unset).

LicenceState Ant0 licence state v1

What the daemon knows about its licence: the response of GET /v1/licence and of every licence mutation. Never carries tokens.

Field Type Description
state required "signed_out" | "active" | "grace" | "locked" | "suspended" signed_out: no cloud session; active: token valid (now <= exp); grace: offline grace (exp < now <= grace); locked: past grace, no token, or the server refused (lapsed); suspended: the server answered workspace.suspended.
mode required "enforce" | "off" enforce: the §7 table applies; off: development mode (ANT0_LICENCE_MODE=off), nothing is enforced and launches carry no ticket unless a licence is present anyway.
plan required null | string Plan id from the token (free, p10, p50, p200, p1000); null without a token.
limits required null | object
Field Type Description
profiles required integermin 0
seats required integermin 0
used required integermin 0 Profiles counted against the plan: the larger of used_local and the workspace-wide active claim count the cloud last reported (claims made on other devices included). Shown to the user; the local gates use used_local.
used_local required integermin 0 Profiles holding a claim on this device: live plus trashed rows (the trash keeps its claim so restores are free; purge releases it). Drives the keep list and the over-the-limit lock.
features required array<string> Feature flags from the token (feat), e.g. api, sync, teams, mcp, priority_support.
billing required "active" | "past_due" | "lapsed" | null Subscription status from the token (st); informational, enforcement follows limits.
expires_at required null | string (date-time)
grace_until required null | string (date-time)
device_id required null | stringpattern ^[A-Z2-7]{26}$ base32(SHA-256(hw)[0..16]), 26 characters; null when the hardware fingerprint could not be computed.
sign_pub required null | stringpattern ^[A-Za-z0-9+/]{43}=$ This daemon's device signing public key (Ed25519, 32 raw bytes, standard base64) — the sign_pub it registers and the dpk a licence should name. The desktop shell compares it with its own and hands its keys over when they differ. Public material; null before the keys are loaded.
workspace required null | object
Field Type Description
id required stringmin length 1
name required null | string
online required boolean True when the last POST /v1/licence to the cloud succeeded.
last_refresh_at required null | string (date-time)
last_error required null | string Why the last refresh failed (a cloud error code or network); null after a success.
keep required object Profiles allowed to start while used exceeds limits.profiles (§7 "lapsed to Free"). explicit is true once the user chose (POST /v1/licence/keep); otherwise the daemon's default pick is shown. Empty when the limit is not exceeded.
Field Type Description
profile_ids required array<string (uuid)>
explicit required boolean
message required null | string One human sentence for the current state ("Reconnect within 47 h", "Plan allows 5 profiles"), or null when nothing needs attention.

ProfileBrowser

Field Type Description
channel required "stable"
version required null | stringmin length 1 · max length 64 Pinned release, e.g. "149.0.7827.114-ant0.1"; null = newest installed.

ProfileCreate Ant0 profile create

Profile create request: name is required, everything else defaults.

Field Type Description
name required stringmin length 1 · max length 120
group string | nullmin length 1 · max length 120
tags ProfileInputTags
notes stringmax length 4000
status string | nullmin length 1 · max length 120
pinned boolean Pinned rows sort first in clients. Default false.
browser ProfileInputBrowser
identity ProfileInputIdentity
network ProfileInputNetwork
overrides ProfileInputOverrides
launch ProfileInputLaunch

ProfileDetail Ant0 profile detail

profile-manifest-v1 plus runtime (the live session, or null when stopped), deleted_at (RFC 3339 while in the trash, else null) and platform (the OS persona the browser presents, as in ProfileSummary).

Field Type Description
schema required "ant0-profile/v1"
id required ProfileUuid
name required stringmin length 1 · max length 120
group required null | stringmin length 1 · max length 120
tags required ProfileTags
notes required stringmax length 4000
status required null | stringmin length 1 · max length 120
pinned required boolean Pinned rows sort first in clients. Default false.
created_at required string (date-time)
updated_at required string (date-time)
browser required ProfileBrowser
identity required ProfileIdentity
network required ProfileNetwork
overrides required ProfileOverrides
launch required ProfileLaunch
runtime required Session | null

one of

  1. Session

  2. null

deleted_at required string (date-time) | null

one of

  1. string (date-time)

  2. null

platform required "windows" | "linux" | "macos" | "android" | null OS persona the browser presents: overrides.platform (passed to the engine as --fingerprint-platform), else the OS of the persisted synthetic/captured persona (compatibility.os_family, known once the identity has been previewed or launched); null when neither is known or the identity is native.

ProfileGeo

Field Type Description
source required "proxy" | "manual" | "none" proxy: derive timezone/languages/location from the exit IP at launch.
timezone required null | stringmin length 1 · max length 64 · pattern ^[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)*$ IANA zone name, e.g. "Europe/Berlin".
languages required array<string> BCP-47 tags, first is primary.
latitude required null | numbermin -90 · max 90
longitude required null | numbermin -180 · max 180

ProfileIdentity

Field Type Description
mode required "synthetic" | "captured" | "native"
key required null | stringmin length 1 · max length 256 synthetic: deterministic identity key; defaults to the profile id.
source required null | object
Field Type Description
kind required "population-model" | "templates" | "cloud"
version required stringmin length 1 · max length 64
profile_ref required null | stringmin length 1 · max length 512 · pattern ^(?![/\\])(?![A-Za-z]:)(?!(.*[/\\])?\.\.([/\\]|$)).+$ captured: file under identities/, relative (no absolute paths, no parent traversal).

ProfileInput Ant0 profile input

Partial profile-manifest-v1 for PATCH: objects merge, arrays and scalars replace. network.proxy may carry an inline proxy instead of proxy_id; overrides.<key>: null removes that override.

Field Type Description
name stringmin length 1 · max length 120
group string | nullmin length 1 · max length 120
tags ProfileInputTags
notes stringmax length 4000
status string | nullmin length 1 · max length 120
pinned boolean Pinned rows sort first in clients. Default false.
browser ProfileInputBrowser
identity ProfileInputIdentity
network ProfileInputNetwork
overrides ProfileInputOverrides
launch ProfileInputLaunch

ProfileInputBrowser

Field Type Description
channel "stable"
version string | nullmin length 1 · max length 64 Pinned release, e.g. "149.0.7827.114-ant0.1"; null = newest installed.

ProfileInputGeo

Field Type Description
source "proxy" | "manual" | "none" proxy: derive timezone/languages/location from the exit IP at launch.
timezone string | nullmin length 1 · max length 64 · pattern ^[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)*$ IANA zone name, e.g. "Europe/Berlin".
languages array<string> BCP-47 tags, first is primary.
latitude number | nullmin -90 · max 90
longitude number | nullmin -180 · max 180

ProfileInputIdentity

Field Type Description
mode "synthetic" | "captured" | "native"
key string | nullmin length 1 · max length 256 synthetic: deterministic identity key; defaults to the profile id.
source object | null
Field Type Description
kind "population-model" | "templates" | "cloud"
version stringmin length 1 · max length 64
profile_ref string | nullmin length 1 · max length 512 · pattern ^(?![/\\])(?![A-Za-z]:)(?!(.*[/\\])?\.\.([/\\]|$)).+$ captured: file under identities/, relative (no absolute paths, no parent traversal).

ProfileInputLaunch

Field Type Description
start_urls array<string (uri)>
extensions array<string> Absolute paths to unpacked extensions (POSIX "/..." or Windows "X:\...").
window object | null
Field Type Description
width integermin 200 · max 16384
height integermin 200 · max 16384
fonts_resolve boolean
headless boolean
extra_args array<string> Power users; identity switches are rejected by the SDK.

ProfileInputNetwork

Field Type Description
proxy_id string (uuid) | null null = direct connection (allowed, UI warns).
geo ProfileInputGeo
webrtc "proxy-only" | "disabled" | "host"
proxy ProxyCreate | object | object

one of

  1. ProxyCreate

  2. scheme://user:pass@host:port

    Field Type Description
    url required stringmin length 1 · max length 2048

  3. Provider export line: host:port:user:pass, scheme://host:port:user:pass, ...

    Field Type Description
    line required stringmin length 1 · max length 2048

ProfileInputOverrides

Allowlisted subset of the Node SDK IdentityOverrides. On input every key also accepts null: the override is removed from the manifest (PATCH) or left unset (create).

Field Type Description
platform "windows" | "linux" | "macos" | "android" | null
platformVersion string | nullmin length 1 · max length 64
brand string | nullmin length 1 · max length 64
brandVersion string | nullmin length 1 · max length 64
gpuVendor string | nullmin length 1 · max length 256
gpuRenderer string | nullmin length 1 · max length 512
hardwareConcurrency integer | nullmin 1 · max 1024
deviceMemory number | nullmax 1024 navigator.deviceMemory in GB.
screenWidth integer | nullmin 1 · max 32768
screenHeight integer | nullmin 1 · max 32768
availWidth integer | nullmin 1 · max 32768
availHeight integer | nullmin 1 · max 32768
colorDepth integer | nullmin 1 · max 64
devicePixelRatio number | nullmax 16
maxTouchPoints integer | nullmin 0 · max 256
location string | nullpattern ^-?(?:90(?:\.0+)?|[1-8]?[0-9](?:\.[0-9]+)?), ?-?(?:180(?:\.0+)?|1[0-7][0-9](?:\.[0-9]+)?|[1-9]?[0-9](?:\.[0-9]+)?)$ Geolocation as "lat,lon".
timezone string | nullmin length 1 · max length 64 · pattern ^[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)*$
acceptLanguage string | nullmin length 1 · max length 256 Accept-Language list, e.g. "en-US,en".
webrtcIp string | nullmin length 1 · max length 64
webrtcMdns "on" | "off" | null
disableGpuFingerprint boolean | null
fingerprintNoise boolean | null
gpuStringSpoof boolean | null
canvasNoise boolean | null
storageQuota integer | nullmin 0 navigator.storage.estimate().quota in megabytes.
canvasBridge object | null
Field Type Description
url stringpattern ^wss?://
auth stringmin length 1
mode "off" | "all" | "allow" | "deny"
allow array<string>
deny array<string>
fallback "block" | "local"
tlsProfile string | integer | null "match-persona" | "auto" | "native" | "off" | "chrome-<major>" | Chromium major as an integer.

one of

  1. string min length 1 · max length 32

  2. integer min 1

  3. null

ProfileInputTags

array of string

ProfileLaunch

Field Type Description
start_urls required array<string (uri)>
extensions required array<string> Absolute paths to unpacked extensions (POSIX "/..." or Windows "X:\...").
window required null | object
Field Type Description
width required integermin 200 · max 16384
height required integermin 200 · max 16384
fonts_resolve required boolean
headless required boolean
extra_args required array<string> Power users; identity switches are rejected by the SDK.

ProfileManifest Ant0 profile manifest v1

Canonical stored profile document (schema "ant0-profile/v1"). Runtime state (running, pid, cdp url) is not part of the manifest.

Field Type Description
schema required "ant0-profile/v1"
id required ProfileUuid
name required stringmin length 1 · max length 120
group required null | stringmin length 1 · max length 120
tags required ProfileTags
notes required stringmax length 4000
status required null | stringmin length 1 · max length 120
pinned required boolean Pinned rows sort first in clients. Default false.
created_at required string (date-time)
updated_at required string (date-time)
browser required ProfileBrowser
identity required ProfileIdentity
network required ProfileNetwork
overrides required ProfileOverrides
launch required ProfileLaunch

ProfileNetwork

Field Type Description
proxy_id required null | string (uuid) null = direct connection (allowed, UI warns).
geo required ProfileGeo
webrtc required "proxy-only" | "disabled" | "host"

ProfileOverrides

Allowlisted subset of the Node SDK IdentityOverrides.

Field Type Description
platform "windows" | "linux" | "macos" | "android"
platformVersion stringmin length 1 · max length 64
brand stringmin length 1 · max length 64
brandVersion stringmin length 1 · max length 64
gpuVendor stringmin length 1 · max length 256
gpuRenderer stringmin length 1 · max length 512
hardwareConcurrency integermin 1 · max 1024
deviceMemory numbermax 1024 navigator.deviceMemory in GB.
screenWidth integermin 1 · max 32768
screenHeight integermin 1 · max 32768
availWidth integermin 1 · max 32768
availHeight integermin 1 · max 32768
colorDepth integermin 1 · max 64
devicePixelRatio numbermax 16
maxTouchPoints integermin 0 · max 256
location stringpattern ^-?(?:90(?:\.0+)?|[1-8]?[0-9](?:\.[0-9]+)?), ?-?(?:180(?:\.0+)?|1[0-7][0-9](?:\.[0-9]+)?|[1-9]?[0-9](?:\.[0-9]+)?)$ Geolocation as "lat,lon".
timezone stringmin length 1 · max length 64 · pattern ^[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)*$
acceptLanguage stringmin length 1 · max length 256 Accept-Language list, e.g. "en-US,en".
webrtcIp stringmin length 1 · max length 64
webrtcMdns "on" | "off"
disableGpuFingerprint boolean
fingerprintNoise boolean
gpuStringSpoof boolean
canvasNoise boolean
storageQuota integermin 0 navigator.storage.estimate().quota in megabytes.
canvasBridge object
Field Type Description
url required stringpattern ^wss?://
auth stringmin length 1
mode "off" | "all" | "allow" | "deny"
allow array<string>
deny array<string>
fallback "block" | "local"
tlsProfile string | integer "match-persona" | "auto" | "native" | "off" | "chrome-<major>" | Chromium major as an integer.

one of

  1. string min length 1 · max length 32

  2. integer min 1

ProfileSummary

Field Type Description
id required string (uuid)
name required string
group required string | null

one of

  1. string

  2. null

tags required array<string>
notes required string Free text, may be empty.
status required string | null

one of

  1. string

  2. null

pinned required boolean
platform required "windows" | "linux" | "macos" | "android" | null OS persona the browser presents: overrides.platform (passed to the engine as --fingerprint-platform), else the OS of the persisted synthetic/captured persona (compatibility.os_family, known once the identity has been previewed or launched); null when neither is known or the identity is native.
proxy_id required string (uuid) | null

one of

  1. string (uuid)

  2. null

browser_version required string | null

one of

  1. string

  2. null

identity_mode required "synthetic" | "captured" | "native"

one of

  1. "synthetic"

  2. "captured"

  3. "native"

created_at required string (date-time)
updated_at required string (date-time)
last_launched_at required string (date-time) | null

one of

  1. string (date-time)

  2. null

deleted_at required string (date-time) | null Set while the profile is in the trash (GET /v1/profiles?trashed=true).

one of

  1. string (date-time)

  2. null

ProfileTags

array of string

ProfileUuid

string (uuid)

Proxy Ant0 proxy v1

Stored proxy document (schema "ant0-proxy/v1"). Passwords are never stored inline; password_ref points at the secrets table.

Field Type Description
schema required "ant0-proxy/v1"
id required string (uuid)
name required stringmin length 1 · max length 120
type required "http" | "https" | "socks5"
host required stringmin length 1 · max length 253 · pattern ^[^\s/\\@?#\[\]]+$ Hostname, IPv4, or bare IPv6 address (no brackets).
port required integermin 1 · max 65535
username required null | stringmin length 1 · max length 512
password_ref required null | stringpattern ^secret:[0-9a-f-]{36}$ "secret:<uuid>"; never plaintext.
change_ip_url required null | string (uri) Provider "change IP" link, fetched with GET on demand.
session_pattern required null | stringmin length 1 · max length 512 e.g. "user-{session}" substituted into the username per launch.
provider required null | stringmin length 1 · max length 80 Free-form provider label ("brightdata", "iproyal", ...).
udp required boolean socks5 only: pass --socks5-udp so WebRTC/QUIC traverse the proxy. Ignored for http/https (not enforced by this schema). Default false.
tags required array<string>
notes required stringmax length 4000
created_at required string (date-time)
updated_at required string (date-time)
last_check required ProxyCheck

ProxyCheck

Field Type Description
at required string (date-time)
ok required boolean
ip required null | stringmin length 1 · max length 64
country required null | stringmin length 1 · max length 64 ISO 3166-1 alpha-2 when known.
timezone required null | stringmin length 1 · max length 64
latency_ms required null | integermin 0
error required null | stringmin length 1 · max length 2000

ProxyCreate

Proxy in object form. password is plaintext on input only; responses carry password_ref.

Field Type Description
name stringmin length 1 · max length 120
type required "http" | "https" | "socks5"

one of

  1. "http"

  2. "https"

  3. "socks5"

host required stringmin length 1 · max length 253
port required integermin 1 · max 65535
username stringmax length 512
password stringmax length 4096
change_ip_url stringmax length 2048
session_pattern stringmax length 512
provider stringmax length 80
udp boolean
tags array<string>
notes stringmax length 4000

Session Ant0 session v1

A running browser session: the response of POST /v1/profiles/:id/start and the element of GET /v1/sessions.

Field Type Description
profile_id required string (uuid)
pid required integermin 1
ws_endpoint required string (uri)pattern ^wss?:// Full CDP browser endpoint, e.g. ws://127.0.0.1:9333/devtools/browser/<id>.
debug_port required integermin 1 · max 65535
cdp_http required string (uri)pattern ^https?:// HTTP base of the DevTools endpoint, e.g. http://127.0.0.1:9333.
browser_version required stringmin length 1 · max length 64
user_agent required null | stringmin length 1 · max length 1024
headless required boolean
started_at required string (date-time)

TrashedProfileSummary

Field Type Description
id required string (uuid)
name required string
group required string | null

one of

  1. string

  2. null

tags required array<string>
notes required string Free text, may be empty.
status required string | null

one of

  1. string

  2. null

pinned required boolean
platform required "windows" | "linux" | "macos" | "android" | null OS persona the browser presents: overrides.platform (passed to the engine as --fingerprint-platform), else the OS of the persisted synthetic/captured persona (compatibility.os_family, known once the identity has been previewed or launched); null when neither is known or the identity is native.
proxy_id required string (uuid) | null

one of

  1. string (uuid)

  2. null

browser_version required string | null

one of

  1. string

  2. null

identity_mode required "synthetic" | "captured" | "native"

one of

  1. "synthetic"

  2. "captured"

  3. "native"

created_at required string (date-time)
updated_at required string (date-time)
last_launched_at required string (date-time) | null

one of

  1. string (date-time)

  2. null

deleted_at required string (date-time)
purge_at required string (date-time) When the sweeper will purge it: deleted_at + trash_retention_days.