# 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](/en/docs/mcp) 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:

```json
{ "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

- [MCP server](/en/docs/mcp)
- [Security and privacy](/en/docs/security-privacy)
