Profiles

List profiles

get

Lists persistent profiles (temporary profiles are hidden), newest first, pinned on top. Each entry is enriched with live run state.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Responses

200

Profile list.

application/json

Launcher-facing profile metadata (returned by create).

idstring · uuidOptional

namestringOptional

notesstringOptional

proxy_idstring · nullableOptional

last_launched_atstring · nullableOptional

ISO-8601 or null.

created_atstring · nullableOptional

pinnedbooleanOptional

folderstringOptional

runningbooleanOptional

pidinteger · int64 · nullableOptional

401

Missing or invalid Bearer token.

get

/profiles

HTTPcURLJavaScriptPython

GET /profiles HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "notes": "text",
    "proxy_id": "text",
    "last_launched_at": "text",
    "created_at": "text",
    "pinned": true,
    "folder": "text",
    "running": true,
    "pid": 1,
    "cdp": {
      "port": 1,
      "http_url": "http://127.0.0.1:53217",
      "web_socket_debugger_url": "ws://127.0.0.1:53217/devtools/browser/ab12-..."
    }
  }
]

Create a profile

post

Persists a profile from a client-supplied fingerprint exactly as given (no re-randomization — uniquification already happened in /fingerprint/new). Use folder to file it; bind a proxy by stored proxy_id or attach one inline via proxy (a string that is NOT saved to the proxy store).

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Body

application/json

namestringOptional

notesstringOptional

proxy_idstringOptional

Bind a proxy already in the store (by id).

proxystringOptional

Attach a proxy by string (host:port:user:pass or scheme://user:pass@host:port). On a persistent profile it is added to the proxy store (deduped by endpoint) and full-tested (UDP + geo), then bound by id — so it appears in the proxy list and QUIC/WebRTC gating has a cached result. On a temporary profile it is attached inline (not stored). Ignored if proxy_id is set.

Example: socks5://user:[email protected]:1080

folderstringOptional

Folder tag (ignored on /folders/{folder}/profiles, which wins).

Responses

200

Created profile metadata.

application/json

Launcher-facing profile metadata (returned by create).

idstring · uuidOptional

namestringOptional

notesstringOptional

proxy_idstring · nullableOptional

last_launched_atstring · nullableOptional

ISO-8601 or null.

created_atstring · nullableOptional

pinnedbooleanOptional

folderstringOptional

400

Missing/!object fingerprint, or an unparseable proxy string.

application/json

401

Missing or invalid Bearer token.

post

/profiles

HTTPcURLJavaScriptPython

POST /profiles HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1157

{
  "name": "text",
  "notes": "text",
  "proxy_id": "text",
  "proxy": "socks5://user:[email protected]:1080",
  "folder": "text",
  "fingerprint": {
    "name": "text",
    "notes": "text",
    "seed": 1,
    "navigator": {
      "user_agent": "text",
      "platform": "Win32",
      "hardware_concurrency": 12,
      "device_memory": 16,
      "language": "text",
      "do_not_track": true,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "screen": {
      "width": 1,
      "height": 1,
      "avail_width": 1,
      "avail_height": 1,
      "color_depth": 24,
      "device_pixel_ratio": 2,
      "color_gamut": "",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "client_hints": {
      "platform": "text",
      "platform_version": "text",
      "architecture": "x86",
      "bitness": "64",
      "mobile": true,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "webgl": {
      "unmasked_vendor": "text",
      "unmasked_renderer": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "webgpu": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "webrtc": "auto",
    "noise": {
      "canvas": {
        "enabled": true,
        "seed": 1
      },
      "webgl": {
        "intensity": 1,
        "enabled": true,
        "seed": 1
      },
      "audio": {
        "intensity": 1,
        "enabled": true,
        "seed": 1
      },
      "client_rects": {
        "max_offset": 1,
        "enabled": true,
        "seed": 1
      },
      "sensors": {
        "enabled": true,
        "seed": 1
      },
      "fonts": {
        "enabled": true,
        "seed": 1
      }
    },
    "network": {
      "blocked_ports": [
        1
      ]
    },
    "timezone": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "notes": "text",
  "proxy_id": "text",
  "last_launched_at": "text",
  "created_at": "text",
  "pinned": true,
  "folder": "text"
}

Create a temporary profile

post

Creates a profile from a random (or specified) library fingerprint, uniquified like /fingerprint/new and stored verbatim, flagged temporary: hidden from listings and auto-deleted when its browser closes (or purged on next app start after a crash). Pair with POST /profiles/{id}/start.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Body

application/json

fingerprint_idstringOptional

Library entry to base off; random match for platform when omitted.

platformstring · enumOptional

Used to pick a random fingerprint when fingerprint_id is omitted; host OS when both omitted.

Possible values:

proxystringOptional

Inline proxy string (not saved to the store).

namestringOptional

folderstringOptional

Responses

200

Created temporary profile.

application/json

idstring · uuidOptional

namestringOptional

fingerprint_idstringOptional

The library entry the profile was generated from.

temporarybooleanOptionalExample: true

proxy_inlinebooleanOptional

Whether an inline proxy string was attached.

400

Unparseable proxy string.

application/json

401

Missing or invalid Bearer token.

404

No matching fingerprint / empty library.

application/json

post

/profiles/temporary

HTTPcURLJavaScriptPython

POST /profiles/temporary HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "fingerprint_id": "text",
  "platform": "Windows",
  "proxy": "text",
  "name": "text",
  "folder": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "fingerprint_id": "text",
  "temporary": true,
  "proxy_inline": true
}

Get a profile

get

Returns the full stored profile: the _meta envelope plus the flattened FingerprintConfig. If the profile is running, running and cdp are added.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Responses

200

The stored profile.

application/json

Full on-disk profile: the _meta envelope plus the flattened FingerprintConfig (all Fingerprint fields appear at the top level). running/cdp are present only while the profile runs.

runningbooleanOptional

Other propertiesanyOptional

401

Missing or invalid Bearer token.

404

No such profile.

application/json

get

/profiles/{id}

HTTPcURLJavaScriptPython

GET /profiles/{id} HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_meta": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "proxy_id": "text",
    "inline_proxy": {
      "id": "text",
      "name": "text",
      "kind": "socks5",
      "host": "text",
      "port": 1,
      "username": "text",
      "password": "text",
      "country": "text",
      "notes": "text"
    },
    "last_launched_at": "text",
    "created_at": "text",
    "pinned": true,
    "folder": "text",
    "temporary": true
  },
  "running": true,
  "cdp": {
    "port": 1,
    "http_url": "http://127.0.0.1:53217",
    "web_socket_debugger_url": "ws://127.0.0.1:53217/devtools/browser/ab12-..."
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Delete a profile

delete

Removes the profile config and its user-data-dir.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Responses

200

Deleted.

application/json

deletedbooleanOptionalExample: true

idstring · uuidOptional

401

Missing or invalid Bearer token.

500

Deletion failed.

application/json

delete

/profiles/{id}

HTTPcURLJavaScriptPython

DELETE /profiles/{id} HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "deleted": true,
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Edit a profile

patch

Updates only the provided fields. When fingerprint is given it REPLACES the stored fingerprint verbatim (no re-randomization). folder: "" unfiles the profile; proxy_id: "" unbinds the proxy; a proxy string is stored (deduped) + full-tested, then bound. Returns the updated stored profile.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Body

application/json

All fields optional — only what's present is changed.

namestringOptional

notesstringOptional

folderstringOptional

"" unfiles (moves to All).

proxy_idstringOptional

"" unbinds the proxy.

proxystringOptional

Proxy string — stored (deduped) + full-tested, then bound.

Responses

200

Updated stored profile.

application/json

Full on-disk profile: the _meta envelope plus the flattened FingerprintConfig (all Fingerprint fields appear at the top level). running/cdp are present only while the profile runs.

runningbooleanOptional

Other propertiesanyOptional

400

Bad fingerprint (not an object) or unparseable proxy.

application/json

401

Missing or invalid Bearer token.

404

No such profile.

application/json

patch

/profiles/{id}

HTTPcURLJavaScriptPython

PATCH /profiles/{id} HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1130

{
  "name": "text",
  "notes": "text",
  "folder": "text",
  "proxy_id": "text",
  "proxy": "text",
  "fingerprint": {
    "name": "text",
    "notes": "text",
    "seed": 1,
    "navigator": {
      "user_agent": "text",
      "platform": "Win32",
      "hardware_concurrency": 12,
      "device_memory": 16,
      "language": "text",
      "do_not_track": true,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "screen": {
      "width": 1,
      "height": 1,
      "avail_width": 1,
      "avail_height": 1,
      "color_depth": 24,
      "device_pixel_ratio": 2,
      "color_gamut": "",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "client_hints": {
      "platform": "text",
      "platform_version": "text",
      "architecture": "x86",
      "bitness": "64",
      "mobile": true,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "webgl": {
      "unmasked_vendor": "text",
      "unmasked_renderer": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "webgpu": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "webrtc": "auto",
    "noise": {
      "canvas": {
        "enabled": true,
        "seed": 1
      },
      "webgl": {
        "intensity": 1,
        "enabled": true,
        "seed": 1
      },
      "audio": {
        "intensity": 1,
        "enabled": true,
        "seed": 1
      },
      "client_rects": {
        "max_offset": 1,
        "enabled": true,
        "seed": 1
      },
      "sensors": {
        "enabled": true,
        "seed": 1
      },
      "fonts": {
        "enabled": true,
        "seed": 1
      }
    },
    "network": {
      "blocked_ports": [
        1
      ]
    },
    "timezone": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "_meta": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "proxy_id": "text",
    "inline_proxy": {
      "id": "text",
      "name": "text",
      "kind": "socks5",
      "host": "text",
      "port": 1,
      "username": "text",
      "password": "text",
      "country": "text",
      "notes": "text"
    },
    "last_launched_at": "text",
    "created_at": "text",
    "pinned": true,
    "folder": "text",
    "temporary": true
  },
  "running": true,
  "cdp": {
    "port": 1,
    "http_url": "http://127.0.0.1:53217",
    "web_socket_debugger_url": "ws://127.0.0.1:53217/devtools/browser/ab12-..."
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Launch a profile (with CDP)

post

Spawns the ShardX browser for the profile with remote-debugging enabled, resolves any auto timezone/locale/geo from the bound proxy, and returns the CDP endpoint once Chrome has written its DevToolsActivePort. CDP is enabled only on API launches (UI launches stay debugging-free for anti-detect). cdp is null if the endpoint couldn't be read within the timeout. Works for both regular and temporary profiles.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Body

application/json

headlessbooleanOptional

Launch headless (--headless=new).

Default: false

Responses

200

Launched.

application/json

profile_idstringOptional

pidinteger · int64Optional

OS process id.

headlessbooleanOptional

401

Missing or invalid Bearer token.

500

Binary not configured / spawn failed.

application/json

post

/profiles/{id}/start

HTTPcURLJavaScriptPython

POST /profiles/{id}/start HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "headless": false
}

{
  "profile_id": "text",
  "pid": 1,
  "headless": true,
  "cdp": {
    "port": 1,
    "http_url": "http://127.0.0.1:53217",
    "web_socket_debugger_url": "ws://127.0.0.1:53217/devtools/browser/ab12-..."
  }
}

Stop a profile

post

Sends the browser a graceful shutdown (SIGTERM on Unix; 5s grace then SIGKILL). Temporary profiles are deleted as part of close. stopped is false if the profile wasn't running.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Responses

200

Stop requested.

application/json

profile_idstringOptional

stoppedbooleanOptional

401

Missing or invalid Bearer token.

post

/profiles/{id}/stop

HTTPcURLJavaScriptPython

POST /profiles/{id}/stop HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "profile_id": "text",
  "stopped": true
}

Export cookies

get

Reads the profile's Chromium cookie store and returns all cookies decrypted. Works whether the profile is running or stopped. Empty array if the profile has never launched.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Responses

200

Cookies.

application/json

401

Missing or invalid Bearer token.

500

Cookie DB read/decrypt failed.

application/json

get

/profiles/{id}/cookies

HTTPcURLJavaScriptPython

GET /profiles/{id}/cookies HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "cookies": [
    {
      "domain": "text",
      "name": "text",
      "value": "text",
      "path": "/",
      "expires": 1,
      "secure": false,
      "http_only": false,
      "same_site": "Strict"
    }
  ]
}

Import cookies

post

Writes cookies into the profile's cookie store (re-encrypting to Chromium's v10 scheme). The profile must be stopped — a running browser rewrites the store on exit and would clobber the import.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

idstring · uuidRequired

Profile UUID.

Body

application/json

Responses

200

Imported.

application/json

importedintegerOptional

Number of cookies written.

401

Missing or invalid Bearer token.

409

Profile is running — stop it first.

application/json

500

Cookie DB write failed.

application/json

post

/profiles/{id}/cookies

HTTPcURLJavaScriptPython

POST /profiles/{id}/cookies HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 137

{
  "cookies": [
    {
      "domain": "text",
      "name": "text",
      "value": "text",
      "path": "/",
      "expires": 1,
      "secure": false,
      "http_only": false,
      "same_site": "Strict"
    }
  ]
}

{
  "imported": 1
}

List running profiles

get

Profiles with a live browser process, including the CDP endpoint when launched via the API.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Responses

200

Running profiles.

application/json

profile_idstringOptional

pidinteger · int64Optional

401

Missing or invalid Bearer token.

get

/running

HTTPcURLJavaScriptPython

GET /running HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "profile_id": "text",
    "pid": 1,
    "cdp": {
      "port": 1,
      "http_url": "http://127.0.0.1:53217",
      "web_socket_debugger_url": "ws://127.0.0.1:53217/devtools/browser/ab12-..."
    }
  }
]