Profiles

List profiles

get

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

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

响应

200

Profile list.

application/json

Launcher-facing profile metadata (returned by create).

idstring · uuid可选

namestring可选

notesstring可选

proxy_idstring · 可为 null可选

last_launched_atstring · 可为 null可选

ISO-8601 or null.

created_atstring · 可为 null可选

pinnedboolean可选

folderstring可选

runningboolean可选

pidinteger · int64 · 可为 null可选

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).

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

请求体

application/json

namestring可选

notesstring可选

proxy_idstring可选

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

proxystring可选

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

folderstring可选

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

响应

200

Created profile metadata.

application/json

Launcher-facing profile metadata (returned by create).

idstring · uuid可选

namestring可选

notesstring可选

proxy_idstring · 可为 null可选

last_launched_atstring · 可为 null可选

ISO-8601 or null.

created_atstring · 可为 null可选

pinnedboolean可选

folderstring可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

请求体

application/json

fingerprint_idstring可选

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

platformstring · enum可选

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

可能的值:

proxystring可选

Inline proxy string (not saved to the store).

namestring可选

folderstring可选

响应

200

Created temporary profile.

application/json

idstring · uuid可选

namestring可选

fingerprint_idstring可选

The library entry the profile was generated from.

temporaryboolean可选Example: true

proxy_inlineboolean可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

响应

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.

runningboolean可选

Other propertiesany可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

响应

200

Deleted.

application/json

deletedboolean可选Example: true

idstring · uuid可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

请求体

application/json

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

namestring可选

notesstring可选

folderstring可选

"" unfiles (moves to All).

proxy_idstring可选

"" unbinds the proxy.

proxystring可选

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

响应

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.

runningboolean可选

Other propertiesany可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

请求体

application/json

headlessboolean可选

Launch headless (--headless=new).

Default: false

响应

200

Launched.

application/json

profile_idstring可选

pidinteger · int64可选

OS process id.

headlessboolean可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

响应

200

Stop requested.

application/json

profile_idstring可选

stoppedboolean可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

响应

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

路径参数

idstring · uuid必填

Profile UUID.

请求体

application/json

响应

200

Imported.

application/json

importedinteger可选

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.

授权

bearerAuth

Authorizationstring必填

Permanent JWT from Settings → Automation API.

响应

200

Running profiles.

application/json

profile_idstring可选

pidinteger · int64可选

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-..."
    }
  }
]