Reference · updated 4 November 2026

REST API

The same data, definitions and query engine your agents reach over MCP, as plain HTTPS and JSON. Use it from scripts, n8n, Make, Zapier or your own backend. Every answer names the dataset version it came from, and every call shows up in the workspace audit.

OpenAPI 3.1 spec https://app.datatomcp.com/v1

Quick start

1. In the app, open Account → API keys and create a key. It starts with dtm_ and is shown once.
2. Find a dataset id with GET /datasets, or copy it from the dataset page.
3. Ask for totals. This one uses the team's approved paid_revenue definition:

curl https://app.datatomcp.com/v1/datasets/DATASET_ID/query \
  -H "Authorization: Bearer $DATATOMCP_KEY" \
  -H "content-type: application/json" \
  -d '{
    "group_by": ["region"],
    "metrics": [{ "metric": "paid_revenue" }, { "fn": "count", "as": "orders" }],
    "where": [{ "column": "order_date", "op": "between", "value": ["2026-01-01", "2026-09-30"] }],
    "order_by": [{ "column": "paid_revenue", "dir": "desc" }]
  }'

const res = await fetch("https://app.datatomcp.com/v1/datasets/DATASET_ID/query", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.DATATOMCP_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ group_by: ["region"], metrics: [{ metric: "paid_revenue" }] }),
});
const { rows, meta } = await res.json();
// meta.version: pass it as "version" on follow-up calls to stay on the same data

import os, requests

r = requests.post(
    "https://app.datatomcp.com/v1/datasets/DATASET_ID/query",
    headers={"Authorization": f"Bearer {os.environ['DATATOMCP_KEY']}"},
    json={"group_by": ["region"], "metrics": [{"metric": "paid_revenue"}]},
)
r.raise_for_status()
rows, meta = r.json()["rows"], r.json()["meta"]

The answer:

{
  "rows": [
    { "region": "EU", "paid_revenue": 412870.5, "orders": 1834 },
    { "region": "US", "paid_revenue": 298114, "orders": 1310 }
  ],
  "meta": {
    "dataset_id": "ds_8f2k…",
    "version": 14,
    "refreshed_at": "2026-11-04T07:12:09.000Z",
    "rows_returned": 2,
    "rows_matched": 2,
    "truncated": false,
    "metrics": [{ "name": "paid_revenue", "approved_by": "Ana" }],
    "view_url": "https://app.datatomcp.com/app/datasets/ds_8f2k…?q=…"
  }
}

Authentication

Send the key in the Authorization header: Authorization: Bearer dtm_…. A key acts as the person who created it, with their role in each workspace (owner, editor or viewer). You can limit a key to some workspaces from the Connect page; it then sees nothing else. Keys can't create or revoke other keys: do that in the app. Revoked keys stop working at once.

Agents in Claude, ChatGPT, Cursor and other MCP clients don't need a key: they connect to https://app.datatomcp.com/mcp and sign in with OAuth.

The query

Queries are JSON, not SQL. Column names are checked against the dataset, values are always bound as parameters, and agents get read-only access. There are two modes:

• Rows: leave out metrics. Use select, where, order_by, limit (up to 1,000) and offset.
• Totals: add metrics, and group_by for one row per group.

Filters

{ "column": "status", "op": "in", "value": ["paid", "shipped"] }. Operators: eq, neq, gt, gte, lt, lte, in, not_in, contains, starts_with, is_null, not_null, between. between includes both ends; contains and starts_with ignore case. Call GET /datasets/{id}/values/{column} first to filter on the values that are really there.

Metrics and definitions

A metric is either a calculation, { "fn": "sum", "column": "amount", "as": "revenue" } with fn one of count, count_distinct, sum, avg, min or max, or a saved definition by name: { "metric": "paid_revenue" }. A definition is the team's agreed meaning of a number, approved by a person, and the answer says who approved it. A metric can carry its own where, so "revenue" and "refunded revenue" fit in one call.

Linked datasets

When a dataset links to another (orders to customers, say), the linked columns work as alias.column in select, where and group_by: "group_by": ["customers.segment"]. Chained links work too (orders → customers → regions). GET /datasets/{id} lists them.

Versions

Every refresh makes a new version. Pass "version": 14 on a query to read the data an earlier answer came from, so a follow-up question doesn't change under you. Free keeps 2 versions, Pro 20, for 30 days.

What every answer carries

dataset_id

The dataset that answered.

version

The dataset version the result came from.

refreshed_at

When this version was fetched or uploaded.

rows_returned

Rows in this response.

rows_matched

Rows that matched before the limit.

truncated

True when more rows matched than the limit returned.

metrics

The saved definitions the query used, with who approved them.

linked

unmatched

Rows whose link value found no row in the linked dataset.

view_url

A page where a person can check the rows behind the number.

rows_counted

Totals: rows of the dataset the numbers were computed over, after the filters.

units

Unit per result column, from the definition or the column's meaning.

method

How the numbers were computed, in one line.

freshness

warnings

What affects the number: duplicate rows, empty values in the columns used, sums of columns that don't add up.

curl https://app.datatomcp.com/v1/datasets/DATASET_ID/chart \
  -H "Authorization: Bearer $DATATOMCP_KEY" -H "content-type: application/json" \
  -d '{ "chart": "columns", "x": "month", "title": "EU revenue doubled in Q3",
        "query": { "group_by": ["month"], "metrics": [{ "metric": "paid_revenue" }] },
        "output": "svg" }' > chart.svg

Limits

Daily limits reset at 00:00 UTC. GET /usage shows today's count. Queries stop after a few seconds; add filters if one times out.

Errors

Errors are JSON with a stable code and a message written to be shown to a person or an agent: { "error": { "code": "unknown_column", "message": "…" } }.

Something missing or wrong? Write to [email protected]. For agents, see the MCP setup guides; for charts, the chart library.