Local API

AdsPower Local API — REST API Layer

Knowledge base section 01. Covers the Local API (REST endpoints), authentication, rate limits, and the complete endpoint catalog. Source: AdsPower help page (api.txt) + Postman API reference (https://documenter.getpostman.com/view/45822952/2sB34hEzQH)

---

1. Overview

The AdsPower Local API is a REST HTTP API running on the user’s device (the machine where the AdsPower client is running). It allows you to:

1. Read and write browser profile configuration (create, update, delete, list profiles).
2. Start and close browser profiles programmatically.
3. Manage groups, tags, proxies, and extensions.
4. Connect automation frameworks (Selenium, Puppeteer) to opened browser profiles via the WebSocket/Debug Port returned by the start endpoint.

The API is the foundation for programmatic multi-profile management — the REST layer manages profile lifecycle, while browser automation (clicking, typing, navigating) is handled via Selenium/Puppeteer connecting to the debug port, or via the MCP server / RPA layer (covered in their respective KB sections).

---

2. Authentication

Bearer Token (API Key)

Item	Value
Auth method	Bearer Token
Token source	API Key generated in AdsPower client (Automation → API)
Postman variable	API_TOKEN (configured as collection-level Bearer Token)
Header format	Authorization: Bearer YOUR_API_TOKEN

API Key Generation

• Super admins have API access by default. Team members need the manager/admin to assign API permission.
• Go to Automation → API in the AdsPower client to check API connection status.
• Click Generate or Reset to get your API key.
• Each team member has a unique API key.

When API Key is Required

• CLI / Headless mode: API Key authentication is required for ALL calls.
• Security verification enabled: API Key authentication is required for ALL calls.
• In standard GUI mode with no security verification, the API may work without the key (but using it is best practice).

Key Reset Behavior

• Resetting the API key immediately invalidates the previous key.
• You must stop the service first, then restart with the new key — you cannot update the key while the service is running.

---

3. Base URL and Port

Item	Value
Default address	http://local.adspower.net or http://localhost
Default port	50325
Full base URL	http://localhost:50325

Both addresses resolve to the same local API service. Use localhost for scripts running on the same machine; use local.adspower.net if you need a hostname that works across network configurations.

---

4. Headless Mode

AdsPower can run in headless mode (no GUI), which is required for server/VPS deployments and automated workflows.

Requirements

• AdsPower version v3.3.2 or above
• Kernel version v2.4.2.8 or above
• API access permission

Start Commands

OS	Command
Windows	"AdsPower Global.exe" --headless=true --api-key=XXXX --api-port=50325
macOS	"/Applications/AdsPower Global.app/Contents/MacOS/AdsPower Global" --args --headless=true --api-key=XXXX --api-port=50325
Linux	adspower_global --headless=true --api-key=XXXX --api-port=50325

Flags

Flag	Required	Description
--headless	Yes	Runs browser in headless mode (true)
--api-key	Yes	Credential to use Local API in headless mode
--api-port	No	Specified port for Local API (default: 50325)

Key Differences: Headless vs GUI

• GUI mode: One account can log in on only one device at a time.
• Headless (API-key) mode: One account can log in on multiple devices simultaneously — enables distributed automation across multiple machines for one AdsPower account.

Stopping Headless Service

• Press Ctrl+C (under CMD/Terminal) or close the command line window.
• You cannot run GUI mode and headless mode simultaneously on the same device.

---

5. Rate Limits

Standard Rate Limits (by profile count)

Number of Profiles	Request Limit
0 – 200	2 requests per second
200 – 5000	5 requests per second
5000+	10 requests per second

The profile count is based on the total profiles in your AdsPower account, not the number of profiles being operated on.

Special-Rate Endpoints (fixed 1 req/sec)

These endpoints always have a fixed rate limit of 1 request per second, regardless of your profile count:

Endpoint
GET /api/v1/user/list
POST /api/v2/browser-profile/list
GET /api/v1/group/list
GET /api/v2/browser-profile/cookies
POST /api/v2/browser-profile/download-kernel

Practical note for Reddit workflow: The profile list endpoint (/api/v2/browser-profile/list) is rate-limited to 1 req/sec. When polling profile status at scale, use the active-status endpoints (/api/v1/browser/active or /api/v2/browser-profile/active) instead, which follow the standard rate limit.

---

6. Complete Endpoint Catalog

6.1 Connection Status

Method	Endpoint	Name	Description
GET	/status	Connection Status	Check API availability. Returns {"code":0,"msg":"success"}

6.2 Profiles (29 endpoints)

Profile Lifecycle (Open / Close / Status)

Method	Endpoint	Name	Key Params
GET	/api/v1/browser/start	Open Profile	user_id, serial_number, open_tabs, ip_tab, launch_args, headless, disable_password_filling, clear_cache_after_closing, enable_password_saving, cdp_mask, device_scale
POST	/api/v2/browser-profile/start	Open Profile v2	profile_id, profile_no, launch_args, headless, last_opened_tabs, proxy_detection, password_filling, password_saving, cdp_mask, device_scale, delete_cache
GET	/api/v1/browser/stop	Close Profile	user_id, serial_number
POST	/api/v2/browser-profile/stop	Close Profile v2	profile_id, profile_no
GET	/api/v1/browser/active	Check Profile Status	user_id, serial_number — returns Active/Inactive status
GET	/api/v2/browser-profile/active	Check Profile Status v2	profile_id, profile_no — returns status + ws/selenium debug info
GET	/api/v1/browser/active-local	Check startup status (current device)	—
GET	/api/v2/browser-profile/active-local	Check startup status (current device) v2	—
POST	/api/v2/browser-profile/active-cross	Check Profile Status (cross-devices)	Cross-device profile status check
GET	/api/v1/browser/active-list	Query Active Profile	List all currently active/open profiles

Profile CRUD

Method	Endpoint	Name	Key Params
GET	/api/v1/user/list	Query Profile	page, page_size — legacy v1 list
POST	/api/v2/browser-profile/list	Query Profile v2	profile_id[], profile_no[], group_id, limit, page, sort_type, sort_order, tag_ids, tags_filter, name, name_filter
POST	/api/v1/user/create	New Profile	name, domain_name, username, password, fakey, cookie, group_id, user_proxy_config/proxyid, fingerprint_config, country, remark, etc.
POST	/api/v2/browser-profile/create	New Profile v2	name, group_id, remark, platform, username, password, fakey, platform_account[], cookie, repeat_config, ignore_cookie_error, tabs, user_proxy_config/proxyid, ip, country, region, city, ipchecker, fingerprint_config, category_id
POST	/api/v1/user/update	Update Profile	Same as create + user_id (profile ID)
POST	/api/v2/browser-profile/update	Update Profile v2	Same as create v2 + profile_id
POST	/api/v1/user/delete	Delete Profile	user_ids[] (max 100 per request)
POST	/api/v2/browser-profile/delete	Delete Profile v2	profile_id[]

Profile Management

Method	Endpoint	Name	Key Params
POST	/api/v1/user/move	Move Profile	group_id, user_ids[] — move profiles to a group
POST	/api/v1/user/delete-cache	Delete Cache	user_id — legacy v1
POST	/api/v2/browser-profile/clear-cache	Delete Cache v2	profile_id[], type[] (local_storage, indexeddb, extension_cache, cookie, history, image_file)
POST	/api/v1/share	Share Profile	user_ids[], receiver (email), share_type, content
GET	/api/v1/user/profile-cookies	Query Profile Cookies	user_id / serial_number — fixed 1 req/sec rate limit
POST	/api/v2/browser-profile/cookies	Query Profile Cookies v2	profile_id / profile_no — fixed 1 req/sec rate limit
POST	/api/v1/user/profile-ua	Query Profile User-Agent	user_id[] / serial_number[] (up to 10)
POST	/api/v1/browser/stop-all	Close All Profiles	No params — closes all open profiles on current device
POST	/api/v1/user/new-fingerprint	New Fingerprint	user_id[] / serial_number[] (up to 10) — regenerate fingerprint for existing profile

Kernel & Patch

Method	Endpoint	Name	Key Params
GET	/api/v1/kernel/list	Get Kernel List	kernel_type (Chrome/Firefox)
POST	/api/v2/browser-profile/download-kernel	Download Kernel	kernel_type, kernel_version — fixed 1 req/sec rate limit
POST	/api/v1/client/upgrade	Update to Latest Patch	version_type (stable/beta)

6.3 Tags (4 endpoints)

Method	Endpoint	Name	Key Params
POST	/api/v2/browser-tags/create	Create Tag	tags[] with name (required, max 50 chars), color (optional: darkBlue, blue, purple, red, yellow, orange, green, lightGreen)
POST	/api/v2/browser-tags/update	Update Tag	tags[] with id (required), name, color
POST	/api/v2/browser-tags/delete	Delete Tag	ids[] (required, max 100 per request)
POST	/api/v2/browser-tags/list	Query Tag	ids[], limit, page

6.4 Groups (3 endpoints)

Method	Endpoint	Name	Key Params
GET	/api/v1/group/list	Query Group	group_name, page, page_size (1-200) — fixed 1 req/sec rate limit
POST	/api/v1/group/create	New Group	group_name (required, max 30 chars, unique), remark (max 100 chars)
POST	/api/v1/group/update	Update Group	group_id (required), group_name (required, max 30 chars, unique), remark

6.5 Proxies (4 endpoints)

Method	Endpoint	Name	Key Params
GET	/api/v2/proxy-list/create	Create Proxy	type (http/https/ssh/socks5), host, port, user, password, proxy_url, ipchecker, remark — max 500 per request
POST	/api/v2/proxy-list/update	Update Proxy	proxy_id (required), type, host, port, user, password, proxy_url, ipchecker, remark
POST	/api/v2/proxy-list/list	Query Proxy	proxy_id[] (max 100), limit (1-200), page
POST	/api/v2/proxy-list/delete	Delete Proxy	proxy_id[] (max 100 per request)

6.6 Extensions (2 endpoints)

Method	Endpoint	Name	Key Params
GET	/api/v1/application/list	Category List	page (default 1), page_size (default 50, range 1-200)
GET	/api/v2/category/list	Category List v2	category_id, limit (1-200), page

---

7. v1 vs v2 Differences

Aspect	v1	v2
ID parameter name	user_id, serial_number	profile_id, profile_no
HTTP method for create/list	GET (query) / POST (create)	POST (both)
List endpoint	GET /api/v1/user/list (fixed 1 req/sec)	POST /api/v2/browser-profile/list (fixed 1 req/sec, richer filtering)
Open Profile params	open_tabs, ip_tab, new_first_tab, disable_password_filling, clear_cache_after_closing, enable_password_saving	last_opened_tabs, proxy_detection, password_filling, password_saving, delete_cache (renamed/restructured)
Create Profile	domain_name, open_urls	platform, platform_account[] (multi-account support), tabs
Multi-account platform	Not supported	Supported via platform_account[] array
Cache deletion	Single profile	Batch via profile_id[] + type[] (local_storage, indexeddb, extension_cache, cookie, history, image_file)
Cookie format query	GET /api/v1/user/profile-cookies	POST /api/v2/browser-profile/cookies

Recommendation: Use v2 endpoints wherever available. They have better filtering, multi-account platform support, batch operations, and are the actively maintained API surface.

---

8. Key Endpoint Deep-Dives

8.1 Open Profile v2 — POST /api/v2/browser-profile/start

This is the core endpoint for launching a browser profile. It returns the debug port and WebSocket endpoints needed for Selenium/Puppeteer automation.

Parameters:

Param	Type	Required	Default	Description
profile_id	string	Yes*	—	Unique profile ID
profile_no	string	No*	—	Profile serial number (used if profile_id empty)
launch_args	string[]	No	—	Chromium command-line switches, e.g. ["--disable-notifications"]
headless	string	No	0	1=headless, 0=GUI
last_opened_tabs	string	No	1	1=reopen last tabs, 0=no
proxy_detection	string	No	1	1=open IP detection page, 0=no
password_filling	string	No	0	1=fill password (first open only), 0=no
password_saving	string	No	0	1=allow password saving (Chrome only), 0=no
cdp_mask	string	No	1	1=mask CDP detection (forced on iOS/Android), 0=no
device_scale	string	No	—	Zoom ratio for mobile: 1=100%, range 0.1-2 (Chrome 128+, Android/iOS only)
delete_cache	string	No	0	1=clear cache on close, 0=no

*Either profile_id or profile_no must be provided — both cannot be empty.

Response (success):

{
    "code": 0,
    "msg": "success",
    "data": {
        "ws": {
            "puppeteer": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxxxx",
            "selenium": "127.0.0.1:xxxx"
        },
        "debug_port": "xxxx",
        "webdriver": "xxxxxxxxxxxx"
    }
}

The ws.puppeteer and ws.selenium values are the connection strings for browser automation frameworks. This is the bridge between the REST API (profile management) and the automation layer (browser actions).

8.2 New Profile v2 — POST /api/v2/browser-profile/create

Creates a new browser profile with full fingerprint, proxy, and platform account configuration.

Key Parameters:

Param	Type	Required	Description
name	string(100)	No	Profile name
group_id	string	Yes	Group ID (use 0 for ungrouped)
remark	string(1500)	No	Profile remarks
platform	string	No	Platform domain (e.g. reddit.com) — for single-account
username	string	No	Platform account username
password	string	No	Platform account password
fakey	string	No	2FA key
platform_account	array	No	Multi-account platform config (array of {domain_name, login_user, password, fakey})
cookie	string	No	Cookie data (Netscape or JSON format)
repeat_config	string	No	0=allow duplicates, 2=dedupe by account+password, 3=by cookies, 4=by c_user
ignore_cookie_error	string	No	0=return as-is, 1=filter invalid cookies
tabs	array(10)	No	URLs to open as tabs
user_proxy_config	object	No*	Inline proxy config (see Appendix)
proxyid	string	No*	Proxy ID from saved proxies (takes priority over user_proxy_config)
ip	string	No	IP address
country	string	No	Country code (2 letters, e.g. us)
region	string	No	Region
city	string	No	City
ipchecker	string	No	IP checker: ip2location/ipapi/ipfoxy
fingerprint_config	object	Yes	Fingerprint configuration (see Appendix)
category_id	string	No	Extension category ID

*Either user_proxy_config or proxyid must be provided for proxy configuration.

Minimal example for Reddit profile creation:

{
    "name": "Reddit-User-001",
    "group_id": "0",
    "platform": "reddit.com",
    "username": "reddit_user",
    "password": "***",
    "country": "us",
    "proxyid": "random",
    "fingerprint_config": {
        "automatic_timezone": "1",
        "webrtc": "disabled",
        "location": "ask",
        "location_switch": "1",
        "canvas": "1",
        "webgl": "3",
        "webgl_image": "1",
        "audio": "1",
        "browser_kernel_config": {
            "version": "ua_auto",
            "type": "chrome"
        }
    }
}

8.3 Query Profile v2 — POST /api/v2/browser-profile/list

Lists browser profiles with filtering. Rate limited to 1 req/sec.

Parameters:

Param	Type	Required	Default	Description
profile_id	array	No	—	Lookup by profile IDs
profile_no	array	No	—	Lookup by profile numbers
group_id	string	No	—	Filter by group
limit	integer	No	1	Items per page (1-1000)
page	integer	No	1	Page number
sort_type	string	No	profile_no	profile_no/last_open_time/created_time
sort_order	string	No	desc	asc/desc
tag_ids	array	No	—	Filter by tag IDs
tags_filter	string	No	include	include/exclude
name	string	No	—	Filter by profile name
name_filter	string	No	include	include/exclude

Response:

{
  "data": {
    "list": [
      {
        "name": "",
        "created_time": "1754534006",
        "ip": "xxx",
        "ip_country": "cn",
        "password": "***",
        "user_proxy_config": {"proxy_soft": "no_proxy"},
        "group_id": "xxx",
        "group_name": "xxx",
        "remark": "",
        "last_open_time": "0",
        "username": "1",
        "platform": "facebook.com",
        "category_id": "0",
        "profile_no": "xxx",
        "profile_id": "xxx"
      }
    ],
    "page": 1,
    "page_size": 1
  },
  "code": 0,
  "msg": "Success"
}

8.4 Check Profile Status v2 — GET /api/v2/browser-profile/active

Checks if a profile is currently open/active and returns automation connection info.

Parameters: profile_id (required) or profile_no (optional)

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
        "status": "Active",
        "ws": {
            "puppeteer": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxxxx",
            "selenium": "127.0.0.1:xxxx"
        },
        "debug_port": "xxxx",
        "webdriver": "xxxxxxxxxxxx"
    }
}

status is "Active" if the profile is open, "Inactive" otherwise. When Active, the ws and debug_port fields are populated for automation connections.

---

9. Appendix: Configuration Objects

9.1 user_proxy_config

Inline proxy configuration for create/update profile. Pass as JSON object.

Field	Type	Required	Description
proxy_soft	string	Yes	Proxy software: brightdata, brightauto, oxylabsauto, ipfoxyauto, kookauto, lumiproxyauto, ssh, other, adspowerauto, no_proxy
proxy_type	string	No	http, https, socks5 (not needed for no_proxy)
proxy_host	string	No	Proxy server address (IP or domain)
proxy_port	string	No	Proxy server port
proxy_user	string	No	Proxy username
proxy_password	string	No	Proxy password
proxy_url	string	No	IP change link (mobile proxies, http/https/socks5 only)
global_config	string	No	0=don’t use saved proxy, 1=use saved proxy account

Common configs:

Software	Example
no_proxy	{"proxy_soft":"no_proxy"}
other (custom)	{"proxy_soft":"other","proxy_type":"socks5","proxy_host":"xxxx","proxy_port":"xx","proxy_user":"xxx","proxy_password":"**"}
adspowerauto (rotating)	{"proxy_soft":"adspowerauto"}

9.2 fingerprint_config

Browser fingerprint configuration. Required for profile creation. Must be a non-empty JSON object.

Key fields (most relevant for Reddit workflow):

Field	Type	Default	Description
automatic_timezone	string	1	1=auto from IP, 0=custom
timezone	string	—	Custom timezone (e.g. America/New_York)
webrtc	string	disabled	forward/proxy/local/disabled — use disabled or proxy for anti-detect
location	string	ask	ask/allow/block
location_switch	string	1	1=from IP, 0=custom
language	array	["en-US","en"]	Browser languages (when language_switch=0)
language_switch	string	1	1=from IP, 0=custom
ua	string	—	Custom user-agent (leave empty for random)
screen_resolution	string	none	none/random/custom WIDTH_HEIGHT
canvas	string	1	1=noise, 0=default
webgl_image	string	1	1=noise, 0=default
webgl	string	3	0=default, 2=custom, 3=random
audio	string	1	1=noise, 0=off
hardware_concurrency	string	4	CPU cores: default/2/4/6/8/16
device_memory	string	8	RAM: default/2/4/6/8
browser_kernel_config	object	—	{"version":"ua_auto","type":"chrome"} or firefox
random_ua	object	—	{"ua_browser":["chrome"],"ua_version":["80"],"ua_system_version":["Windows 10"]}
mac_address_config	object	—	{"model":"1","address":""} (0=default, 1=match, 2=custom)
gpu	string	0	0=local setting, 1=on, 2=off
tls_switch	string	0	1=disable TLS features, 0=enable
scan_port_type	string	1	1=port scan protection on, 0=off

9.3 Country Codes

Two-letter country codes are used for the country parameter. Common ones for Reddit marketing:

Code	Country
us	United States
gb	Great Britain
ca	Canada
au	Australia
de	Germany
fr	France
nl	Netherlands
sg	Singapore

---

10. Reddit Multi-Profile Engagement Workflow — API Usage

The Local API is the programmatic foundation for managing Reddit profiles at scale. Here’s how the API maps to the Reddit engagement workflow:

Step 1: Prepare Proxies

POST /api/v2/proxy-list/create  →  Add residential/mobile proxies
GET  /api/v2/proxy-list/list    →  Get proxy_ids for profile creation

Step 2: Create Reddit Profiles

POST /api/v2/browser-profile/create  →  Create profile with:
  - group_id: assign to a Reddit group
  - platform: "reddit.com"
  - username/password: Reddit account credentials
  - proxyid: link to a saved proxy
  - fingerprint_config: randomized fingerprint
  - country: "us" (or target country)

Step 3: Open Profile for Automation

POST /api/v2/browser-profile/start  →  Returns:
  - ws.puppeteer (WebSocket URL for Puppeteer)
  - ws.selenium (host:port for Selenium)
  - debug_port
  - webdriver path

Step 4: Automate Reddit Actions

Connect Puppeteer/Selenium to the debug port returned by the start endpoint. The REST API does NOT handle browser actions (clicking, typing, scrolling) — that’s done via:

• Puppeteer/Selenium connecting to the ws/debug port
• MCP Server (Playwright-based, covered in KB section 03)
• RPA (visual automation, covered in KB section 02)

Step 5: Check Status & Close

GET  /api/v2/browser-profile/active  →  Check if profile is still open
POST /api/v2/browser-profile/stop    →  Close profile when done
POST /api/v2/browser-profile/stop-all →  Close all (emergency stop)

Step 6: Manage at Scale

POST /api/v2/browser-profile/list    →  List all Reddit profiles (filter by group_id)
POST /api/v2/browser-profile/update  →  Update proxy/fingerprint if needed
POST /api/v2/browser-profile/clear-cache  →  Clear cookies/history between sessions
POST /api/v2/browser-tags/create     →  Tag profiles (e.g. "active", "warming", "banned")
POST /api/v1/group/create            →  Create groups (e.g. "Reddit-Cluster-1")

Rate Limit Considerations

Operation	Endpoint	Rate Limit
Create profiles	/api/v2/browser-profile/create	Standard (2-10/sec)
List profiles	/api/v2/browser-profile/list	1 req/sec (fixed)
Open profiles	/api/v2/browser-profile/start	Standard (2-10/sec)
Check status	/api/v2/browser-profile/active	Standard (2-10/sec)
Close profiles	/api/v2/browser-profile/stop	Standard (2-10/sec)

With 0-200 profiles, you can open/close 2 profiles per second. For a 50-profile Reddit engagement campaign, opening all profiles takes ~25 seconds. Plan automation queues accordingly.

---

11. CLI Wrapper (adspower-browser)

The adspower-browser CLI (installed as Hermes skill adspower-browser) wraps all Local API endpoints into a command-line tool. It’s the primary interface for Hermes agents.

Key mappings:

CLI Command	API Endpoint
ads open-browser <id>	POST /api/v2/browser-profile/start
ads close-browser <id>	POST /api/v2/browser-profile/stop
ads create-browser '{json}'	POST /api/v2/browser-profile/create
ads get-browser-list '{}'	POST /api/v2/browser-profile/list
ads get-browser-active <id>	GET /api/v2/browser-profile/active
ads check-status	GET /status

The CLI handles authentication via --api-key flag or ADS_API_KEY env var, and default port via --port flag. See the adspower-browser skill for full CLI command reference.

Note: The CLI can manage profiles (create, open, close, list) but CANNOT perform browser automation (navigate, click, fill). For browser actions, use the MCP Server or RPA layer — covered in their respective KB sections.