Local API

Local API cho phép công cụ của bạn liệt kê và mở hồ sơ, chạy quy trình và đọc kết quả. Đây là máy chủ HTTP bên trong ứng dụng, chỉ lắng nghe trên 127.0.0.1: không gì bên ngoài máy này truy cập được.

Bật Local API

1. Mở Cài đặt → API & MCP.
2. Bật Local API. Cổng mặc định là 50325.
3. Tạo khóa API: đặt tên và chọn phạm vi quyền. Khóa (mzb_…) chỉ hiện một lần; MZBase chỉ giữ mã băm của nó.

Phạm vi quyền

Phạm vi	Cho phép
read	mọi route GET
write	tạo, sửa và xóa hồ sơ; đặt trạng thái tài khoản
control	mở và dừng hồ sơ; kiểm tra và đổi IP proxy
run	bắt đầu và hủy lượt chạy quy trình
cdp	nhận endpoint DevTools của trình duyệt khi hồ sơ mở; công cụ thao tác trang qua MCP

Mỗi khóa có thể có giới hạn tốc độ mỗi phút và số lượt chạy song song tối đa. Lời gọi thiếu phạm vi cần thiết trả về 403 API_SCOPE_DENIED.

Mọi lời gọi đã xác thực được ghi vào nhật ký API (route và query, không bao giờ có nội dung body hay bí mật), giữ 90 ngày.

Gọi API

Gửi khóa dưới dạng bearer token:

curl -H "Authorization: Bearer $MZB_KEY" http://127.0.0.1:50325/profiles

GET /health không cần khóa và trả về { "status": "ok" }.

Yêu cầu và phản hồi là JSON với tên trường camelCase. Lỗi dùng một định dạng chung:

{ "error": { "code": "PROFILE_NOT_FOUND", "message": "…", "details": {} } }

Các route

Method	Đường dẫn	Chức năng
GET	/health	Kiểm tra sống, không cần khóa
GET	/profiles?search=&folderId=&tag=	Liệt kê hồ sơ
POST	/profiles	Tạo hồ sơ
GET	/profiles/{id}	Một hồ sơ
PATCH	/profiles/{id}	Cập nhật hồ sơ
DELETE	/profiles/{id}	Chuyển hồ sơ đang đóng vào Thùng rác
POST	/profiles/{id}/start	Mở hồ sơ; trả về endpoint DevTools khi có phạm vi cdp
POST	/profiles/{id}/stop	Đóng hồ sơ
GET	/profiles/{id}/status	Trạng thái chạy
GET	/proxies	Liệt kê proxy (không bao giờ có mật khẩu)
POST	/proxies/{id}/check	Kiểm tra lại proxy
POST	/proxies/{id}/change-ip	Yêu cầu nhà cung cấp cấp IP mới
GET	/accounts	Liệt kê tài khoản (không có mật khẩu hay seed 2FA)
POST	/accounts/status	Đặt trạng thái tài khoản
GET	/workflows	Liệt kê quy trình
POST	/workflows/run	Chạy quy trình: { "workflow": "<id hoặc tên>", "profileIds": ["…"], "inputs": {} }
GET	/workflows/runs/{id}	Một lượt chạy và trạng thái
GET	/tools	Các công cụ năng lực khóa của bạn được dùng
POST	/tools/{name}/run	Chạy một công cụ năng lực với đầu vào JSON
POST	/mcp	Máy chủ MCP (bên dưới)

Điều khiển trình duyệt

Với phạm vi cdp, POST /profiles/{id}/start trả về:

{
  "cdpPort": 9231,
  "wsEndpoint": "ws://127.0.0.1:9231/<token>/devtools/browser/default",
  "cdpUrl": "http://127.0.0.1:9231/<token>"
}

Bản thân trình duyệt không mở cổng DevTools: MZBase phục vụ endpoint của từng hồ sơ trên một cổng nối cục bộ, dưới một token ngẫu nhiên cho mỗi lần mở. Yêu cầu từ trang web (có header Origin) và từ máy khác bị từ chối.

Kết nối thư viện tự động hóa của bạn tới cdpUrl hoặc wsEndpoint, ví dụ chromium.connectOverCDP(cdpUrl) của Playwright hoặc puppeteer.connect({ browserWSEndpoint: wsEndpoint }) của Puppeteer. Lưu ý: thư viện kết nối theo cách này có thể bật các tín hiệu trình duyệt mà trang web phát hiện được; các node của MZBase và node Browser script dùng trình điều khiển ẩn danh thay vào đó (xem Quy trình).

Lệnh mzb

Terminal mở trong trang Terminal của MZBase đã có mzb trên PATH, kèm token phiên cho ứng dụng này. Ví dụ:

mzb profile list --search shop
mzb profile start "Shop · US 01"
mzb run "Daily check-in" --profile "Shop · US 01" --wait
mzb proxy change-ip "US residential 3"
mzb tool list

Dùng tên hoặc id ở mọi nơi; --json in JSON của API. Mã thoát: 0 thành công, 1 ứng dụng trả lỗi, 2 sai cú pháp, 3 không ở trong terminal MZBase hoặc không kết nối được ứng dụng.

MCP

POST /mcp là máy chủ MCP (streamable HTTP) với cùng bearer key. Ứng dụng AI chỉ thấy các công cụ mà phạm vi của khóa cho phép: hồ sơ, tài khoản, quy trình, execution, lượt chạy, chụp và click trang, và mọi công cụ năng lực. Các công cụ chạy quy trình hoặc thay đổi nhiều tài khoản có thể cần bạn duyệt trong ứng dụng trước khi chạy.

Với ứng dụng MCP chỉ hỗ trợ stdio, trỏ chúng tới chương trình mzbase-mcp được cài cạnh ứng dụng, với khóa trong MZBASE_API_KEY.