API

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

  1. POST /v1/auth/login returns an access token (JWT) valid for 15 minutes.
  2. Send it with every request: Authorization: Bearer <access token>.
  3. Refresh with POST /v1/auth/refresh, using the dx_refresh session cookie (HttpOnly) and the header X-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 header X-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 } }
HTTPWhen
400Bad parameters; invalid Excel file
401Not signed in, or token expired
402Plan quota reached, code = quota_exceeded
403Not allowed, or missing CSRF header
404Not found
409State conflict, e.g. the workspace already has a run in progress
413too_large: request body too big (multipart over 110 MB, JSON over 5 MB)
422Invalid approval; details lists the errors
429rate_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.

GroupLimit
Login20 per minute per IP
Sign-up10 per 10 minutes per IP
Asking Si (POST /ask, messages in a session)20 per minute per user, 60 per minute per workspace
File uploads30 per 10 minutes per user
MCP60 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.

Markdown