REST API

Mọi thao tác có qua MCP đều có endpoint REST tương ứng. Cùng một registry, cùng quyền và cùng quy tắc.

#URL gốc và xác thực

• URL gốc: https://reach-link-craft.lovable.app/api/public/v1
• Khoá API: tạo khoá trong Cài đặt → Kết nối MCP / API → Tạo khoá API (bạn có thể đặt thời hạn). Gửi khoá như sau:

Authorization: Bearer xb_live_<id>_<secret>

Khoá hoạt động với vai trò hiện tại của người tạo. Hãy giữ bí mật: khoá chỉ hiển thị một lần.

Với n8n, dùng node HTTP Request với Header Auth (Name Authorization, Value Bearer <YOUR_KEY>); trong Make, dùng HTTP → Make a request; trong Zapier, dùng Webhooks by Zapier → Custom Request.

#Thao tác ghi cần khoá idempotency

Mọi thao tác ghi (loại X, W, D) đều cần header Idempotency-Key (hoặc idempotency_key trong nội dung yêu cầu): 8–128 ký tự thuộc A–Z a–z 0–9 . _ : -.

• Cùng khoá + cùng dữ liệu đầu vào → trả về kết quả đã lưu hoặc cùng một việc. Không có thao tác nào chạy hai lần.
• Cùng khoá + dữ liệu đầu vào khác → 409 idempotency_conflict.
• Lần gọi đầu tiên với khoá đó vẫn đang chạy → 409 idempotency_processing, thử lại sau 2 giây với cùng khoá.

Phạm vi của khoá được giới hạn theo kết nối.

#Cài đặt có phiên bản

Cài đặt có phiên bản yêu cầu bạn gửi phiên bản đã đọc: gửi If-Match: "<revision>" hoặc expected_revision trong nội dung yêu cầu. Phản hồi cho các đối tượng có phiên bản chứa ETag. Nếu phiên bản đã cũ, API trả về 412 revision_conflict cùng giá trị hiện tại — hãy hợp nhất thay đổi rồi thử lại.

#Việc và chờ kết quả

Thao tác đọc trực tiếp (L) và hành động trên X (X) tạo ra các việc. Yêu cầu chờ việc hoàn tất trong tối đa số giây chỉ định bằng ?wait= (0–20, mặc định 15).

• Hoàn tất trong thời gian chờ → 200 kèm kết quả.
• Vẫn đang trong hàng đợi, bị giữ hoặc đang chạy → 202 kèm Location: /api/public/v1/jobs/{job_id} và Retry-After: 2. Thăm dò bằng GET /jobs/{job_id} (yêu cầu này cũng có thể chờ tối đa 20 giây).
• POST /jobs/{job_id}/cancel huỷ việc đang trong hàng đợi hoặc bị giữ. Việc đang chạy sẽ được yêu cầu dừng và vẫn có thể kết thúc với trạng thái succeeded, cancelled hoặc unknown.

#Phản hồi và phân trang

Các phản hồi thành công dùng chung một cấu trúc bao ngoài:

{ "data": {}, "meta": { "request_id": "req_…", "operation": "account_list" }, "next_cursor": null, "has_more": false }

Danh sách trả về next_cursor; gửi lại giá trị này qua cursor để lấy trang tiếp theo. Mọi phản hồi đều có header X-Request-Id.

#Giới hạn tốc độ

600 lượt gọi mỗi phút cho mỗi kết nối. Phản hồi chứa các header RateLimit-Policy và RateLimit; khi vượt giới hạn, bạn nhận được 429 rate_limited kèm Retry-After. Đây là giới hạn của API — giới hạn hành động riêng của từng nick vẫn được áp dụng độc lập.

#Lịch sử lượt gọi

Mỗi lượt gọi được thêm vào lịch sử sử dụng của kết nối trong X-Buddy ngay sau khi câu trả lời đã gửi đi, nên lịch sử không bao giờ làm lượt gọi chậm lại. Nếu máy chủ dừng đúng lúc đó, lịch sử có thể thiếu đúng lượt gọi ấy; còn việc lượt gọi đã làm (việc đã xếp hàng, cài đặt đã lưu) vẫn được giữ. Các lần từ chối do kết nối đang tạm dừng hoặc đã thu hồi được ghi mỗi phút một lần.

#Xử lý hàng loạt

POST /batches (x_batch) chạy một hành động trên X cho tối đa 1.000 mục: các cặp nick + tham số được chỉ định rõ, hoặc kết hợp từng nick / nhóm với từng phần tử trong danh sách tham số. Thao tác này hỗ trợ chạy thử không thực thi và giãn cách theo từng nick. Các giới hạn, giờ chạy và danh sách loại trừ vẫn áp dụng. Theo dõi bằng x_batch_get; sự kiện batch.completed được phát khi kết thúc. Khi huỷ, các mục chưa được đưa vào hàng đợi sẽ bị loại bỏ và các việc đang chờ sẽ bị huỷ; các việc đang chạy vẫn hoàn tất.

#Media

1. POST /media/uploads (media_create_upload) với purpose là post (mặc định), profile hoặc dm theo thao tác bạn định dùng; kết quả trả về upload_url có thời hạn ngắn và một media_id.
2. Gửi các byte của tệp bằng PUT tới upload_url với loại nội dung bạn đã khai báo.
3. Dùng media_id trong thao tác đăng bài, cập nhật hồ sơ hoặc nhắn tin tương ứng với purpose đã chọn. Ảnh hồ sơ chỉ nhận JPG, PNG và WEBP.

Giới hạn: JPG, PNG và WEBP tối đa 5 MB; GIF tối đa 15 MB; MP4 và MOV tối đa 50 MB.

#Tải xuống

• Tài liệu OpenAPI 3.1 — tạo client bằng ngôn ngữ bất kỳ.
• TypeScript SDK — một tệp, không có thư viện phụ thuộc.
• Bộ sưu tập Postman
• Trình khám phá API — thử gọi API trong trình duyệt.

Tất cả đều được tạo từ cùng registry với tài liệu tham chiếu API.

#Ví dụ

curl "https://reach-link-craft.lovable.app/api/public/v1/accounts" \
  -H "Authorization: Bearer $XBUDDY_API_KEY"

#Liên quan

• Lỗi
• Webhook và sự kiện