# API HTTP — tổng quan

> Quy ước của API HTTP DataxLand — xác thực Bearer, chọn workspace, dạng lỗi, giới hạn tốc độ (429, Retry-After), hạn mức (402) và nhóm tài nguyên.

API HTTP của DataxLand là API mà ứng dụng web dùng; mọi thao tác trong ứng dụng đều đi qua nó. Hiện **chưa có khóa API riêng** cho tích hợp máy với máy: để AI agent hay công cụ bên ngoài đọc chỉ số, dùng [máy chủ MCP](/vi/docs/mcp) với token có hạn và thu hồi được.

## Địa chỉ và phiên bản

- Mọi đường dẫn bắt đầu bằng `/v1`. Từ trình duyệt, ứng dụng gọi qua `/api/v1/…` trên cùng domain của ứng dụng.
- Phản hồi là JSON UTF-8. Ngày dạng `YYYY-MM-DD`; thời điểm ISO 8601 theo UTC. Ngày nghiệp vụ (kỳ, "dữ liệu đến") theo múi giờ của workspace.
- Trên giao diện gọi là **workspace**, trong API là `tenant`.

## Xác thực

1. `POST /v1/auth/login` trả mã truy cập (JWT) sống 15 phút.
2. Gửi kèm mỗi yêu cầu: `Authorization: Bearer <mã truy cập>`.
3. Làm mới bằng `POST /v1/auth/refresh`, dùng cookie phiên `dx_refresh` (HttpOnly) và header `X-DX-CSRF: 1`.

Thiếu, sai hoặc hết hạn mã: `401`. Thiếu vai trò ở workspace: `403`. Tài khoản bật 2FA phải nhập mã khi đăng nhập.

## Chọn workspace

- Đường dẫn `/v1/tenants/{id}/…` dùng `{id}`.
- Các endpoint chỉ số, dashboard và hỏi đáp (`/v1/metrics…`, `/v1/dashboards…`, `/v1/ask`) dùng header `X-DX-Tenant: <id>`.

Workspace không thuộc người dùng: `403`.

## Lỗi

Mọi lỗi có cùng dạng:

```json
{ "detail": { "code": "quota_exceeded", "message": "Gói … cho tối đa …", "details": null } }
```

| Mã HTTP | Khi nào |
| --- | --- |
| 400 | Sai tham số; file Excel không hợp lệ |
| 401 | Chưa đăng nhập hoặc mã hết hạn |
| 402 | Hết hạn mức của gói, `code = quota_exceeded` |
| 403 | Không có quyền, hoặc thiếu header CSRF |
| 404 | Không tìm thấy |
| 409 | Xung đột trạng thái, ví dụ workspace đang có lần chạy |
| 413 | `too_large`: thân yêu cầu quá lớn (multipart trên 110 MB, JSON trên 5 MB) |
| 422 | Bản duyệt không hợp lệ; `details` là danh sách lỗi |
| 429 | `rate_limited`: vượt giới hạn tốc độ |

`message` viết bằng tiếng Việt, hiển thị được cho người dùng.

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

Vượt giới hạn trả `429` với `code = "rate_limited"`, header **`Retry-After`** (giây) và `details.retry_after`. Chờ đúng số giây đó rồi thử lại; đừng thử lại liên tục.

| Nhóm | Giới hạn |
| --- | --- |
| Đăng nhập | 20 mỗi phút mỗi IP |
| Đăng ký | 10 mỗi 10 phút mỗi IP |
| Hỏi Si (`POST /ask`, tin trong phiên) | 20 mỗi phút mỗi người, 60 mỗi phút mỗi workspace |
| Tải file | 30 mỗi 10 phút mỗi người |
| MCP | 60 mỗi phút mỗi token, 120 mỗi phút mỗi người |

## Hạn mức (402)

Thao tác tạo thêm vượt hạn mức gói trả `402 quota_exceeded`; thao tác xem không bao giờ bị chặn. Xem [Gói và hạn mức](/vi/docs/billing/quotas).

## Nhóm tài nguyên

| Nhóm | Ví dụ |
| --- | --- |
| Đăng nhập, tài khoản, thành viên | phiên, 2FA, lời mời, vai trò |
| Workspace | tạo, trạng thái, duyệt, build, cài đặt |
| Nguồn dữ liệu | nguồn, connector, OAuth sàn, lịch làm mới, xác nhận thông tin cá nhân |
| Chỉ số và dashboard | sổ tay chỉ số, truy vấn chỉ số, trang dashboard |
| Lớp ngữ nghĩa | mô hình ngữ nghĩa, truy vấn ngữ nghĩa, "vì sao", chỉ số và trang của workspace |
| Hỏi đáp | hỏi Si, lịch sử, kiến thức |
| Thông báo | đích nhận, báo cáo định kỳ, cảnh báo, hỏi đáp qua chat |
| Tích hợp | token MCP |
| Gói | mức dùng, mua thêm |
| Quyền với dữ liệu | xuất workspace, xuất dữ liệu cá nhân, xóa |

Tài liệu tương tác của API (`/docs`) tắt trên bản chính thức.

## Liên quan

- [Máy chủ MCP](/vi/docs/mcp)
- [Bảo mật và quyền riêng tư](/vi/docs/security-privacy)
- [Gói và hạn mức](/vi/docs/billing/quotas)
