API: Reports

Reports, paginated reports, export and scheduled delivery. All endpoints require authentication unless noted. 61 endpoints, 1 of them app only: an API key gets 403 there.

GET /api/report-email-templates

List published scheduled-email template versions

Query parameters

Name	Type	Required	Description
targetType	"report" | "dashboard"	no

Responses: 200

POST /api/report-email-templates/{id}/retire

Retire a workspace scheduled-email template version

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200

POST /api/report-email-templates/versions

Publish an immutable scheduled-email template version

Request body (JSON)

Field	Type	Required	Description
templateKey	string	yes
name	string	yes
targetScope	"all" | "report" | "dashboard"	no
subjectTemplate	string	yes
preheaderTemplate	string	yes
content	object	yes
replyTo	string | null	no

Responses: 201

POST /api/report-subscriptions/unsubscribe

Unsubscribe one personal report or dashboard subscription via a signed one-click token

RFC 8058 one-click unsubscribe, for the List-Unsubscribe link of a personal subscription’s email (a report or a dashboard). The signed link names the subscription, its subscriber and its workspace; only that subscription is removed. 200 with unsubscribed true when this request removed it; 200 with outcome already_removed when it had been removed before (a second click); 404 with outcome not_matched when the link no longer matches a subscription, so nothing was removed. 400 for a link that is invalid or expired.

Query parameters

Name	Type	Required	Description
token	string	yes

Responses: 200 · 404

GET /api/reports

List reports

An AI narrative text block computed from data a row-level-security policy hides from you comes without its numbers: its content holds the reason (narrativeWithheld) instead.

Query parameters

Name	Type	Required	Description
includeDeleted	boolean	no
limit	integer	no
offset	integer	no
type	string	no
search	string	no
sort	"recent" | "name"	no

Responses: 200 · 400 · 401

POST /api/reports

Create a new report

Request body (JSON)

Field	Type	Required	Description
name	string	yes
description	string	no
layout	string	no
pageSize	string	no
orientation	"portrait" | "landscape"	no
reportType	"paginated" | "summary" | "detailed" | "kpi_scorecard" | "template"	no

Responses: 201 · 400 · 401 · 409

GET /api/reports/{id}

Get report by ID

can_edit says whether the caller may change the report: their role edits reports, or an editor grant on this one (ENT-GOV). An AI narrative text block computed from data a row-level-security policy hides from you comes without its numbers and facts: its content holds the reason (narrativeWithheld) instead. It is computed for you when the report is sent to you, unless a person has edited its words: those are never computed again, and stay hidden from you in what is sent to you too. A save that sends the block back keeps the stored narrative.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

PUT /api/reports/{id}

Update a report

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
description	string	no
layout	string	no
dataConfig	string	no
pageSize	string	no
orientation	"portrait" | "landscape"	no
isPublished	boolean	no

Responses: 200 · 400 · 401 · 404

DELETE /api/reports/{id}

Delete a report (soft delete)

Needs the reports delete permission — except for a draft of the caller’s own that nothing has been put into (still named “Untitled Report”, no description, no blocks or filters, never published), which its creator may always delete.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 204 — No content · 401 · 404

GET /api/reports/{id}/access

List who a report is shared with

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/reports/{id}/access

Share a report with a workspace member (or change what they may do)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
email	string	yes
permission	"viewer" | "editor"	yes

Responses: 201 · 400 · 401 · 409

DELETE /api/reports/{id}/access/{accessId}

Stop sharing a report with someone

Path parameters

Name	Type	Required	Description
id	string	yes
accessId	string	yes

Responses: 204 — No content · 401 · 404

GET /api/reports/{id}/access/candidates

Search workspace members to share a report with

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
q	string	no

Responses: 200 · 400 · 401

POST /api/reports/{id}/change-matrix-scopes

Discover saved matrix cells and subtotals for comparison

Runs two fresh governed captures and returns at most 200 typed scalar cell/subtotal scopes across both. Uses only saved matrix axes and enabled subtotals, inside the selected repeated partition where applicable. Returns contributing row counts and availability on each side; absent scopes cannot be compared. Choices are not snapshots. Comparison rechecks the same scope in two new captures. No AI call is made.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
revision	string	yes
regionId	string	yes
measure	string	yes
group	string	yes
before	object	yes
after	object	yes
partitionKey	string	no

Responses: 200

GET /api/reports/{id}/change-options

Read saved table and matrix change-comparison choices

Returns visible table and matrix sums, counts, averages and numeric minima/maxima, including row-local, dataset aggregate and window table calculations, plus scalar matrix distinct counts. Minima/maxima identify matching groups and ties without additive shares; both captures need numeric observations. Shared distinct values are allocated equally among their groups. Matrix choices support a grand total or discovered saved cells/subtotals. Repeated list paths have distinct saved identifiers and ancestor group definitions; load partitions before comparing them. Includes saved revision, typed parameters and optional AI availability. No warehouse query is run.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200

POST /api/reports/{id}/change-partitions

Discover repeated-section partitions for two saved parameter sets

Runs two fresh governed captures, following the selected saved list ancestry and reuse path. Returns at most 200 typed scalar partitions across both captures with row counts and presence on each side. Missing partitions cannot be compared. Refuses partial data, unsafe grouping values and changed definitions or access. These choices are not snapshots; comparison reruns both queries and verifies the selected partition still exists. No AI call is made.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
revision	string	yes
regionId	string	yes
measure	string	yes
group	string	yes
before	object	yes
after	object	yes

Responses: 200

GET /api/reports/{id}/delivery-members

Find eligible delivery members

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
search	string	no

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/delivery-review

Review verified member destinations without querying their data

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
memberRecipients	array of object	yes

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/document-conversion

Prepare a flowing copy of a representable block report without saving

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200

POST /api/reports/{id}/drillthrough

Open an independently authorized drill target

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
regionId	string	yes
row	object	yes

Responses: 200

POST /api/reports/{id}/email-preview

Preview the canonical scheduled-report email

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
format	"pdf" | "xlsx" | "csv" | "pptx" | "docx" | "html"	no
scheduleName	string	no
timezone	string	no
occurrenceAt	string	no
emailTemplateVersionId	string	no
partialRenderPolicy	"fail_without_send" | "send_with_warning"	no
filters	object	no
sampleBurst	object	no

Responses: 200

POST /api/reports/{id}/explain-change

Compare two parameter sets on a saved report table or matrix

Runs two fresh governed captures under the current member identity. Repeated sections require a discovered partitionKey; every saved ancestor group restricts rows before section expressions and aggregates (saved query windows precede this restriction) and the same partition must exist in both captures. An optional discovered matrixScopeKey selects a saved cell/subtotal with contributing rows in both captures; no key means grand total. Refuses partial data and changed definitions or permissions. Returns deterministic group contributions, or matching-group evidence for numeric minima/maxima; optional metered AI receives only aggregate facts and selected breakdown labels, without extra partition metadata. When the workspace’s AI controls refuse the AI summary, the comparison is still returned, with narrative.status unavailable and aiRefusal (code, message, details) saying why. The comparison shows observations, not proof of causation. No query definitions or client evidence are accepted.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
revision	string	yes
regionId	string	yes
measure	string	yes
group	string	yes
before	object	yes
after	object	yes
partitionKey	string	no
matrixScopeKey	string	no
ai	boolean	no

Responses: 200

POST /api/reports/{id}/export

Export a report as PDF, Word, Excel, CSV, PowerPoint or HTML

X-Report-Status reports complete, empty or incomplete output. X-Report-Warnings contains URL-encoded layout notices. Word is available for tablix and multi-region document reports.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
format	"pdf" | "xlsx" | "csv" | "pptx" | "docx" | "html"	yes
parameters	array of object	no

Responses: 200

GET /api/reports/{id}/export-runs

List your recent exports for this report

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200

POST /api/reports/{id}/export-runs

Queue a private export of the saved report revision

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
format	"pdf" | "html" | "csv" | "xlsx" | "docx" | "pptx"	yes
mode	"document" | "data"	yes
regionId	string	no
parameters	object	no

Responses: 200

POST /api/reports/{id}/mobile-change-view

Read a saved comparison as native mobile evidence

The same complete, fresh, governed numerical comparison with saved revision, repeated-partition and matrix-scope checks. Returns version 1 native text/tables with totals, contribution or matching-extreme evidence, omitted groups, distinct-value counts and both capture contexts. No raw query rows, retained snapshot, AI request or client calculation. Changing parameters requires rediscovering scoped choices.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
revision	string	yes
regionId	string	yes
measure	string	yes
group	string	yes
before	object	yes
after	object	yes
partitionKey	string	no
matrixScopeKey	string	no

Responses: 200

POST /api/reports/{id}/mobile-drill

Recheck a mobile report row and open its saved drill target

Reruns the saved source with the same parameters and requires the exact complete row, expanded section, revision and authorization fingerprint. No client row values or target are accepted. Resolves typed parameters from the saved mapping and independently checks target membership, parameters, data policy and revision before returning a navigation link. A changed row requires a refresh. No retained capture, database write or AI call.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
parameters	object	no
revision	string	yes
nodeId	string	yes
rowId	string	yes
drillKey	string	yes

Responses: 200

POST /api/reports/{id}/mobile-view

Read a saved report as bounded accessible mobile content

Version 1 uses the saved table/document definition, or a block report’s saved blocks (text, pictures described, tables, charts as data rows, KPIs, and blocks reading a saved query, each with the report’s filters and the given parameter values), current member and governed fresh queries. A block report has no drill keys. No draft or query definition is accepted. Formatted rows preserve grouping, totals, matrices and repeated-section identity; raw hidden operands are omitted. Complete detail rows can include an opaque drillKey for independently rechecked navigation. Rechecks definition and data authorization before releasing the response. Source limits and failed sections remain explicit. Rejects more than 200 nodes, 80 columns per table, 10,000 semantic rows, 100,000 cells or 4 MiB without silently truncating. No storage or AI call.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
parameters	object	no

Responses: 200

POST /api/reports/{id}/parameter-values

Read permitted values for a parameter in a saved report

Uses the current saved tablix or document dataset, current viewer permissions and parent values. Available with document authoring disabled. Returns at most 200 choices; a capped list returns complete=false. No client query definition is accepted.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
parameter	string	yes
datasetId	string	no
parameters	object	no
search	string	no

Responses: 200

POST /api/reports/{id}/publish

Publish a report version (snapshot current state)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
changeNote	string	no
override	boolean	no
overrideReason	string	no

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/rollback

Restore a report from a published version

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
version	integer	yes

Responses: 200 · 400 · 401 · 404

GET /api/reports/{id}/schedules

List schedules for a report

Each schedule says whether it is paused for its creator’s review (hold: why, who changed what, and when), when the report filters it sends were pinned and whether they are still the report’s (filter_pin), and whether you may change who it sends to and what it sends, and resume it (may_change_what_it_sends: its creator or a workspace admin).

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/reports/{id}/schedules

Create a report schedule

A schedule starts from its next occurrence after it is made. Word (docx) is refused (400) for a report of layout blocks: it is available for paginated and document reports. The same request again within two minutes (a double click, a second Save) makes no second schedule: it answers 200 with the one already made.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	yes
cronExpression	string	yes
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx" | "html"	no
recipients	array of string	no
filters	object	no
burst	object	no
timezone	string	no
isActive	boolean	no
emailTemplateVersionId	string	no
partialRenderPolicy	"fail_without_send" | "send_with_warning"	no
deliveryMode	"publisher" | "verified_recipient"	no
memberRecipients	array of object	no

Responses: 200 · 201 · 400 · 401 · 409

PUT /api/reports/{id}/schedules/{scheduleId}

Update a report schedule

A publisher-mode schedule sends the report as its creator sees it, so only its creator or a workspace admin can change who it sends to or what it sends: its recipients (the address list or the data-driven list), its filters (the report parameters the send uses) or its delivery mode. Anyone else gets 403. Sending the stored values back unchanged is not a change. Such a schedule sends the report’s filters as they were when its creator made it, resumed it after a pause, switched it to publisher mode, or chose the current ones (pinFilters, its creator or a workspace admin, whatever the delivery mode): a later change to the report’s filters by anyone changes no send until then. Resuming a paused schedule, or switching it to publisher mode, makes it send the report’s filters as they are then.

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
cronExpression	string	no
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx" | "html"	no
recipients	array of string	no
filters	object	no
burst	object | null	no
timezone	string	no
isActive	boolean	no
emailTemplateVersionId	string	no
partialRenderPolicy	"fail_without_send" | "send_with_warning"	no
deliveryMode	"publisher" | "verified_recipient"	no
memberRecipients	array of object	no
baseEditVersion	integer	no
pinFilters	boolean	no	true: the schedule sends the report’s filters (its parameters among them) as they are now.

Responses: 200 · 400 · 401 · 403 · 404

DELETE /api/reports/{id}/schedules/{scheduleId}

Delete a report schedule

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Responses: 204 — No content · 401 · 404

GET /api/reports/{id}/schedules/{scheduleId}/runs

List delivery runs for a report schedule

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Responses: 200 · 400 · 401

GET /api/reports/{id}/schedules/{scheduleId}/runs/{runId}/attempts

List retained recipient evidence for a report delivery run (admin only)

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes
runId	string	yes

Responses: 200 · 400 · 401

GET /api/reports/{id}/subscriptions

List your subscriptions for this report

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/reports/{id}/subscriptions

Subscribe yourself to this report on a schedule

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
cronExpression	string	yes
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx" | "html"	no
timezone	string	no

Responses: 201 · 400 · 401 · 409

PUT /api/reports/{id}/subscriptions/{scheduleId}

Pause or resume your subscription

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Request body (JSON)

Field	Type	Required	Description
isActive	boolean	yes

Responses: 200 · 400 · 401 · 404

DELETE /api/reports/{id}/subscriptions/{scheduleId}

Delete your subscription

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Responses: 204 — No content · 401 · 404

GET /api/reports/{id}/subscriptions/{scheduleId}/history/v1

Read safe delivery history for your viewed personal report subscription

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Query parameters

Name	Type	Required	Description
baseEditVersion	integer	yes
after	string	no

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/subscriptions/{scheduleId}/remove/v1

Remove your report subscription at its viewed edit version

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Request body (JSON)

Field	Type	Required	Description
baseEditVersion	integer	yes

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/subscriptions/{scheduleId}/state/v1

Pause or resume your report subscription at its viewed edit version

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Request body (JSON)

Field	Type	Required	Description
baseEditVersion	integer	yes
isActive	boolean	yes

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/subscriptions/create/v1

Subscribe yourself to the saved report with duplicate protection

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
cronExpression	string	yes
timezone	string	yes
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx" | "html"	yes

Responses: 201 · 400 · 401 · 409

GET /api/reports/{id}/subscriptions/manage/v1

Read your report subscriptions with bounded delivery summaries

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
after	string	no

Responses: 200 · 400 · 401 · 404

POST /api/reports/{id}/test-send

Send a one-off test render of the report

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
format	"pdf" | "xlsx" | "csv" | "pptx" | "docx" | "html"	no
scheduleName	string	no
timezone	string	no
occurrenceAt	string	no
emailTemplateVersionId	string	no
partialRenderPolicy	"fail_without_send" | "send_with_warning"	no
filters	object	no
sampleBurst	object	no
recipient	string	no
confirmExternalRecipient	boolean	no

Responses: 200

GET /api/reports/{id}/versions

List report versions

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

GET /api/reports/export-runs/{runId}

Read your private export progress

Path parameters

Name	Type	Required	Description
runId	string	yes

Responses: 200

POST /api/reports/export-runs/{runId}/cancel

Cancel an export or remove access to its finished artifact

Path parameters

Name	Type	Required	Description
runId	string	yes

Responses: 200

GET /api/reports/export-runs/{runId}/copy/v1

Read verified capture context for your unexpired saved PDF copy

Path parameters

Name	Type	Required	Description
runId	string	yes

Responses: 200

GET /api/reports/export-runs/{runId}/download

Download an unexpired private artifact after checking current access

Path parameters

Name	Type	Required	Description
runId	string	yes

Responses: 200

GET /api/reports/exports/capabilities

Read background export availability and limits

Responses: 200

POST /api/reports/paginated

Create a paginated (operational) report

Request body (JSON)

Field	Type	Required	Description
name	string	yes
description	string	no
tablix	object	yes
pageSize	string	no
orientation	"portrait" | "landscape"	no

Responses: 200

POST /api/reports/paginated/ai-edits

Propose reviewed formatting and layout edits for a report draft

App only. An API key gets 403: AI features are available in the DataSquares app; API keys can’t use them.

Explicit metered AI call, with no warehouse queries or report writes. Only the request and at most 100 curated layout/column settings reach the AI; query definitions, rows, filters, formulas and delivery settings are excluded. Returns at most 12 validated proposed edits with before/after values. Author permissions, saved report revision and the document authoring gate are rechecked after the call. Apply selected suggestions to the same draft through ai-edits/preview, then explicitly save using the ordinary authoring workflow.

Request body (JSON)

Field	Type	Required	Description
version	1 | 2	yes
draft	object	yes
reportId	string	no
request	string	yes

Responses: 200

POST /api/reports/paginated/ai-edits/preview

Validate selected report edits against the unchanged draft without saving

No AI call, query or persistent write. A matching SHA-256 draft revision is required. Only curated formatting/layout setters are allowed; unknown or duplicate settings and invalid candidates are refused. Returns a candidate for explicit local draft application. The ordinary report save remains a separate action.

Request body (JSON)

Field	Type	Required	Description
version	1 | 2	yes
draft	object	yes
reportId	string	no
revision	string	yes
edits	array of object	yes

Responses: 200

GET /api/reports/paginated/capabilities

Read document-section authoring availability

Responses: 200

POST /api/reports/paginated/check

Check draft report settings without querying data or sending a delivery

Request body (JSON)

Field	Type	Required	Description
tablix	object	no
definition	object	no
reportId	string	no
parameters	object	no
format	"pdf" | "html" | "csv" | "xlsx" | "docx" | "pptx"	no

Responses: 200

POST /api/reports/paginated/document-preview

Resolve or preview a flowing multi-region report

Request body (JSON)

Field	Type	Required	Description
definition	object	no
reportId	string	no
name	string	no
output	"explore" | "pdf" | "html" | "parameter-values"	no
parameters	object	no
datasetId	string	no
parameter	string	no
search	string	no

Responses: 200

POST /api/reports/paginated/preview

Preview a paginated report as PDF or a formatted data sample (no save)

Set output to sample for JSON display text and raw rows (at most 25 rows). Dataset expressions use the sample scope. The default output is PDF, with completeness metadata in response headers.

Request body (JSON)

Field	Type	Required	Description
tablix	object	yes
name	string	no
output	"pdf" | "sample" | "explore" | "parameter-values"	no
parameters	object	no
parameter	string	no
search	string	no

Responses: 200

GET /api/reports/subscriptions

List your subscriptions across reports and dashboards

Responses: 200 · 400 · 401