Folders

List folders

get

Distinct, non-empty folder tags across persistent profiles.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Responses

200

Folder names.

application/json

string[]OptionalExample: ["work","scrapers"]

401

Missing or invalid Bearer token.

get

/folders

HTTPcURLJavaScriptPython

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

[
  "work",
  "scrapers"
]

Delete a folder

delete

Deletes the folder tag. With delete_profiles=true the profiles in it are deleted too; otherwise they're unfiled (moved to "All").

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

folderstringRequired

Query parameters

delete_profilesbooleanOptional

Delete the profiles in the folder (default false = unfile).

Default: false

Responses

200

Deleted.

application/json

deleted_folderstringOptional

delete_profilesbooleanOptional

profilesintegerOptional

Profiles affected.

401

Missing or invalid Bearer token.

delete

/folders/{folder}

HTTPcURLJavaScriptPython

DELETE /folders/{folder} HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "deleted_folder": "text",
  "delete_profiles": true,
  "profiles": 1
}

Rename a folder

patch

Retags every profile in the folder. Returns the count.

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

folderstringRequired

Body

application/json

namestringRequired

New folder name.

Responses

200

Renamed.

application/json

renamed_tostringOptional

profilesintegerOptional

Profiles retagged.

401

Missing or invalid Bearer token.

patch

/folders/{folder}

HTTPcURLJavaScriptPython

PATCH /folders/{folder} HTTP/1.1
Host: 127.0.0.1:40325
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "renamed_to": "text",
  "profiles": 1
}

Create a profile in a folder

post

Same as POST /profiles, but the folder comes from the path (overriding any folder in the body).

Authorizations

bearerAuth

AuthorizationstringRequired

Permanent JWT from Settings → Automation API.

Path parameters

folderstringRequired

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

/folders/{folder}/profiles

HTTPcURLJavaScriptPython

POST /folders/{folder}/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"
}