# REST API

> Gọi X-Buddy từ n8n, Make, Zapier hoặc mã nguồn — khoá API, idempotency, phiên bản, việc và chờ kết quả, phân trang, xử lý hàng loạt, media và tải xuống.

Source: https://x.builera.app/docs/vi/rest-api
Last checked: 2026-10-24

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 {#base-url-and-authentication}

- **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:

```http
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 {#writes-need-an-idempotency-key}

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 {#versioned-settings}

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ả {#jobs-and-waiting}

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`.

> [!WARNING]
> Một việc kết thúc với trạng thái `unknown` có thể đã thực sự được thực hiện trên X. Tuyệt đối không gửi lại với khoá idempotency mới.

## Phản hồi và phân trang {#responses-and-pagination}

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

```json
{ "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 độ {#rate-limit}

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 {#request-history}

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 {#batches}

`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 {#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 {#downloads}

- [Tài liệu OpenAPI 3.1](/api/public/v1/openapi.json) — tạo client bằng ngôn ngữ bất kỳ.
- [TypeScript SDK](/api/public/v1/sdk.ts) — một tệp, không có thư viện phụ thuộc.
- [Bộ sưu tập Postman](/api/public/v1/postman.json)
- [Trình khám phá API](/docs/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](/docs/vi/reference).

## Ví dụ {#example}

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

## Liên quan {#related}

- [Lỗi](/docs/vi/errors)
- [Webhook và sự kiện](/docs/vi/webhooks-and-events)