Local API reference

Open MCP & Local API from the top navigation. Its status strip shows whether the server is running, the actual base address and whether a token is required. It serves only this computer’s local browser store.

Configure the server

In Server, set Enable Local API, Require API token, Port and API token, then Save. The default port is 50326; the setting accepts 1024–65535. A port change restarts the server. An empty token field keeps the stored token.

Use the address displayed by the app. A fallback port means scripts using the requested port may reach another process. Restart reconciles the server with saved settings after you clear the conflict.

With the desktop closed, cloutctl system serve can run the Local API. Command line covers its shared queue and sync loop.

Authentication

Token authentication is on by default. Requests can send X-API-Key or Authorization: Bearer; api_key in a query is also accepted. Prefer a header so the token does not become part of a URL.

The desktop token box does not reveal the stored value. Set a token you keep securely, or inspect local settings through cloutctl system settings when appropriate. That command can print sensitive local settings; keep its output private.

/status, /health, /api/v1/status, /docs and /openapi.json are public on this loopback server. Turning authentication off lets local applications call the remaining routes without a token.

A first request

The following examples assume the displayed base address is the default. Set CLOUT_TOKEN in your environment to your own API token; the documentation supplies no credential.

curl http://127.0.0.1:50326/status
curl -H "Authorization: Bearer $CLOUT_TOKEN"   -H 'Content-Type: application/json'   -d '{"page":1,"limit":10}'   http://127.0.0.1:50326/api/v2/browser-profile/list

/status returns {"code":0,"msg":"success"} without a data member. Most operations return code, msg and data. Check code: an operation failure normally returns HTTP 200 with code: -1. Invalid authentication returns HTTP 401 with code: -401 and “Invalid or missing API key”.

JSON body and query handling are route-specific. On v2 and v3 calls, a query value overrides a body field with the same name. v1 writes read their body directly. v2 writes use POST. v3 reads accept GET or POST; v3 writes use POST. Paths are case-insensitive and trailing-slash-insensitive for compatibility.

List and address profiles

POST /api/v2/browser-profile/list supports profile_id, profile_no, group_id, pagination and sorting. Results have data.list, page, limit and page_size; do not require a total field. A short page is the stopping condition when paginating.

Use IDs returned by the list. For one profile, supply profile_id or the register’s profile_no. Do not guess an ID from a Creator’s display name.

Create, update, start and stop

A literal proxy uses user_proxy_config with proxy_soft, proxy_type, proxy_host, proxy_port, proxy_user and proxy_password. For a custom gateway, proxy_soft is other. The example below deliberately has no username or password:

{
  "name": "Creator A · X",
  "user_proxy_config": {
    "proxy_soft": "other",
    "proxy_type": "socks5",
    "proxy_host": "203.0.113.10",
    "proxy_port": "1080"
  }
}

delete_cache on start requests cache clearing at close. It is separate from replacing session cookies. Default visible launch is headless: false.

A successful v2 start exposes data.ws.puppeteer, the CDP WebSocket, and browser connection information. Connect automation to the returned endpoint rather than starting a second browser with a new identity.

import { chromium } from 'playwright';

const response = await fetch(`${baseUrl}/api/v2/browser-profile/start`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ profile_id: profileId }),
});
const reply = await response.json();
if (reply.code !== 0) throw new Error(reply.msg);
const browser = await chromium.connectOverCDP(reply.data.ws.puppeteer);

baseUrl, token and profileId in this example are values obtained by your integration. Stop through the API when finished so the normal capture and cleanup path runs.

Profile creation fields

v1 and v2 use a compatibility mapper. Top-level fields include name, remark, domain_name, platform, username, password, fakey, cookie, ipchecker, ip, country, category_id, sys_app_cate_id, group_id, open_urls, tabs and launch_args. group_id must exist. user_proxy_config is a nested object; proxyid selects a saved proxy when no nested object was supplied. Keep credential-bearing bodies and responses out of logs.

fingerprint_config is an object with these verified input fields:

These names belong to the HTTP compatibility vocabulary. They differ from the flat field flags in cloutctl. Avoid sending both aliases unless you intend the documented precedence. On updates, supply only the changes you reviewed; read the resulting record and verify its next launch.

Profile and catalogue reads

Tag create, update and delete use POST on the same prefix. Proxy-list create, update and delete also use POST. Deletion and cookie reads deserve the same deliberate handling as the corresponding desktop actions.

v1 compatibility

v1 supports existing AdsPower integrations: browser start, stop and active; user list, create, update and delete; and group list, create, update and delete. v2 is the clearer choice for a new profile integration. The route tables below list the installed contract without changing the envelopes existing consumers read.

v3 features

v3 adds folders, templates, extensions, saved proxies, provider templates, proxy pools, bulk actions, tasks, cookie robot, engine preparation, window arrangement, bandwidth and limits. The route index below is organised by resource.

Bulk delete, stop and clear-cache return succeeded, failed and items. Each item has id, ok and, on failure, error. Folder, tag and extension bulk calls return a touched-profile count instead; read the particular operation’s response. Proxy pools are available to scripts rather than as a desktop pool page.

Tasks and cookie robot are real operations on browsers. Create or inspect the task definition before calling run. Cookie robot defaults are readable at /api/v3/cookie-robot/defaults; its start route does not offer a headless option.

Local API documentation and OpenAPI route list use the default address. Substitute the address shown by your installation. They enumerate methods and paths; they do not constitute a full request-field schema.

v1 route index

v1 calls address one profile with user_id or id; start and stop also accept serial_number. List and group reads accept page and page_size. Several compatible v1 actions accept GET, but POST keeps action inputs out of URLs.

The reserved Ungrouped group "0" cannot be renamed or deleted. A v1 group is separate from a v3 folder. Full profile records and cookie reads can contain session or connection credentials; keep their responses private.

Remaining v2 operations

The profile lifecycle and catalogue tables above cover the main routes. These additional operations are implemented:

/api/v2/browser-profile/share refuses in this local launcher. Workspace access is managed through Team. /api/v2/browser-profile/update-patch is a compatibility response, not an app updater; use Check for updates in the desktop.

v3 route and field index

Every read in these tables accepts GET or POST. Every write accepts POST. Inputs name the fields read by the handler; IDs refer to records returned by the matching list. Send arrays and objects in a JSON body. Omitted update fields generally keep their values; exceptions are noted below.

Folders

Kernels

Templates

Extensions

Proxies

Proxy templates

Proxy pools

Referral

Bulk

Tasks

Cookie robot

Entitlements

Arrange

Bandwidth

Data shapes and update rules

• Folder list returns list; get returns folder, ancestors, children and profile_ids. folders/list uses flat to choose a flat list. Folder assignment takes set, add or remove; its default is set. Deleting folder_ids deletes the subtree and unfiles profiles; it does not delete the profiles.
• Templates take config, a profile-creation object. They strip seeds and credentials. apply defaults count to 1, accepts name, group_id and configuration overrides, and returns the created profiles. start_index resumes within the original count; preserve that count and read the created results before retrying.
• Extension rows take name, source, location, optional version and remark. These routes register library metadata and attachments; they do not upload a local extension archive for you. Attachment operations use profile_id, extension_ids and enabled. set-for-profile replaces the profile’s attachment set. set-default uses on for future profiles.
• Saved proxy create accepts one object, a proxies array, or a top-level array. Use proxy_type, proxy_host, proxy_port, proxy_user, proxy_password and title for a connection. Update replaces the saved blob from proxy or the request fields; it does not merge individual old fields. List and get results can contain credentials. Keep responses private.
• proxies/set-default requires proxy_id; explicit null clears it. save-from-profile creates a saved entry from the target’s existing connection. rotate-sessions changes provider sessions and reports per-profile outcomes; it refuses running profiles.
• Proxy templates compose a credential from a saved proxy_id, country, city, duration and sticky. Empty strings and omitted optional strings keep their old values on update. Send a non-empty replacement to change one. Preview returns provider capabilities and placeholders, without actual credential values.
• Proxy pools hold saved proxy IDs. rotation is round_robin (default) or random. Assigning a pool to profiles changes their launch egress. peek reads the next member; rotate also advances the cursor. Delete unassigns profiles and returns unassigned_profiles. If an account deletion fails, that pool remains and appears in failed. Publish and assignment responses can contain cloud.error even when the local operation succeeded. Read health before rotating a pool whose members may be unavailable.
• Bulk folder, tag and extension operations take mode: set, add or remove. Folder defaults to set; tag and extension default to add. Delete, stop and clear-cache report per-profile outcomes. An empty cache types list means everything.
• Kernel prepare takes non-empty profile_ids and starts preparation; status takes its returned run_id. This prepares SunBrowser requirements; Kameleo’s Chroma installation is separate.
• Bandwidth uses window_seconds, not a calendar period. Read the returned window and saved.note; these fleet measurements are a lower bound and differ from the account dashboard’s all-time roll-up.
• Referral routes record attribution and codes. They do not implement a paid reward or a payout.

Tasks and cookie robot

Tasks are available through HTTP and the CLI. Save a definition, run it against returned profile IDs, and poll tasks/run-status using run_id. A start response means the profiles were admitted; it does not mean the work finished. keep_open leaves task browsers open when requested. Cancellation stops further admission and signals work in flight. Deleting a task definition keeps historical run records.

Task steps is an array of these objects:

A literal type value is {"from":"text","text":"Example"}. A credential reference uses from: "credential", site, field (username, password or totp) and optional label. The reference resolves within each profile; the raw two-factor seed is not a task field. Use selectors you have inspected on the target page.

Definitions allow up to 200 steps. The default step timeout is 30,000 ms, with a maximum of 300,000 ms. A wait is at most 300,000 ms. Default typing delay is 30 ms per key. stopIf.when is present or absent; outcome is stop or fail. stop records success when the condition was the intended endpoint.

Cookie robot is a separate browsing run. Read cookie-robot/defaults, then send profile_ids and, optionally, sites and plan fields to start. Plan values are clamped. The response includes unknown_profile_ids and rejected_sites; inspect them before assuming the entire request ran. Poll cookie-robot/run, then cancel through cookie-robot/cancel if needed. It runs visible browsers and provides no headless field.

Write refusals

A read-only licence refuses API writes too. Profile creation and countable v3 resources consult account limits. Profile starts still pass engine, proxy, sync and queue checks.

Check the envelope and report the refusal before retrying. A changing identity, deleting data or rerunning a task is not made safe by treating every code: -1 as a network failure.

Response and failure reference

The body reader takes at most 5,000,000 bytes. A larger JSON document can be truncated and fail parsing; split large requests instead of relying on HTTP success. Header precedence is X-API-Key, then Authorization, then the api_key query value. The Bearer prefix is case-sensitive.

Response fields to preserve

v2 active uses Active or Inactive in status. Its connection fields include ws.selenium, ws.puppeteer, debug_port and webdriver; debug_port is a string and webdriver can be empty. Start returns the connection fields without the active-status label. v2 cookie reads return cookies as a JSON-encoded string, including "[]" for an absent jar; parse that string separately from the response envelope.

List defaults are page 1 and limit 10, capped at 100. Profile sorting uses sort_type and sort_order. Bulk v2 delete, delete-cache, user-agent and fingerprint operations take at most the first 100 targets. Tag mutations and proxy creation take at most the first 500 records. Read the returned records and counts rather than assuming a longer submitted list was processed.

proxies/rotate-sessions returns rotated and failed. Proxy usage is a sanitised connection grouping, while proxy list and get can expose stored connection secrets. An empty string or the string "null", as well as explicit null, clears the default proxy.

Arrangement accepts a nested layout or flat mode, gap, minWidth, minHeight, plus a nested screen or flat x, y, width, height. Page numbering starts at 0. Omitted profile IDs select running profiles; a plan is a read, apply moves windows, and set-layout changes the remembered choice. Read arrange/layout for capabilities before choosing dimensions.

cookie-robot/defaults is a GET or POST read without inputs. run can report found: false for an unknown run. Entitlement, launch, proxy and stopped-profile checks remain in force even for locally authenticated scripts.