# Profiles
## List profiles
> Lists persistent profiles (temporary profiles are hidden), newest\
> first, pinned on top. Each entry is enriched with live run state.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"schemas":{"ProfileListItem":{"allOf":[{"$ref":"#/components/schemas/ProfileMeta"},{"type":"object","properties":{"running":{"type":"boolean"},"pid":{"type":"integer","format":"int64","nullable":true},"cdp":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CdpInfo"}]}}}]},"ProfileMeta":{"type":"object","description":"Launcher-facing profile metadata (returned by create).","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"notes":{"type":"string"},"proxy_id":{"type":"string","nullable":true},"last_launched_at":{"type":"string","nullable":true,"description":"ISO-8601 or null."},"created_at":{"type":"string","nullable":true},"pinned":{"type":"boolean"},"folder":{"type":"string"}}},"CdpInfo":{"type":"object","description":"Chrome DevTools Protocol endpoint of a running profile.","properties":{"port":{"type":"integer","description":"Chrome-chosen remote-debugging port."},"http_url":{"type":"string","description":"REST base (/json, /json/version)."},"web_socket_debugger_url":{"type":"string","description":"Browser-level WS endpoint for Puppeteer/Playwright `connect`."}}}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles":{"get":{"tags":["Profiles"],"summary":"List profiles","description":"Lists persistent profiles (temporary profiles are hidden), newest\nfirst, pinned on top. Each entry is enriched with live run state.\n","responses":{"200":{"description":"Profile list.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProfileListItem"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Create a profile
> 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).
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"schemas":{"CreateProfileRequest":{"type":"object","required":["fingerprint"],"properties":{"name":{"type":"string"},"notes":{"type":"string"},"proxy_id":{"type":"string","description":"Bind a proxy already in the store (by id)."},"proxy":{"type":"string","description":"Attach a proxy by string (`host:port:user:pass` or\n`scheme://user:pass@host:port`). On a **persistent** profile it is\nadded to the proxy store (deduped by endpoint) and full-tested\n(UDP + geo), then bound by id — so it appears in the proxy list\nand QUIC/WebRTC gating has a cached result. On a **temporary**\nprofile it is attached inline (not stored). Ignored if `proxy_id`\nis set.\n"},"folder":{"type":"string","description":"Folder tag (ignored on /folders/{folder}/profiles, which wins)."},"fingerprint":{"allOf":[{"$ref":"#/components/schemas/Fingerprint"}],"description":"Stored verbatim. Get one from /fingerprint/new and edit as needed."}}},"Fingerprint":{"type":"object","description":"Native FingerprintConfig. Documented sub-objects are the common\nones; the object is open and stored verbatim by the create\nendpoints, so any field present here is round-tripped.\n","additionalProperties":true,"properties":{"name":{"type":"string"},"notes":{"type":"string"},"seed":{"type":"integer","description":"0 = overrides-only mode (the common case)."},"navigator":{"type":"object","additionalProperties":true,"properties":{"user_agent":{"type":"string"},"platform":{"type":"string"},"hardware_concurrency":{"type":"integer"},"device_memory":{"type":"integer","enum":[8,16,32]},"language":{"type":"string"},"do_not_track":{"type":"boolean"}}},"screen":{"type":"object","additionalProperties":true,"properties":{"width":{"type":"integer"},"height":{"type":"integer"},"avail_width":{"type":"integer"},"avail_height":{"type":"integer"},"color_depth":{"type":"integer"},"device_pixel_ratio":{"type":"number"},"color_gamut":{"type":"string","enum":["","srgb","p3","rec2020"]}}},"client_hints":{"type":"object","description":"Sec-CH-UA family (browser.vision calls this `hints`).","additionalProperties":true,"properties":{"platform":{"type":"string"},"platform_version":{"type":"string"},"architecture":{"type":"string"},"bitness":{"type":"string"},"mobile":{"type":"boolean"}}},"webgl":{"type":"object","additionalProperties":true,"properties":{"unmasked_vendor":{"type":"string"},"unmasked_renderer":{"type":"string"}}},"webgpu":{"type":"object","additionalProperties":true},"webrtc":{"type":"string","description":"WebRTC handling mode.","enum":["auto","tcp_only","block"]},"noise":{"$ref":"#/components/schemas/NoisePrefs"},"network":{"type":"object","properties":{"blocked_ports":{"type":"array","items":{"type":"integer"},"description":"Local-network port-scan defense (ports_protection)."}}},"timezone":{"type":"string","description":"IANA name, or \"auto\" to resolve from the bound proxy at launch."}}},"NoisePrefs":{"type":"object","description":"Per-vector anti-fingerprint noise. Each block is `{enabled, seed}`\n(+ feature-specific knobs). `enabled:false` = pass-through.\n","properties":{"canvas":{"$ref":"#/components/schemas/NoiseBlock"},"webgl":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"properties":{"intensity":{"type":"number"}}},"audio":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"properties":{"intensity":{"type":"number"}}},"client_rects":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"properties":{"max_offset":{"type":"number"}}},"sensors":{"$ref":"#/components/schemas/NoiseBlock"},"fonts":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"description":"`enabled:true` hides a small deterministic per-profile subset of\nnon-essential fonts (real host fonts otherwise pass through).\n"}}},"NoiseBlock":{"type":"object","properties":{"enabled":{"type":"boolean"},"seed":{"type":"integer","description":"Per-profile entropy; 0 = derive automatically."}}},"ProfileMeta":{"type":"object","description":"Launcher-facing profile metadata (returned by create).","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"notes":{"type":"string"},"proxy_id":{"type":"string","nullable":true},"last_launched_at":{"type":"string","nullable":true,"description":"ISO-8601 or null."},"created_at":{"type":"string","nullable":true},"pinned":{"type":"boolean"},"folder":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles":{"post":{"tags":["Profiles"],"summary":"Create a profile","description":"Persists a profile from a client-supplied `fingerprint` **exactly as\ngiven** (no re-randomization — uniquification already happened in\n`/fingerprint/new`). Use `folder` to file it; bind a proxy by stored\n`proxy_id` or attach one inline via `proxy` (a string that is NOT\nsaved to the proxy store).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProfileRequest"}}}},"responses":{"200":{"description":"Created profile metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileMeta"}}}},"400":{"description":"Missing/!object `fingerprint`, or an unparseable proxy string.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Create a temporary profile
> 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\`.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"schemas":{"TempProfileRequest":{"type":"object","properties":{"fingerprint_id":{"type":"string","description":"Library entry to base off; random match for `platform` when omitted."},"platform":{"type":"string","enum":["Windows","macOS","Linux"],"description":"Used to pick a random fingerprint when `fingerprint_id` is omitted; host OS when both omitted."},"proxy":{"type":"string","description":"Inline proxy string (not saved to the store)."},"name":{"type":"string"},"folder":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/temporary":{"post":{"tags":["Profiles"],"summary":"Create a temporary profile","description":"Creates a profile from a random (or specified) library fingerprint,\nuniquified like `/fingerprint/new` and stored verbatim, flagged\n`temporary`: hidden from listings and **auto-deleted when its\nbrowser closes** (or purged on next app start after a crash). Pair\nwith `POST /profiles/{id}/start`.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TempProfileRequest"}}}},"responses":{"200":{"description":"Created temporary profile.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"fingerprint_id":{"type":"string","description":"The library entry the profile was generated from."},"temporary":{"type":"boolean"},"proxy_inline":{"type":"boolean","description":"Whether an inline proxy string was attached."}}}}}},"400":{"description":"Unparseable proxy string.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No matching fingerprint / empty library.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get a profile
> Returns the full stored profile: the \`\_meta\` envelope plus the\
> flattened FingerprintConfig. If the profile is running, \`running\`\
> and \`cdp\` are added.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"StoredProfile":{"type":"object","description":"Full on-disk profile: the `_meta` envelope plus the flattened\nFingerprintConfig (all `Fingerprint` fields appear at the top\nlevel). `running`/`cdp` are present only while the profile runs.\n","additionalProperties":true,"properties":{"_meta":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"proxy_id":{"type":"string","nullable":true},"inline_proxy":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ProxyEntry"}]},"last_launched_at":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"pinned":{"type":"boolean"},"folder":{"type":"string"},"temporary":{"type":"boolean"}}},"running":{"type":"boolean"},"cdp":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CdpInfo"}]}}},"ProxyEntry":{"type":"object","description":"Full proxy (as embedded in `_meta.inline_proxy`).","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["socks5","http","https"]},"host":{"type":"string"},"port":{"type":"integer"},"username":{"type":"string"},"password":{"type":"string"},"country":{"type":"string"},"notes":{"type":"string"}}},"CdpInfo":{"type":"object","description":"Chrome DevTools Protocol endpoint of a running profile.","properties":{"port":{"type":"integer","description":"Chrome-chosen remote-debugging port."},"http_url":{"type":"string","description":"REST base (/json, /json/version)."},"web_socket_debugger_url":{"type":"string","description":"Browser-level WS endpoint for Puppeteer/Playwright `connect`."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/{id}":{"get":{"tags":["Profiles"],"summary":"Get a profile","description":"Returns the full stored profile: the `_meta` envelope plus the\nflattened FingerprintConfig. If the profile is running, `running`\nand `cdp` are added.\n","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"responses":{"200":{"description":"The stored profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No such profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Delete a profile
> Removes the profile config and its user-data-dir.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"paths":{"/profiles/{id}":{"delete":{"tags":["Profiles"],"summary":"Delete a profile","description":"Removes the profile config and its user-data-dir.","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Deletion failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Edit a profile
> 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.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"EditProfileRequest":{"type":"object","description":"All fields optional — only what's present is changed.","properties":{"name":{"type":"string"},"notes":{"type":"string"},"folder":{"type":"string","description":"\"\" unfiles (moves to All)."},"proxy_id":{"type":"string","description":"\"\" unbinds the proxy."},"proxy":{"type":"string","description":"Proxy string — stored (deduped) + full-tested, then bound."},"fingerprint":{"allOf":[{"$ref":"#/components/schemas/Fingerprint"}],"description":"When present, REPLACES the stored fingerprint verbatim."}}},"Fingerprint":{"type":"object","description":"Native FingerprintConfig. Documented sub-objects are the common\nones; the object is open and stored verbatim by the create\nendpoints, so any field present here is round-tripped.\n","additionalProperties":true,"properties":{"name":{"type":"string"},"notes":{"type":"string"},"seed":{"type":"integer","description":"0 = overrides-only mode (the common case)."},"navigator":{"type":"object","additionalProperties":true,"properties":{"user_agent":{"type":"string"},"platform":{"type":"string"},"hardware_concurrency":{"type":"integer"},"device_memory":{"type":"integer","enum":[8,16,32]},"language":{"type":"string"},"do_not_track":{"type":"boolean"}}},"screen":{"type":"object","additionalProperties":true,"properties":{"width":{"type":"integer"},"height":{"type":"integer"},"avail_width":{"type":"integer"},"avail_height":{"type":"integer"},"color_depth":{"type":"integer"},"device_pixel_ratio":{"type":"number"},"color_gamut":{"type":"string","enum":["","srgb","p3","rec2020"]}}},"client_hints":{"type":"object","description":"Sec-CH-UA family (browser.vision calls this `hints`).","additionalProperties":true,"properties":{"platform":{"type":"string"},"platform_version":{"type":"string"},"architecture":{"type":"string"},"bitness":{"type":"string"},"mobile":{"type":"boolean"}}},"webgl":{"type":"object","additionalProperties":true,"properties":{"unmasked_vendor":{"type":"string"},"unmasked_renderer":{"type":"string"}}},"webgpu":{"type":"object","additionalProperties":true},"webrtc":{"type":"string","description":"WebRTC handling mode.","enum":["auto","tcp_only","block"]},"noise":{"$ref":"#/components/schemas/NoisePrefs"},"network":{"type":"object","properties":{"blocked_ports":{"type":"array","items":{"type":"integer"},"description":"Local-network port-scan defense (ports_protection)."}}},"timezone":{"type":"string","description":"IANA name, or \"auto\" to resolve from the bound proxy at launch."}}},"NoisePrefs":{"type":"object","description":"Per-vector anti-fingerprint noise. Each block is `{enabled, seed}`\n(+ feature-specific knobs). `enabled:false` = pass-through.\n","properties":{"canvas":{"$ref":"#/components/schemas/NoiseBlock"},"webgl":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"properties":{"intensity":{"type":"number"}}},"audio":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"properties":{"intensity":{"type":"number"}}},"client_rects":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"properties":{"max_offset":{"type":"number"}}},"sensors":{"$ref":"#/components/schemas/NoiseBlock"},"fonts":{"allOf":[{"$ref":"#/components/schemas/NoiseBlock"}],"description":"`enabled:true` hides a small deterministic per-profile subset of\nnon-essential fonts (real host fonts otherwise pass through).\n"}}},"NoiseBlock":{"type":"object","properties":{"enabled":{"type":"boolean"},"seed":{"type":"integer","description":"Per-profile entropy; 0 = derive automatically."}}},"StoredProfile":{"type":"object","description":"Full on-disk profile: the `_meta` envelope plus the flattened\nFingerprintConfig (all `Fingerprint` fields appear at the top\nlevel). `running`/`cdp` are present only while the profile runs.\n","additionalProperties":true,"properties":{"_meta":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"proxy_id":{"type":"string","nullable":true},"inline_proxy":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ProxyEntry"}]},"last_launched_at":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"pinned":{"type":"boolean"},"folder":{"type":"string"},"temporary":{"type":"boolean"}}},"running":{"type":"boolean"},"cdp":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CdpInfo"}]}}},"ProxyEntry":{"type":"object","description":"Full proxy (as embedded in `_meta.inline_proxy`).","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["socks5","http","https"]},"host":{"type":"string"},"port":{"type":"integer"},"username":{"type":"string"},"password":{"type":"string"},"country":{"type":"string"},"notes":{"type":"string"}}},"CdpInfo":{"type":"object","description":"Chrome DevTools Protocol endpoint of a running profile.","properties":{"port":{"type":"integer","description":"Chrome-chosen remote-debugging port."},"http_url":{"type":"string","description":"REST base (/json, /json/version)."},"web_socket_debugger_url":{"type":"string","description":"Browser-level WS endpoint for Puppeteer/Playwright `connect`."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/{id}":{"patch":{"tags":["Profiles"],"summary":"Edit a profile","description":"Updates only the provided fields. When `fingerprint` is given it\nREPLACES the stored fingerprint verbatim (no re-randomization).\n`folder: \"\"` unfiles the profile; `proxy_id: \"\"` unbinds the proxy;\na `proxy` string is stored (deduped) + full-tested, then bound.\nReturns the updated stored profile.\n","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditProfileRequest"}}}},"responses":{"200":{"description":"Updated stored profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredProfile"}}}},"400":{"description":"Bad fingerprint (not an object) or unparseable proxy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No such profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Launch a profile (with CDP)
> 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.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"CdpInfo":{"type":"object","description":"Chrome DevTools Protocol endpoint of a running profile.","properties":{"port":{"type":"integer","description":"Chrome-chosen remote-debugging port."},"http_url":{"type":"string","description":"REST base (/json, /json/version)."},"web_socket_debugger_url":{"type":"string","description":"Browser-level WS endpoint for Puppeteer/Playwright `connect`."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/{id}/start":{"post":{"tags":["Profiles"],"summary":"Launch a profile (with CDP)","description":"Spawns the ShardX browser for the profile with remote-debugging\nenabled, resolves any `auto` timezone/locale/geo from the bound\nproxy, and returns the CDP endpoint once Chrome has written its\nDevToolsActivePort. CDP is enabled **only** on API launches (UI\nlaunches stay debugging-free for anti-detect). `cdp` is `null` if\nthe endpoint couldn't be read within the timeout. Works for both\nregular and temporary profiles.\n","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"requestBody":{"required":false,"description":"Optional. Empty body launches headed.","content":{"application/json":{"schema":{"type":"object","properties":{"headless":{"type":"boolean","default":false,"description":"Launch headless (--headless=new)."}}}}}},"responses":{"200":{"description":"Launched.","content":{"application/json":{"schema":{"type":"object","properties":{"profile_id":{"type":"string"},"pid":{"type":"integer","format":"int64","description":"OS process id."},"headless":{"type":"boolean"},"cdp":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CdpInfo"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Binary not configured / spawn failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Stop a profile
> 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.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/{id}/stop":{"post":{"tags":["Profiles"],"summary":"Stop a profile","description":"Sends the browser a graceful shutdown (SIGTERM on Unix; 5s grace\nthen SIGKILL). Temporary profiles are deleted as part of close.\n`stopped` is `false` if the profile wasn't running.\n","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"responses":{"200":{"description":"Stop requested.","content":{"application/json":{"schema":{"type":"object","properties":{"profile_id":{"type":"string"},"stopped":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Export cookies
> 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.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"Cookie":{"type":"object","description":"A cookie in a tool-friendly shape (compatible with EditThisCookie /\nPuppeteer exports — `httpOnly`/`sameSite` are accepted as aliases on\nimport).\n","required":["domain","name","value"],"properties":{"domain":{"type":"string","description":"Cookie host (Chromium `host_key`), e.g. \".example.com\"."},"name":{"type":"string"},"value":{"type":"string"},"path":{"type":"string","default":"/"},"expires":{"type":"number","nullable":true,"description":"Unix seconds; null/absent = session cookie."},"secure":{"type":"boolean","default":false},"http_only":{"type":"boolean","default":false},"same_site":{"type":"string","enum":["Strict","Lax","None","unspecified"],"description":"Case-insensitive on import."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/{id}/cookies":{"get":{"tags":["Profiles"],"summary":"Export cookies","description":"Reads the profile's Chromium cookie store and returns all cookies\n**decrypted**. Works whether the profile is running or stopped.\nEmpty array if the profile has never launched.\n","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"responses":{"200":{"description":"Cookies.","content":{"application/json":{"schema":{"type":"object","properties":{"cookies":{"type":"array","items":{"$ref":"#/components/schemas/Cookie"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Cookie DB read/decrypt failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Import cookies
> 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.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"parameters":{"ProfileId":{"name":"id","in":"path","required":true,"description":"Profile UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"Cookie":{"type":"object","description":"A cookie in a tool-friendly shape (compatible with EditThisCookie /\nPuppeteer exports — `httpOnly`/`sameSite` are accepted as aliases on\nimport).\n","required":["domain","name","value"],"properties":{"domain":{"type":"string","description":"Cookie host (Chromium `host_key`), e.g. \".example.com\"."},"name":{"type":"string"},"value":{"type":"string"},"path":{"type":"string","default":"/"},"expires":{"type":"number","nullable":true,"description":"Unix seconds; null/absent = session cookie."},"secure":{"type":"boolean","default":false},"http_only":{"type":"boolean","default":false},"same_site":{"type":"string","enum":["Strict","Lax","None","unspecified"],"description":"Case-insensitive on import."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/profiles/{id}/cookies":{"post":{"tags":["Profiles"],"summary":"Import cookies","description":"Writes cookies into the profile's cookie store (re-encrypting to\nChromium's v10 scheme). The profile **must be stopped** — a running\nbrowser rewrites the store on exit and would clobber the import.\n","parameters":[{"$ref":"#/components/parameters/ProfileId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cookies"],"properties":{"cookies":{"type":"array","items":{"$ref":"#/components/schemas/Cookie"}}}}}}},"responses":{"200":{"description":"Imported.","content":{"application/json":{"schema":{"type":"object","properties":{"imported":{"type":"integer","description":"Number of cookies written."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Profile is running — stop it first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Cookie DB write failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## List running profiles
> Profiles with a live browser process, including the CDP endpoint when launched via the API.
```json
{"openapi":"3.0.3","info":{"title":"ShardX Launcher — Automation API","version":"0.1.0"},"tags":[{"name":"Profiles"}],"servers":[{"url":"http://127.0.0.1:40325","description":"Local launcher (default port; change in Settings)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Permanent JWT from Settings → Automation API."}},"schemas":{"RunningProfile":{"type":"object","properties":{"profile_id":{"type":"string"},"pid":{"type":"integer","format":"int64"},"cdp":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CdpInfo"}]}}},"CdpInfo":{"type":"object","description":"Chrome DevTools Protocol endpoint of a running profile.","properties":{"port":{"type":"integer","description":"Chrome-chosen remote-debugging port."},"http_url":{"type":"string","description":"REST base (/json, /json/version)."},"web_socket_debugger_url":{"type":"string","description":"Browser-level WS endpoint for Puppeteer/Playwright `connect`."}}}},"responses":{"Unauthorized":{"description":"Missing or invalid Bearer token."}}},"paths":{"/running":{"get":{"tags":["Profiles"],"summary":"List running profiles","description":"Profiles with a live browser process, including the CDP endpoint when launched via the API.","responses":{"200":{"description":"Running profiles.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RunningProfile"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.proxyshard.com/proxyshard/shardx-launcher-api/profiles.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.