The REST API | ATX AnalyticsTable Docs

The REST APICredentials (scoped service tokens, Entra ID, the installation token), the role each operation needs, every endpoint of /api/v1, and worked curl and Python examples. Base path: /api/v1 on the backend — the same host and port as the application, behind your reverse proxy on a server installation. The API adds no new listener and no new port. Give every integration its own SCOPED SERVICE TOKEN. An administrator lists tokens in the file named by ANALYTICS_API_TOKENS_FILE, each with a name and a role (viewer, analyst or admin). The file holds only SHA-256 digests, and revoking a token is an edit of the file, with no restart. Send the token as "Authorization: Bearer <token>". Where the installation signs people in with Microsoft Entra ID, an Entra access token works too, and the call runs as that person.

Overview

Base path: /api/v1 on the backend — the same host and port as the application, behind your reverse proxy on a server installation. The API adds no new listener and no new port.

Credentials and roles for the API

Give every integration its own SCOPED SERVICE TOKEN. An administrator lists tokens in the file named by ANALYTICS_API_TOKENS_FILE, each with a name and a role (viewer, analyst or admin). The file holds only SHA-256 digests, and revoking a token is an edit of the file, with no restart. Send the token as "Authorization: Bearer <token>". Where the installation signs people in with Microsoft Entra ID, an Entra access token works too, and the call runs as that person.
The installation's shared token acts as an administrator and should not be used for integrations. Reading is viewer work. Calling an MCP tool needs analyst, and configuring MCP servers needs admin. GET /api/v1/me shows which identity, role and rate limit a credential has.

Credentials

Scoped service token — Authorization: Bearer <token> — The role written beside the token (viewer, analyst or admin); recorded in the audit trail as service:<name> — Integrations. Recommended.
Microsoft Entra ID access token — Authorization: Bearer <token> — The person signed in, with the role their groups map to — Tools that act on behalf of a signed-in person
Installation token — X-Analytics-Token: <token> — admin — Break-glass administration only — never an integration
Scoped service tokens are listed by an administrator in the file named by ANALYTICS_API_TOKENS_FILE. The file holds only SHA-256 digests, never the tokens themselves, and is re-read when it changes, so revoking a token is an edit of the file with no restart.
[ { "name": "reporting-bot", "sha256": "<sha256 hex of the token>", "role": "viewer" }, { "name": "jira-sync", "sha256": "<sha256 hex of the token>", "role": "analyst" } ]
1. Create a token: openssl rand -base64 32 (or any 32 random bytes, base64-encoded).
2. Compute its digest: printf %s "$TOKEN" | sha256sum — on Windows, Get-FileHash on a file holding only the token, or any SHA-256 tool.
3. Add an entry with a name, the digest and the role to the tokens file. Give an integration the lowest role that works: viewer reads; only calling an MCP tool needs analyst.
4. Hand the token to the integration through its own secret store. Nobody, including the server, can recover it from the file.
5. Check it: GET /api/v1/me returns the identity, role, permissions and rate limit the token resolves to.

Roles

Discovery: /api/v1, /openapi.json, /docs, /me, /health — viewer
Tables, POST /query, connections, connection query — viewer — object-level grants apply
Metric catalogue and POST /metrics/query — viewer — the grant on the metric's connection applies
Dashboards and widget data — viewer — the dashboard grant applies
MCP: list servers, templates and tools — viewer
MCP: call a tool — analyst

Endpoints

GET — /api/v1 — Version, build and links
GET — /api/v1/openapi.json — The OpenAPI 3.1 document
GET — /api/v1/docs — The HTML reference — no scripts, no external assets, so it works on an air-gapped server
GET — /api/v1/me — Identity, role, permissions and rate limit of the caller
GET — /api/v1/health — Engine admission state and MCP circuit states: ok, degraded or draining
GET — /api/v1/tables — Tables of the project named by the X-Project-Path header
GET — /api/v1/tables/{name} — Columns of one table
POST — /api/v1/query — One read-only DuckDB statement on the project database, paged
GET — /api/v1/connections — Saved connections visible to the caller — id, name, kind and database only, never credentials
POST — /api/v1/connections/{id}/query — One SELECT or WITH statement on a saved connection, paged
GET — /api/v1/metrics — The metric catalogue (?kind=, ?q=)
GET — /api/v1/metrics/{id} — One metric; for a measure, the dimensions it can be sliced by
POST — /api/v1/metrics/query — A headless metric query — see Headless metrics
GET — /api/v1/dashboards — Dashboards visible to the caller
GET — /api/v1/dashboards/{urn} — One dashboard definition
POST — /api/v1/dashboards/{urn}/widgets/{wid}/data — The data behind one widget
GET — /api/v1/mcp/servers — Registered MCP servers and their health
GET — /api/v1/mcp/templates — Ready-made MCP server definitions
GET — /api/v1/mcp/servers/{id}/tools — A server's tools, their class and the policy decision
POST — /api/v1/mcp/servers/{id}/tools/{tool}/call — Call one allowed tool

Examples

export ATX_URL=https://analytics.example.com export ATX_TOKEN=... # a scoped service token export ATX_PROJECT='D:\Projects\Finance' # Who am I? curl -sS "$ATX_URL/api/v1/me" -H "Authorization: Bearer $ATX_TOKEN" # A query, 500 rows per page curl -sS -X POST "$ATX_URL/api/v1/query" \ -H "Authorization: Bearer $ATX_TOKEN" -H "X-Project-Path: $ATX_PROJECT" \ -H "Content-Type: application/json" \ -d '{"sql":"SELECT region, SUM(amount) AS revenue FROM sales GROUP BY region","limit":500}' # The next page: the same body plus the cursor from the previous answer curl ... -d '{"sql":"...same...","limit":500,"cursor":"eyJvIjo1MDAsImgiOiI..."}' # The same as CSV curl ... "$ATX_URL/api/v1/query?format=csv" ... # Revenue by region from the governed semantic layer curl -sS -X POST "$ATX_URL/api/v1/metrics/query" \ -H "Authorization: Bearer $ATX_TOKEN" -H "Content-Type: application/json" \ -d '{"measures":["revenue"],"dimensions":["region"],"orderBy":[{"field":"revenue","direction":"desc"}],"limit":10}'
Python, reading every page of a query:
import requests BASE, TOKEN = "https://analytics.example.com/api/v1", "..." S = requests.Session() S.headers["Authorization"] = f"Bearer {TOKEN}" def query_all(sql, project): body, rows = {"sql": sql, "limit": 5000}, [] while True: r = S.post(f"{BASE}/query", json=body, headers={"X-Project-Path": project}, timeout=120) r.raise_for_status() page = r.json() rows += page["rows"] if not page["nextCursor"]: return rows body["cursor"] = page["nextCursor"]
A query through the API can never change data, whatever the role. To write, use the application itself, where the change is made by a person and recorded as theirs.

Glossary terms on this page

KPI dashboard: definition

ATX Institute on LinkedIn

This site needs JavaScript for the full experience. Every page above is reachable without it.