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 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
POST /v1/auth/logintrả mã truy cập (JWT) sống 15 phút.- Gửi kèm mỗi yêu cầu:
Authorization: Bearer <mã truy cập>. - Làm mới bằng
POST /v1/auth/refresh, dùng cookie phiêndx_refresh(HttpOnly) và headerX-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 headerX-DX-Tenant: <id>.
Workspace không thuộc người dùng: 403.
Lỗi
Mọi lỗi có cùng dạng:
{ "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.
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.