Local API

App desktop chạy sẵn một HTTP API ngay trên máy bạn, để script của bạn liệt kê profile, mở profile kèm endpoint CDP, và chạy workflow.

26 endpoint

Base URL

Server chỉ lắng nghe trên loopback, nên chỉ gọi được từ chính máy đang chạy app, không nơi nào khác. Cổng lấy từ LOCAL_API_PORT, mặc định 3030.

http://127.0.0.1:3030

Xác thực

Mọi endpoint trừ /health và /status đều cần API token đặt trong header X-Token. Token được tạo trong tài khoản của bạn chứ không phải trong app.

Ví dụ request

curl http://127.0.0.1:3030/profiles \
  -H "X-Token: <your api token>"

Token được xác thực với cloud rồi cache lại. Nếu cloud không truy cập được, app dùng kết quả đã cache trong tối đa một ngày, nên script vẫn chạy qua được những lúc mạng chập chờn.

Phân quyền

Mỗi token mang một bộ quyền theo nhóm — profiles, workspaces, instant_profiles và rpa — và mỗi endpoint bên dưới đều ghi rõ nó kiểm tra quyền nào.

Quyền rộng bao luôn các phép kiểm tra hẹp nằm trong nó: delete thỏa mãn cả write và read. Các quyền thao tác thì độc lập — start không kéo theo stop, và read không kéo theo cả hai — nên cần quyền nào thì cấp đúng quyền đó.

Endpoint yêu cầu	Thỏa mãn bởi bất kỳ quyền nào trong
`read`	`readwritedelete`
`write`	`writedelete`
`delete`	`delete`
`start`	`start`
`stop`	`stop`
`execute`	`execute`
`logs`	`logs`
`create`	`create`
`connect`	`connectcontrol`
`control`	`control`

Giới hạn tốc độ

Giới hạn được đếm theo từng token trong cửa sổ một phút trượt, mỗi nhóm route có mức riêng.

default100 request/phút
profile60 request/phút
rpa60 request/phút
strict10 request/phút

Mọi response đều kèm hạn mức hiện tại

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Lỗi

Khi thất bại, response trả success: false kèm error cho người đọc và code cho máy đọc.

{ "success": false, "error": "Missing X-Token header", "code": "UNAUTHORIZED" }
{ "success": false, "error": "Permission denied: profiles.start", "code": "FORBIDDEN" }
{ "success": false, "error": "Too many requests", "code": "RATE_LIMIT_EXCEEDED", "retryAfter": 42 }

Sức khỏe và trạng thái

Các endpoint nhẹ để kiểm tra app còn sống không và còn kết nối được tới cloud không.

GET/health

Local API có đang chạy không

Gọi được mà không cần token — endpoint này nằm trước middleware xác thực.

Quyền: không cầnGiới hạn: 100 request/phút

200 OK

{ "status": "ok", "timestamp": 1787553311344 }

GET/status

Kết nối cloud và lần đồng bộ gần nhất

Gọi được mà không cần token — endpoint này nằm trước middleware xác thực.

Quyền: không cầnGiới hạn: 100 request/phút

200 OK — lastSync là mốc mới nhất trong profile, workflow và workspace

{ "online": true, "lastSync": 1787553311344, "timestamp": 1787553311999 }

GET/list

Các profile đang chạy

Quyền: không cầnGiới hạn: 100 request/phút

200 OK

{
  "success": true,
  "data": [{ "profile_id": "abc", "port": 19001, "status": "RUNNING" }]
}

GET/stats

Cache, hàng đợi đồng bộ và số lượng đang chạy

Quyền: không cầnGiới hạn: 100 request/phút

Profile

Bật/tắt các profile đã đồng bộ từ tài khoản. Bật một profile sẽ trả về endpoint CDP để bạn điều khiển bằng Puppeteer hoặc Playwright.

GET/profiles

Liệt kê profile trong cache

Đọc từ cache cục bộ. Nếu cache rỗng thì đồng bộ từ cloud trước, nên lần gọi đầu sau khi mở app sẽ chậm hơn.

Quyền: profiles.readGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`workspace_id`	query	string	Chỉ trả về profile thuộc workspace này.

GET/profiles/sync

Buộc đồng bộ lại từ cloud

Quyền: profiles.readGiới hạn: 60 request/phút

GET/profiles/:profileId

Lấy một profile từ cache

Quyền: profiles.readGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`profileId`bắt buộc	path	string	ID của profile.

POST/profiles/:profileId/start

Mở trình duyệt của profile

Trả về URL CDP để thư viện tự động hóa kết nối vào. Không truyền port thì app tự chọn cổng trống trong khoảng 19000-19999. Profile phải có sẵn trong cache — chưa đồng bộ thì trả 404.

Quyền: profiles.startGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`profileId`bắt buộc	path	string	ID của profile.
`port`	query	number	Cổng debug muốn dùng, từ 1 đến 65535.

200 OK

{
  "success": true,
  "data": {
    "profile_id": "abc",
    "port": 19001,
    "cdp_url": "http://127.0.0.1:19001"
  }
}

POST/profiles/:profileId/stop

Đóng trình duyệt của profile

Quyền: profiles.stopGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`profileId`bắt buộc	path	string	ID của profile.

GET/profiles/:profileId/status

Đang chạy hay đã dừng

Quyền: profiles.readGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`profileId`bắt buộc	path	string	ID của profile.

Profile tức thời

Profile dùng một lần, tạo ngay tại chỗ và không lưu vào tài khoản. Nhóm này bị giới hạn tốc độ chặt nhất.

POST/instant

Tạo và mở một profile dùng một lần

Quyền: instant_profiles.createGiới hạn: 10 request/phút

Tên	Vị trí	Kiểu	Mô tả
`fingerprint`	body	object	Gợi ý fingerprint, ví dụ os và version.
`proxy_id`	body	string	Proxy trong tài khoản dùng cho profile này.

200 OK

{
  "success": true,
  "data": { "profile_id": "instant_…", "port": 19002, "cdp_url": "http://127.0.0.1:19002" }
}

DELETE/instant/:profileId

Đóng và hủy một profile tức thời

Quyền: instant_profiles.deleteGiới hạn: 10 request/phút

Tên	Vị trí	Kiểu	Mô tả
`profileId`bắt buộc	path	string	ID của profile.

GET/instant/:profileId

Lấy một profile tức thời

Quyền: không cầnGiới hạn: 10 request/phút

Tên	Vị trí	Kiểu	Mô tả
`profileId`bắt buộc	path	string	ID của profile.

GET/instant

Tất cả profile tức thời đang sống

Quyền: không cầnGiới hạn: 10 request/phút

RPA

Chạy các workflow bạn dựng trên canvas, trên profile đã lưu hoặc trên profile tức thời, và theo dõi task trong lúc chạy.

GET/rpa/workflows

Liệt kê workflow

Quyền: rpa.readGiới hạn: 60 request/phút

GET/rpa/workflows/:workflowId

Một workflow, kèm sơ đồ của nó

Quyền: rpa.readGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`workflowId`bắt buộc	path	string	ID của workflow.

POST/rpa/workflows/sync

Buộc đồng bộ lại workflow

Quyền: rpa.readGiới hạn: 60 request/phút

POST/rpa/tasks

Chạy workflow trên một profile

Quyền: rpa.executeGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`workflow_id`bắt buộc	body	string	Workflow cần chạy.
`profile_id`bắt buộc	body	string	Profile dùng để chạy.

400 nếu thiếu một trong hai trường

{
  "success": false,
  "error": "workflow_id and profile_id are required in request body"
}

POST/rpa/tasks/instant

Chạy workflow trên profile tức thời mới

Tự tạo profile, chạy workflow trên đó, không cần truyền profile_id.

Quyền: rpa.executeGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`workflow_id`bắt buộc	body	string	Workflow cần chạy.
`profile_config`	body	object	Cấu trúc giống body của endpoint tạo profile tức thời.

GET/rpa/tasks

Liệt kê task

Quyền: rpa.readGiới hạn: 60 request/phút

GET/rpa/tasks/:taskId

Một task và trạng thái của nó

Quyền: rpa.readGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`taskId`bắt buộc	path	string	ID của task.

POST/rpa/tasks/:taskId/stop

Dừng một task đang chạy

Quyền: rpa.stopGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`taskId`bắt buộc	path	string	ID của task.

GET/rpa/tasks/:taskId/logs

Log của một task

Quyền: rpa.logsGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`taskId`bắt buộc	path	string	ID của task.

Workspace

Xem (chỉ đọc) các workspace mà profile được gom vào.

GET/workspaces

Liệt kê workspace

Quyền: workspaces.readGiới hạn: 60 request/phút

GET/workspaces/sync

Buộc đồng bộ lại workspace

Quyền: workspaces.readGiới hạn: 60 request/phút

GET/workspaces/:workspaceId

Lấy một workspace

Quyền: workspaces.readGiới hạn: 60 request/phút

Tên	Vị trí	Kiểu	Mô tả
`workspaceId`bắt buộc	path	string	ID của workspace.