HTTP API overview
Conventions of the DataxLand HTTP API — Bearer authentication, choosing a workspace, the error shape, rate limits (429, Retry-After), quotas (402) and resource groups.
The DataxLand HTTP API is the API the web app uses; everything in the app goes through it. There are no separate API keys for machine-to-machine integration yet: to let an AI agent or an external tool read metrics, use the MCP server with an expiring, revocable token.
Base path and versioning
- Every path starts with
/v1. From the browser the app calls/api/v1/…on its own domain. - Responses are UTF-8 JSON. Dates are
YYYY-MM-DD; timestamps are ISO 8601 in UTC. Business dates (periods, "data as of") follow the workspace's time zone. - The UI says workspace; the API says
tenant.
Authentication
POST /v1/auth/loginreturns an access token (JWT) valid for 15 minutes.- Send it with every request:
Authorization: Bearer <access token>. - Refresh with
POST /v1/auth/refresh, using thedx_refreshsession cookie (HttpOnly) and the headerX-DX-CSRF: 1.
Missing, invalid or expired token: 401. Missing role in the workspace: 403. Accounts with 2FA enter their code at login.
Choosing a workspace
- Paths
/v1/tenants/{id}/…use{id}. - Metric, dashboard and ask endpoints (
/v1/metrics…,/v1/dashboards…,/v1/ask) use the headerX-DX-Tenant: <id>.
A workspace the user does not belong to: 403.
Errors
Every error has the same shape:
{ "detail": { "code": "quota_exceeded", "message": "…", "details": null } }| HTTP | When |
|---|---|
| 400 | Bad parameters; invalid Excel file |
| 401 | Not signed in, or token expired |
| 402 | Plan quota reached, code = quota_exceeded |
| 403 | Not allowed, or missing CSRF header |
| 404 | Not found |
| 409 | State conflict, e.g. the workspace already has a run in progress |
| 413 | too_large: request body too big (multipart over 110 MB, JSON over 5 MB) |
| 422 | Invalid approval; details lists the errors |
| 429 | rate_limited |
message is human-readable and safe to show to users.
Rate limits (429)
Over a limit the API returns 429 with code = "rate_limited", a Retry-After header (seconds) and details.retry_after. Wait that long before retrying; do not retry in a tight loop.
| Group | Limit |
|---|---|
| Login | 20 per minute per IP |
| Sign-up | 10 per 10 minutes per IP |
Asking Si (POST /ask, messages in a session) | 20 per minute per user, 60 per minute per workspace |
| File uploads | 30 per 10 minutes per user |
| MCP | 60 per minute per token, 120 per minute per user |
Quotas (402)
Creating something beyond the plan's quota returns 402 quota_exceeded; reading is never blocked.
Resource groups
Auth, account and members · workspaces (create, status, approve, build, settings) · sources (connectors, marketplace OAuth, refresh schedules, personal-data confirmation) · metrics and dashboards · semantic layer (model, semantic queries, "why" analysis, workspace metrics and pages) · questions to Si, history, knowledge · notifications (destinations, scheduled reports, alerts, chat Q&A) · MCP tokens · plan usage and add-ons · data rights (workspace export, personal export, deletion).
The interactive API docs (/docs) are disabled in production.
Related
Set up with an AI agent
A ready-to-copy prompt so Claude Code, Cursor or Codex can read the DataxLand docs and connect MCP for you.
Members and roles
Invite colleagues to a workspace, choose the Admin, Analyst or Viewer role, revoke invitations, transfer ownership, require 2FA and read the security log.