Local API V2 User Guide

Local API V2 is called in the same way as V1: first confirm the local port and Local API Key, then send an HTTP request to the endpoint.

All V2 endpoint paths begin with /openapi/v2, such as /openapi/v2/profiles, /openapi/v2/proxies, and /openapi/v2/fingerprints.

Base URL

The Local API service runs on a local port. The full request URL uses the following format:

http://127.0.0.1:{port}/openapi/v2/...

Example:

GET http://127.0.0.1:52100/openapi/v2/profiles

{port} is the Local API port displayed or configured in the client. Replace the port, Profile ID, Proxy ID, and API Key in the examples with your actual values.

Request Headers

Name	Type	Required	Description
X-API-KEY	string	Yes	Local API Key.
Content-Type	string	Recommended for request body	Must be application/json.
X-Token	string	No	Optional authentication header. Usually not required.

Notes:

• Use X-API-KEY to call the API.
• Send valid JSON to endpoints that accept a request body.
• If any parameter is invalid, the corresponding error message is returned.

Response Format

V2 uses a standard response envelope:

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

Name	Type	Description
code	integer	Business status code. 0 indicates success.
msg	string/null	Response message.
data	object/null	Response data. The structure varies by endpoint.
next	string/null	Cursor for the next page. null if there are no more pages.

Common errors:

HTTP	code	Description
401	401000	The X-API-KEY header is missing.
403	401000	X-API-KEY does not match the local configuration.
429	429000	Too many requests.
502	502000	The service is temporarily unavailable.
502	502001	The service returned an invalid response.
504	504000	The request timed out.

Pagination

Some list endpoints support two pagination methods:

Method	Parameters	Description
Page-based	page, page_size	page starts at 1.
Cursor-based	cursor, limit	Omit cursor in the first request; use next from the response for the next page.

page/page_size and cursor/limit are mutually exclusive. Do not use them together.

Example paginated list response:

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [],
    "total": 0,
    "summary": null
  },
  "next": null
}

API Coverage

Local API V2 currently provides 72 endpoints:

Module	Count	Description
Runtime	9	Service status, version, health, rate limits, sessions, stopping all Profiles, and available kernels.
Profiles	19	Create, read, update, and delete Profiles; manage accounts, groups, Proxy bindings, and start/stop actions.
Extensions and Bookmarks	8	Profile Bookmarks, Profile Extension settings, Extension installation, Extension lists, and Extension groups.
Tags	6	Create, read, update, and delete Tags; add Tags to or remove Tags from Profiles.
Profile Groups	5	Create, read, update, and delete Profile Groups.
Members and Permissions	8	Create, read, update, and delete Members; manage accessible Profile Groups, Member Groups, and permissions.
Proxies	7	Create, read, update, and delete Proxies; test Proxies.
Cookie	4	Query, import, and clear Cookies.
Fingerprints	6	Query, override, refresh, and generate Fingerprints; query Fingerprint options.

Module Documentation

Module	Endpoints	Documentation
Runtime	9	View Runtime endpoints
Profiles	19	View Profile endpoints
Extensions and Bookmarks	8	View Extension and Bookmark endpoints
Tags	6	View Tag endpoints
Profile Groups	5	View Profile Group endpoints
Members and Permissions	8	View Member and permission endpoints
Proxies	7	View Proxy endpoints
Cookie	4	View Cookie endpoints
Fingerprints	6	View Fingerprint endpoints

Usage Notes

• Every V2 endpoint path must include /openapi/v2.
• Every request must include a valid X-API-KEY.
• For endpoints with a request body, send JSON and set Content-Type: application/json.
• For create, update, and import endpoints, test with a small data set before making bulk requests.
• After a Profile starts successfully, use debug_port or web_socket_url from the response to connect to the browser.
• If you receive a 429 response, reduce the request rate and refer to the Retry-After and X-RateLimit-* response headers.