Local API reference

Control AliasMode through a loopback API.

The AliasMode Local API exposes an AdsPower-compatible subset for status, profiles, groups, browser control, cookies, cache, and CDP attachment.

Connect with Playwright Download AliasMode

Tested 2026-08-10

127.0.0.1:50400Default loopback endpoint

13Documented routes

CDPBrowser automation connection

Keep the API local

The Local API has no authentication. Keep port 50400 on the loopback interface. Never expose it to a LAN or the internet through port forwarding or a reverse proxy. A returned CDP URL grants control of the active browser profile, so do not share or publish it.

Check API availability

Start the AliasMode desktop app on the same computer as your integration. Confirm one status route returns a JSON response before sending profile commands.

curl http://127.0.0.1:50400/api/v1/status

Find the route you need

AliasMode implements only the documented subset below. Do not assume that an unlisted AdsPower API route is available.

Status: API health and compatibility
Browser lifecycle: start, stop, and active state
Session data: cookies and browser cache
Groups: list and create
Profiles: list, create, update, and delete

GET /status
GET /api/v1/status
GET /api/v1/browser/start?user_id=&launch_args=
GET /api/v1/browser/stop?user_id=
GET /api/v1/browser/active?user_id=
POST /api/v2/browser-profile/delete-cache
GET /api/v1/browser/cookies?user_id=&urls=
GET /api/v1/group/list?page=&page_size=
POST /api/v1/group/create
GET /api/v1/user/list?page=&page_size=&group_id=&user_sort=
POST /api/v1/user/create
POST /api/v1/user/delete
POST /api/v1/user/update

Follow the request conventions

Responses use the JSON envelope { code, msg, data }. Treat code 0 as success. A successful HTTP response can still contain code -1 and an error message.

Send POST bodies as JSON. URL-encode query values. The user_id value is a profile ID from GET /api/v1/user/list. The optional launch_args value is a URL-encoded JSON array of browser arguments.

{"code":0,"msg":"success","data":{}}

launch_args=["--lang=en-US"]

Discover, start, and stop a profile

Call GET /api/v1/user/list to find a profile ID. Set ALIASMODE_PROFILE_ID, then run the example. It checks both HTTP status and the API envelope, validates data.ws.puppeteer, connects through chromium.connectOverCDP, and stops the profile during cleanup.

import { chromium } from 'playwright';

const origin = 'http://127.0.0.1:50400';
// Find this ID with GET /api/v1/user/list.
const profileId = process.env.ALIASMODE_PROFILE_ID;
if (!profileId) throw new Error('Set ALIASMODE_PROFILE_ID');

const startUrl = new URL('/api/v1/browser/start', origin);
startUrl.searchParams.set('user_id', profileId);

let browser;
let started = false;
try {
  const startResponse = await fetch(startUrl);
  if (!startResponse.ok) {
    throw new Error(`AliasMode returned HTTP ${startResponse.status}`);
  }

  const payload = await startResponse.json();
  const cdpUrl = payload?.data?.ws?.puppeteer;
  if (payload?.code !== 0 || typeof cdpUrl !== 'string') {
    throw new Error(payload?.msg || 'AliasMode did not return a CDP URL');
  }

  started = true;
  browser = await chromium.connectOverCDP(cdpUrl);
  // Run automation with the connected browser.
} finally {
  try {
    await browser?.close();
  } finally {
    if (started) {
      const stopUrl = new URL('/api/v1/browser/stop', origin);
      stopUrl.searchParams.set('user_id', profileId);
      await fetch(stopUrl);
    }
  }
}

Follow the Playwright setup Plan an AdsPower API migration

Handle failures and cleanup

If a command fails, confirm the desktop app is open, the status route responds, and the profile ID exists. Check both the HTTP status and the response code and message. Treat a missing CDP URL as a failed start.

Disconnect Playwright and stop the profile when automation finishes. Stop a browser before deleting its profile.

Troubleshoot Local API access

Endpoint reference

AliasMode Local APIv0.1.0-beta.49http://127.0.0.1:50400

AliasMode serves this API on the loopback interface only (http://127.0.0.1:50400). It has no authentication by design: any process on the same machine can call it. Never expose the listener beyond loopback with a reverse proxy, port forward, or tunnel. A CDP WebSocket URL returned by `browserStart` or `browserActive` grants full control of that browser and its logged-in sessions; treat it like a credential. The API is a compatibility subset of the AdsPower local API, so an AdsPower REST client migrates by changing its base URL. Only the 13 operations in this document exist. Do not assume that any other AdsPower route is available. Two routes are AliasMode extensions: `browserCookies` and the `fp_verdict`/`fp_captured_at` fields of `userList`. Every response uses HTTP status 200 and the JSON envelope `{ code, msg, data }`. `code` is `0` with `msg` `"success"` on success and `-1` with a reason in `msg` on failure, including unknown routes. Inspect `code`, not the HTTP status. The browser-control routes ignore the HTTP method; the group and user routes require the documented method and fall through to `unknown route` otherwise. Each operation carries `x-aliasmode-version-introduced`: the oldest AliasMode release these public contracts cover in which the route exists. All 13 routes exist in 0.1.0-beta.42 and in the current source; they may also exist in earlier builds. In AliasMode Cloud mode the same routes are served, with `browserStart`, `browserStop`, and `browserActive` routed through the cloud coordinator and the group and user routes reading the shared workspace roster. The wire shapes do not change.

status

Health check.

GET/status

Health check (AdsPower path)

`/status` is the path AdsPower's own local API serves. Returns `code: 0` while AliasMode is running. When lifecycle admission control is configured, `data.admission` reports its counters.

Response 200 · Always `code: 0`.

{
  "code": 0,
  "msg": "success",
  "data": {}
}

GET/api/v1/status

Health check (versioned path)

Same response as `/status`. May include `data.admission` statistics when admission control is configured.

Response 200 · Always `code: 0`.

{
  "code": 0,
  "msg": "success",
  "data": {
    "admission": {
      "limit": 4,
      "inFlight": 1,
      "queued": 0,
      "byKind": {
        "stop": {
          "inFlight": 0,
          "queued": 0
        },
        "cleanup": {
          "inFlight": 0,
          "queued": 0
        },
        "start": {
          "inFlight": 1,
          "queued": 0
        }
      }
    }
  }
}

browser

Start, stop, and inspect a profile's browser.

GET/api/v1/browser/start

Start a profile's browser

Launches the CloakBrowser process for the profile, or returns the running one. `data.ws.puppeteer` is the CDP WebSocket URL for automation clients. It grants full control of the browser; do not log or share it. Fails with `no such profile: <id>` for an unknown profile and with the launcher error otherwise.

Parameters
Name	In	Type	Required	Description
`user_id`	query	string	Yes	AliasMode profile id (AdsPower `user_id`). Missing values fail with `missing user_id`.
`launch_args`	query	string	No	URL-encoded JSON array of extra browser command-line arguments. Non-array or invalid JSON is ignored.

Response 200 · Success envelope with the CDP endpoint, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {
    "ws": {
      "puppeteer": "ws://127.0.0.1:53211/devtools/browser/0f2c6d1e-example",
      "selenium": ""
    },
    "debug_port": "53211",
    "webdriver": ""
  }
}

GET/api/v1/browser/stop

Stop a profile's browser

Captures session state and closes the browser. Returns `code: 0` with empty `data` once teardown is confirmed. Fails with `browser teardown unconfirmed: <id>` when the process could not be confirmed stopped.

Parameters
Name	In	Type	Required	Description
`user_id`	query	string	Yes	AliasMode profile id (AdsPower `user_id`). Missing values fail with `missing user_id`.

Response 200 · Success envelope with empty `data`, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {}
}

GET/api/v1/browser/active

Check whether a profile's browser is running

`status` is `Active` or `Inactive`. `lifecycle` reports a transition (`starting`, `stopping`) or `uncertain` when ownership-safe teardown is unconfirmed; `running` accompanies a certified live browser. `ws` is present only for `lifecycle: running`.

Parameters
Name	In	Type	Required	Description
`user_id`	query	string	Yes	AliasMode profile id (AdsPower `user_id`). Missing values fail with `missing user_id`.

Response 200 · Success envelope with the browser state, or a failure envelope (missing `user_id`).

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "Active",
    "lifecycle": "running",
    "ws": {
      "puppeteer": "ws://127.0.0.1:53211/devtools/browser/0f2c6d1e-example",
      "selenium": ""
    }
  }
}

POST/api/v2/browser-profile/delete-cache

Clear a profile's disk caches

Trims the on-disk browser caches of the given profiles so user-data directories do not grow without bound. Compatibility clients fire-and-forget this after each session with `type: ["image_file"]`; `type` is accepted and ignored. Always returns `code: 0`; a missing or malformed body clears nothing.

Request body · required

Request body fields
Field	Type	Required	Description
`profile_id`	string \| string[]	Yes	One profile id or a list of ids.
`type`	string[]	No	AdsPower cache categories such as `image_file`. Accepted for compatibility and ignored; AliasMode clears its disk caches.

{
  "profile_id": [
    "k1d0cd11"
  ],
  "type": [
    "image_file"
  ]
}

Response 200 · Always `code: 0` with empty `data`.

{
  "code": 0,
  "msg": "success",
  "data": {}
}

GET/api/v1/browser/cookies

Read cookies from a running browser (AliasMode extension)

AliasMode extension to the AdsPower API. Reads cookies through Playwright's `context.cookies()` for the given URLs. The profile's browser must be safely running; otherwise the call fails with `profile not safely running: <id>` or `profile not running: <id>`. Cookie values are session credentials; handle the response accordingly.

Parameters
Name	In	Type	Required	Description
`user_id`	query	string	Yes	AliasMode profile id (AdsPower `user_id`). Missing values fail with `missing user_id`.
`urls`	query	string	No	Comma-separated list of URLs whose cookies to return. Defaults to `https://x.com,https://twitter.com`.

Response 200 · Success envelope with the cookie list, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {
    "cookies": [
      {
        "name": "auth_token",
        "value": "REDACTED_EXAMPLE_VALUE",
        "domain": ".x.com",
        "path": "/",
        "httpOnly": true,
        "secure": true,
        "expires": 4070908800,
        "sameSite": "None"
      }
    ]
  }
}

Profile groups. AliasMode has no group ids, so the id equals the name.

GET/api/v1/group/list

List profile groups

Returns one page of group names. `group_id` equals `group_name` because AliasMode has no separate group ids. AdsPower's ungrouped id `"0"` maps to `""` and is never listed. Empty groups registered with `groupCreate` are included.

Parameters
Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number. Non-positive or non-numeric values fall back to 1.
`page_size`	query	integer	No	Rows per page. Non-positive or non-numeric values fall back to 100.

Response 200 · Always `code: 0`.

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "group_id": "research",
        "group_name": "research"
      }
    ],
    "page": 1,
    "page_size": 100
  }
}

POST/api/v1/group/create

Create a profile group

Registers a group so it lists before its first profile exists. Idempotent: the returned `group_id` equals the trimmed `group_name`. Fails with `invalid JSON body` or `missing group_name`.

Request body · required

Request body fields
Field	Type	Required	Description
`group_name`	string	Yes	Group name; surrounding whitespace is trimmed.

{
  "group_name": "research"
}

Response 200 · Success envelope with the group id, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {
    "group_id": "research"
  }
}

user

Profile management in AdsPower's `user` vocabulary. A `user_id` is an AliasMode profile id.

GET/api/v1/user/list

List profiles

Returns one page of profiles in AdsPower's row shape. Filter with `group_id` (`"0"` or `""` selects ungrouped profiles). Sort with `user_sort`. Timestamps are Unix seconds; `0` means unknown or never opened. `fp_verdict` and `fp_captured_at` are AliasMode additions: the fingerprint attestation verdict and capture time, or `""` when no attestation exists.

Parameters
Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number. Non-positive or non-numeric values fall back to 1.
`page_size`	query	integer	No	Rows per page. Non-positive or non-numeric values fall back to 100.
`group_id`	query	string	No	Only profiles in this group. `0` or an empty string selects ungrouped profiles.
`user_sort`	query	string	No	JSON object with one key, `created_time` or `last_open_time`, whose value is `asc` or `desc`. Malformed JSON keeps insertion order.

Response 200 · Always `code: 0`.

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "user_id": "k1d0cd11",
        "name": "research-01",
        "group_id": "research",
        "serial_number": "1",
        "created_time": 1767225600,
        "last_open_time": 0,
        "fp_verdict": "",
        "fp_captured_at": ""
      }
    ],
    "page": 1,
    "page_size": 100
  }
}

POST/api/v1/user/create

Create a profile

Creates an AliasMode profile from an AdsPower-shaped payload. A blank `name` is replaced by the generated profile id. `group_id` `"0"` means ungrouped. `fingerprint_config.screen_resolution` uses AdsPower's `WIDTH_HEIGHT` form; omit it for a realistic random resolution. When a proxy is given, the browser timezone is matched to the proxy's location on a best-effort basis. Fails with `invalid JSON body` or the validation error.

Request body · required

Request body fields
Field	Type	Required	Description
`name`	string	No	Profile name. Blank names become the generated id.
`group_id`	string	No	Group name. `0` or empty means ungrouped.
`domain_name`	string	No	Platform the account belongs to, for example `x.com`.
`username`	string	No
`password`	string	No
`email`	string	No
`email_password`	string	No
`emailPassword`	string	No	Alias of `email_password`.
`fakey`	string	No	TOTP secret for two-factor login.
`twofa`	string	No	Alias of `fakey`.
`user_proxy_config`	object	No	AdsPower `user_proxy_config`. Ignored unless `proxy_host` is a non-empty string.
`fingerprint_config`	object	No

{
  "name": "research-01",
  "group_id": "research",
  "domain_name": "x.com",
  "username": "example_user",
  "password": "EXAMPLE_PASSWORD",
  "email": "user@example.com",
  "email_password": "EXAMPLE_EMAIL_PASSWORD",
  "fakey": "EXAMPLE_TOTP_SECRET",
  "user_proxy_config": {
    "proxy_type": "http",
    "proxy_host": "proxy.example.com",
    "proxy_port": "8080",
    "proxy_user": "proxy_user",
    "proxy_password": "EXAMPLE_PROXY_PASSWORD"
  },
  "fingerprint_config": {
    "screen_resolution": "1920_1080"
  }
}

Response 200 · Success envelope with the new profile id, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "k1d0cd11"
  }
}

POST/api/v1/user/delete

Delete profiles

Stops each profile's browser, removes its browser data, and deletes the profile. Unknown ids are skipped. Profiles whose browser could not be stopped are left in place and returned in `locked`. Fails only with `invalid JSON body`.

Request body · required

Request body fields
Field	Type	Required	Description
`user_ids`	string[]	Yes	Profile ids to delete. A non-array value deletes nothing.

{
  "user_ids": [
    "k1d0cd11",
    "k1d0cd12"
  ]
}

Response 200 · Success envelope with counts, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {
    "deleted": 1,
    "locked": [
      "k1d0cd12"
    ]
  }
}

POST/api/v1/user/update

Rename a profile and update its saved credentials

`name` is required and replaces the profile name. Credential fields are applied only when present as strings. Fails with `invalid JSON body`, `missing user_id`, `name must be a non-empty string`, `no such profile: <id>`, or `failed to persist profile update: <reason>`.

Request body · required

Request body fields
Field	Type	Required	Description
`user_id`	string	Yes
`name`	string	Yes	New profile name. Required and non-empty.
`username`	string	No
`password`	string	No
`email`	string	No
`email_password`	string	No
`emailPassword`	string	No	Alias of `email_password`.
`fakey`	string	No	TOTP secret for two-factor login.
`twofa`	string	No	Alias of `fakey`.

{
  "user_id": "k1d0cd11",
  "name": "research-01-renamed",
  "username": "example_user"
}

Response 200 · Success envelope with empty `data`, or a failure envelope.

{
  "code": 0,
  "msg": "success",
  "data": {}
}