API

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

  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:

{ "detail": { "code": "quota_exceeded", "message": "Gói … cho tối đa …", "details": null } }
Mã HTTPKhi nào
400Sai tham số; file Excel không hợp lệ
401Chưa đăng nhập hoặc mã hết hạn
402Hết hạn mức của gói, code = quota_exceeded
403Không có quyền, hoặc thiếu header CSRF
404Không tìm thấy
409Xung đột trạng thái, ví dụ workspace đang có lần chạy
413too_large: thân yêu cầu quá lớn (multipart trên 110 MB, JSON trên 5 MB)
422Bản duyệt không hợp lệ; details là danh sách lỗi
429rate_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ómGiới hạn
Đăng nhập20 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 file30 mỗi 10 phút mỗi người
MCP60 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ómVí dụ
Đăng nhập, tài khoản, thành viênphiên, 2FA, lời mời, vai trò
Workspacetạo, trạng thái, duyệt, build, cài đặt
Nguồn dữ liệunguồn, connector, OAuth sàn, lịch làm mới, xác nhận thông tin cá nhân
Chỉ số và dashboardsổ tay chỉ số, truy vấn chỉ số, trang dashboard
Lớp ngữ nghĩamô hình ngữ nghĩa, truy vấn ngữ nghĩa, "vì sao", chỉ số và trang của workspace
Hỏi đáphỏ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ợptoken MCP
Góimức dùng, mua thêm
Quyền với dữ liệuxuấ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

Markdown