HTTP API reference

Replaces the report's instructions. An empty string clears them. Edit access.

Body

reportIdstringRequired

Report ID.

instructionsstringRequired

At most 1,500 characters.

maxLength: 1500

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "instructions": "Amounts are USD. Fiscal year starts in May."
}

Response 200

messagestringOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

The report's lasting guidance to the assistant (terminology, units, conventions).

Parameters

report_idpath · stringRequired

Response 200

instructionsstringOptional

Example response

{
  "instructions": "Amounts are USD. Fiscal year starts in May."
}

Errors

403 Scope, access or subscription. Every error has error, message and code.

Reports the caller can open, newest first, including ones being deleted (with deletion).

Response 200

Example response

[
  {
    "id": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
    "reportName": "Sales overview",
    "accessLevel": "Owner",
    "ownerFullName": "Alex Morgan",
    "createdAt": "2026-10-13T10:52:04.120Z",
    "sourceCount": 1
  }
]

Pages, visuals and connections across the whole report without loading every visual. Each page carries its id, name, kind, viewport and hidden (limited to editors and people added to it). Each visual carries its key, type, title, page, query, contract, appearance, revision and layout; detail=true adds bindings and lineage. Page with offset and nextOffset while complete is false.

Parameters

report_idpath · stringRequired

kindquery · stringOptional

queryquery · stringOptional

Search text over titles and queries.

pageIdquery · stringOptional

Restrict to one page: its UUID or numeric ID.

currentPageIdquery · stringOptional

The page the caller is looking at (marks it in the result).

visualKeyquery · array<string>Optional

detailquery · stringOptional

true adds bindings, lineage and filters per visual.

offsetquery · integerOptional

limitquery · integerOptional

Response 200

statusstringOptional

enum: ["success"]

itemsarray<object>Optional

totalintegerOptional

offsetintegerOptional

completebooleanOptional

nextOffsetinteger | nullOptional

missingVisualKeysarray<string>Optional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Owner only. Deletion runs in the background: the report disappears from content APIs at once and GET /api/reports/{report_id}/deletion follows it. An active assistant run must stop first.

Parameters

report_idpath · stringRequired

Response 200

deletionobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Parameters

report_idpath · stringRequired

Response 200

deletionobjectOptional

Errors

404 Not found. Every error has error, message and code.

Cheap revision counters: compare them with the last values you saw to know what to re-read (pagesVersion, modelRevision, pagesFingerprint, and with visualsPage that page's visualsRevision), plus each of your conversations' run state. pagesFingerprint changes when any page (HTML or canvas) is saved, created or deleted. With visualsPage it also answers `page` ({pageUid, kind, version}), `hold`, `leases` and `presence` for that page; each HTML page's own version comes from GET /api/html/pages/{pageUid}; history is the report's (GET /api/reports/{reportId}/versions).

Parameters

report_idpath · stringRequired

visualsPagequery · integerOptional

Numeric page ID whose visualsRevision to include.

Response 200

reportIdstringOptional

Report ID.

accessLevelstringOptional

pagesVersionstringOptional

modelRevisionintegerOptional

pagesFingerprintstringOptional

pageobject | nullOptional

visualsPageIdinteger | nullOptional

visualsRevisionstring | nullOptional

chatobjectOptional

Errors

403 Scope, access or subscription. Every error has error, message and code.

Parameters

report_idpath · stringRequired

Body

reportNamestringRequired

1 to 50 characters.

minLength: 1 maxLength: 50

Example request body

{
  "reportName": "Sales overview FY27"
}

Response 200

reportNamestringOptional

messagestringOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

The report's saved versions, newest first. Every saved change makes one; version n is the report after that change. Each entry is one assistant run or one person's burst of edits (each within 5 minutes of the one before); expand lists one entry's versions one by one, so one change inside an entry can be undone by restoring the version before it. The first list of the whole report also has deletedPages. Needs Edit access to the report, or to the page with pageId.

Parameters

report_idpath · stringRequired

pageIdquery · stringOptional

A page's pageId: only that page's versions and its filters (page Edit is enough).

beforeVersionquery · integerOptional

nextBeforeVersion from the previous list, for older entries.

expandquery · integerOptional

An entry's version: its versions one by one, each as an entry of its own.

Response 200

headinteger | nullOptional

The latest version.

versionsarray<object>Optional

nextBeforeVersioninteger | nullOptional

deletedPagesarray<object>Optional

Pages deleted since history started that are still gone, newest first (the first list of the whole report).

Example response

{
  "head": 42,
  "nextBeforeVersion": null,
  "versions": [
    {
      "version": 42,
      "firstVersion": 39,
      "count": 4,
      "at": "2026-11-01T09:12:44.120Z",
      "actor": {
        "name": "Alex Morgan",
        "kind": "assistant"
      },
      "label": "Moved visual",
      "changed": [
        "Model",
        "Page 'Sales'"
      ]
    }
  ]
}

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

The report's definition document (GetReportDefinition) as it was at that version; with pageId, only that page and its filters.

Parameters

report_idpath · stringRequired

versionpath · integerRequired

pageIdquery · stringOptional

A page's pageId: only that page's versions and its filters (page Edit is enough).

Response 200

The report's definition document at that version (UnityReportDefinition), or with pageId {unityReportDefinition, pages: [that page], filters: [its filters]}.

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Make the report, or one page with pageId (a deleted page too), equal to a saved version, with the checks a save makes. Version n is the report after change n: to undo a change, restore the version listed before it (GET /api/reports/{report_id}/versions); for one change inside a grouped entry, list the entry with expand and restore the version before that change. A dry run (dryRun true, the default) changes nothing and returns the changes, the warnings (what can't come back), expectedVersion and expectedWarnings; the restore (dryRun false) needs both and answers 409 version_conflict when the report or the warnings moved since, and 409 restore_failed when a section wouldn't come back as saved. Restoring the whole report deletes pages added after that version. A restore is a new version. Needs Edit access to the report, or to the page with pageId; a deleted page needs Edit access to the report.

Parameters

report_idpath · stringRequired

versionpath · integerRequired

Body

pageIdstring | nullOptional

A page's pageId: only that page and its filters.

dryRunbooleanOptional

expectedVersioninteger | nullOptional

expectedVersion from the dry run.

expectedWarningsstring | nullOptional

expectedWarnings from the dry run.

Example request body

{
  "pageId": null,
  "dryRun": false,
  "expectedVersion": 42,
  "expectedWarnings": "3f9a1c0b7d2e4a65"
}

Response 200

dryRunbooleanOptional

appliedbooleanOptional

Whether the restore changed anything (it made a version).

reportVersionintegerOptional

The new version the restore made; absent when it changed nothing.

restoredFromintegerOptional

pageIdstring | nullOptional

expectedVersionintegerOptional

expectedWarningsstringOptional

changesarray<object>Optional

warningsarray<object>Optional

moreintegerOptional

How many changes beyond the first 300 are left out.

Example response

{
  "dryRun": true,
  "restoredFrom": 38,
  "pageId": null,
  "expectedVersion": 42,
  "expectedWarnings": "3f9a1c0b7d2e4a65",
  "changes": [
    {
      "section": "pages",
      "kind": "page",
      "id": "34432e64-7f1e-43b7-8a6c-bdb0926d0577",
      "name": "Draft",
      "pageId": "34432e64-7f1e-43b7-8a6c-bdb0926d0577",
      "change": "removed",
      "keys": []
    }
  ],
  "warnings": [
    {
      "code": "page_removed",
      "section": "pages",
      "id": "34432e64-7f1e-43b7-8a6c-bdb0926d0577",
      "name": "Draft",
      "text": "Page 'Draft' isn't in version 38, so the restore deletes it; it can be brought back from the deleted pages."
    }
  ]
}

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

What changed from one saved version to another (to omitted: the report now): each object added, removed or changed, by section, kind, id and name, with the keys that changed.

Parameters

report_idpath · stringRequired

fromquery · integerRequired

The earlier version.

toquery · integerOptional

The later version.

pageIdquery · stringOptional

A page's pageId: only that page's versions and its filters (page Edit is enough).

Response 200

fromVersionintegerOptional

toVersioninteger | nullOptional

changesarray<object>Optional

moreintegerOptional

How many changes beyond the first 300 are left out.

Example response

{
  "fromVersion": 38,
  "toVersion": null,
  "changes": [
    {
      "section": "pages",
      "kind": "visual",
      "id": "8c1f0b7e-2d1a-4c55-9a0e-5b7f0e1d2c3a",
      "name": "Revenue by month",
      "pageId": "34432e64-7f1e-43b7-8a6c-bdb0926d0577",
      "change": "changed",
      "keys": [
        "position"
      ]
    }
  ]
}

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

The report's name, the caller's access, its pages (both page IDs, kind, visibility and canvas) and its attached connections. Start here after choosing a report. contentEdit is true when the caller's View share is Edit content (they can also save text through the report's HTML pages); accessLevel stays View.

Parameters

report_idpath · stringRequired

Response 200

reportIdstringOptional

Report ID.

reportNamestringOptional

hasPermissionbooleanOptional

accessLevelstringOptional

contentEditbooleanOptional

pagesarray<value>Optional

connectionsarray<object>Optional

Example response

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "reportName": "Sales overview",
  "hasPermission": true,
  "accessLevel": "Owner",
  "connections": [],
  "pages": [
    {
      "PageID": 888,
      "PageUID": "34432E64-7F1E-43B7-8A6C-BDB0926D0577",
      "PageName": "Page 1",
      "PageKind": "report",
      "Hidden": false,
      "lockedViewport": null
    }
  ]
}

Errors

403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

A new report owned by the caller, with one empty canvas page and one conversation.

Body

reportNamestringRequired

1 to 50 characters.

minLength: 1 maxLength: 50

clientRequestIdstringOptional

Optional retry key, a UUID or any string up to 64 characters. Retrying with the same key returns the first result instead of a second report.

maxLength: 64

Example request body

{
  "reportName": "Sales overview",
  "clientRequestId": "sales-overview-1"
}

Response 201

reportIdstringOptional

Report ID.

defaultPageIdintegerOptional

Numeric ID of the first page.

defaultPageUidstringOptional

UUID of the first page.

messagestringOptional

Example response

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "defaultPageId": 888,
  "defaultPageUid": "34432e64-7f1e-43b7-8a6c-bdb0926d0577",
  "message": "Report created successfully"
}

Errors

400 Invalid input · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Pages visible to the caller, in creation order, with both IDs and the kind of page: report (a canvas of native visuals) or html.

Parameters

reportIdquery · stringRequired

Report ID. Also accepted as report_id.

Response 200

PageIDintegerOptional

PageUIDstringOptional

PageNamestringOptional

PageKindstringOptional

enum: ["report","html"]

ReportIDstringOptional

HiddenbooleanOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

A canvas page (pageKind report) for native visuals, or an HTML page (pageKind html) that starts from a blank template. Returns [page] by default, or the full receipt with includeReceipt.

Body

reportIdstringRequired

Report ID.

pageNamestringRequired

Alias: newPageName.

pageKindstringOptional

enum: ["report","html"] default: "report"

clientRequestIdstringOptional

Retry key: a UUID or any string up to 64 characters.

maxLength: 64

includeReceiptbooleanOptional

Return the receipt instead of [page].

default: false

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "pageName": "Spending",
  "clientRequestId": "page-spending-1"
}

Response 200

Example response

[
  {
    "PageID": 890,
    "PageUID": "678AE2F0-1469-489E-AE28-B729A0000E51",
    "PageName": "Spending",
    "PageKind": "report",
    "PageLayout": {
      "kind": "report"
    },
    "Hidden": false,
    "ReportID": "9af3fb53-34e2-4e88-a953-ffdecdeece82"
  }
]

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

Deletes the page with its visuals and filters. Conversations remain. The report's versions list it as a deleted page (GET /api/reports/{reportId}/versions), and restoring it brings it back with its original IDs.

Body

reportIdstringRequired

Report ID.

pageIdstringRequired

The page: its UUID or its numeric ID (every page parameter accepts either).

Response 200

A page receipt (see Receipt). The change is one report version; restoring the version listed before it (POST /api/reports/{reportId}/versions/{version}/restore) reverses it.

pagevalueOptional

reportIdstringOptional

Report ID.

resourceTypestringOptional

mutationobjectOptional

changeobjectOptional

canvasBoundsobjectOptional

Errors

403 Scope, access or subscription · 422 Cannot be applied. Every error has error, message and code.

Copies a page's visual definitions, layout and saved filters into a new page.

Body

reportIdstringRequired

Report ID.

sourcePageIdstringRequired

The page: its UUID or its numeric ID (every page parameter accepts either).

newPageNamestringRequired

clientRequestIdstringOptional

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "sourcePageId": 890,
  "newPageName": "Spending copy"
}

Response 200

pagevalueOptional

reportIdstringOptional

Report ID.

resourceTypestringOptional

mutationobjectOptional

changeobjectOptional

canvasBoundsobjectOptional

sourcePageobjectOptional

duplicatedVisualsarray<object>Optional

lockedViewportobjectOptional

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

Body

reportIdstringRequired

Report ID.

pageIdstringRequired

The page: its UUID or its numeric ID (every page parameter accepts either).

pageNamestringRequired

Alias: newPageName.

Response 200

A page receipt (see Receipt). The change is one report version; restoring the version listed before it (POST /api/reports/{reportId}/versions/{version}/restore) reverses it.

pagevalueOptional

reportIdstringOptional

Report ID.

resourceTypestringOptional

mutationobjectOptional

changeobjectOptional

canvasBoundsobjectOptional

Errors

403 Scope, access or subscription · 422 Cannot be applied. Every error has error, message and code.

Parameters

reportIdquery · stringRequired

Report ID. Also accepted as report_id.

pageIdquery · stringRequired

The page: its UUID or its numeric ID (every page parameter accepts either). Also accepted as page_id.

Response 200

reportIdstringOptional

Report ID.

pageIdintegerOptional

lockedViewportvalueOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found · 422 Cannot be applied. Every error has error, message and code.

Canvas pages have a fixed logical size (default 1280x720); visuals do not grow it. Send lockedViewport or its fields at the top level. An HTML page fills the window and has no canvas size: viewport fields on one are refused (422).

Body

reportIdstringRequired

Report ID.

pageIdstringRequired

The page: its UUID or its numeric ID (every page parameter accepts either).

lockedViewportvalueOptional

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "pageId": 890,
  "lockedViewport": {
    "width": 1600,
    "height": 900,
    "backgroundColor": "#ffffff"
  }
}

Response 200

pagevalueOptional

reportIdstringOptional

Report ID.

resourceTypestringOptional

mutationobjectOptional

changeobjectOptional

canvasBoundsobjectOptional

statusstringOptional

pageIdintegerOptional

pageLayoutobjectOptional

lockedViewportvalueOptional

Errors

403 Scope, access or subscription · 422 Cannot be applied. Every error has error, message and code.

Every visual on a page with its kind, title, position and connection, without data. The browser draws placeholders from it; read data with POST /api/reports/{report_id}/visual-data.

Parameters

reportIdquery · stringRequired

Report ID. Also accepted as report_id.

pageIdquery · stringOptional

The page: its UUID or its numeric ID (every page parameter accepts either). Also accepted as page_id.

initialPagequery · stringOptional

Read the first visible page when pageId is omitted.

Response 200

visualsarray<object>Optional

connectionsarray<object>Optional

shellCountsobjectOptional

pageobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 422 Cannot be applied. Every error has error, message and code.

Response 200

Response 200

Response 200

Your own report chats on a page (conversations are private to their creator).

Parameters

reportIdquery · stringRequired

Report ID.

pageIdquery · stringRequired

The page: its UUID or numeric ID.

Response 200

DataChatIDintegerOptional

NamestringOptional

PageIDintegerOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

A new report chat for assistant runs (POST /api/agent/runs takes its DataChatID).

Body

reportIdstringRequired

Report ID.

activePagestringRequired

The page: its UUID or numeric ID.

namestringOptional

clientRequestIdstringOptional

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "activePage": 890,
  "name": "API exploration"
}

Response 201

DataChatIDintegerOptional

NamestringOptional

PageIDintegerOptional

createdNowbooleanOptional

False when clientRequestId replayed an earlier creation.

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Response 200

Response 200

Response 200

Response 200

Response 200

Response 200

Response 200

Response 200

Response 200

Without kind: the native kinds and their purpose. With kind (repeat for up to three): the exact JSON Schemas for a definition, its changes and its appearance, plus rendering semantics and the renderer guide. Build create and update bodies from these.

Parameters

kindquery · array<string>Optional

Response 200

schemaVersionintegerOptional

kindsobjectOptional

Errors

400 Invalid input. Every error has error, message and code.

Copies a visual (definition, appearance and filters) to a page of the same report.

Body

reportIdstringRequired

Report ID.

typestringRequired

Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind.

enum: ["declarativeChart","dataTable","matrix","dataCard","textBox","shape"]

idstring | integerRequired

The visual's UUID (visualUid), or its legacy numeric ID.

pageIdstringRequired

The page: its UUID or numeric ID.

positionobjectOptional

Logical canvas pixels on the page (default page 1280x720). Omitted: Unity finds free space.

Response 200

idvalueOptional

reportIdstringOptional

Report ID.

pageIdintegerOptional

visualvalueOptional

mutationobjectOptional

changeobjectOptional

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

Validates the definition and its query against the report model and the kind's rules, saves it on the page and returns the receipt. Text boxes and shapes need no query.

A query or presentation that breaks a rule answers 422 with one sentence and its code (invalid_query, unknown_field, or legacy_sql for a visual saved as SQL).

Body

reportIdstringRequired

Report ID.

typestringRequired

Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind.

enum: ["declarativeChart","dataTable","matrix","dataCard","textBox","shape"]

pageIdstringRequired

The page: its UUID or numeric ID.

definitionobjectRequired

Per kind: GET /api/visuals/capabilities?kind={kind} returns the exact definition, changes and appearance schemas, required fields and rendering semantics.

positionobjectOptional

Logical canvas pixels on the page (default page 1280x720). Omitted: Unity finds free space.

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "type": "declarativeChart",
  "pageId": "678AE2F0-1469-489E-AE28-B729A0000E51",
  "definition": {
    "title": "Spend by category",
    "query": {
      "groups": [
        {
          "name": "Category",
          "field": "col_6f1c0d2a9b8e4f3a8c7d6e5f4a3b2c1d"
        }
      ],
      "values": [
        {
          "name": "Spend",
          "field": "fld_0a1b2c3d4e5f60718293a4b5c6d7e8f9"
        }
      ],
      "sort": [
        {
          "name": "Spend",
          "direction": "desc"
        }
      ]
    },
    "rendererSpec": {
      "mark": {
        "type": "bar",
        "cornerRadiusEnd": 3
      },
      "encoding": {
        "x": {
          "field": "Spend",
          "type": "quantitative"
        },
        "y": {
          "field": "Category",
          "type": "nominal",
          "sort": "-x",
          "title": null
        }
      }
    }
  },
  "position": {
    "x": 24,
    "y": 24,
    "width": 600,
    "height": 320
  }
}

Response 200

A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was.

persistedbooleanOptional

visualUidstringOptional

visual_idstringOptional

visual_typestringOptional

visualvalueOptional

mutationobjectOptional

changeobjectOptional

The visual before and after the change (null: created, deleted), for the tabs that show it.

layoutobjectOptional

Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps.

warningsarray<object>Optional

reportIdstringOptional

Report ID.

visual_dataobjectOptional

The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql).

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

Deletes one visual. Restoring the report version listed before the delete brings it back.

Body

reportIdstringRequired

Report ID.

typestringRequired

Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind.

enum: ["declarativeChart","dataTable","matrix","dataCard","textBox","shape"]

idstring | integerRequired

The visual's UUID (visualUid), or its legacy numeric ID.

expectedRevisionstringOptional

clientRequestIdstringOptional

Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409.

maxLength: 64

Response 200

A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was.

persistedbooleanOptional

visualUidstringOptional

visual_idstringOptional

visual_typestringOptional

visualvalueOptional

mutationobjectOptional

changeobjectOptional

The visual before and after the change (null: created, deleted), for the tabs that show it.

layoutobjectOptional

Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps.

warningsarray<object>Optional

reportIdstringOptional

Report ID.

visual_dataobjectOptional

The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql).

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Deletes 1 to 100 visuals in one transaction.

Body

reportIdstringRequired

Report ID.

targetsarray<object>Required

clientRequestIdstringOptional

Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409.

maxLength: 64

Response 200

receiptsarray<object>Optional

One receipt per visual.

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

All saved visuals of one page and the page's visualsRevision (compare it with GET /api/reports/{report_id}/live to know when to re-read).

Parameters

reportIdquery · stringRequired

Report ID. Also accepted as report_id.

pageIdquery · stringRequired

The page: its UUID or numeric ID. Also accepted as page_id, pageUid.

Response 200

reportIdstringOptional

Report ID.

pageIdintegerOptional

pageUidstringOptional

visualsRevisionstringOptional

visualsarray<value>Optional

Errors

403 Scope, access or subscription · 422 Cannot be applied. Every error has error, message and code.

Saves 1 to 100 visuals' positions and z-order in one transaction.

Body

reportIdstringRequired

Report ID.

targetsarray<object>Required

clientRequestIdstringOptional

Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409.

maxLength: 64

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "targets": [
    {
      "type": "declarativeChart",
      "id": "3976903A-10E2-4861-B202-A29CF2BD7531",
      "position": {
        "x": 24,
        "y": 24,
        "width": 620,
        "height": 320
      }
    }
  ]
}

Response 200

receiptsarray<object>Optional

One receipt per visual, in request order.

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

Validates a definition and runs its query without saving anything: the result a create would produce. Use it to check a query, its outputs and a renderer specification.

Body

reportIdstringRequired

Report ID.

typestringRequired

Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind.

enum: ["declarativeChart","dataTable","matrix","dataCard","textBox","shape"]

definitionobjectRequired

Per kind: GET /api/visuals/capabilities?kind={kind} returns the exact definition, changes and appearance schemas, required fields and rendering semantics.

Response 200

persistedbooleanOptional

enum: [false]

sql_dataobjectOptional

outputsarray<object>Optional

The query's outputs: groups, then values, with the result's types.

generatedSqlstringOptional

The SQL the visual query compiles to (read-only).

rendererSpecobjectOptional

Errors

403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

A saved visual's authored state (its visual query), its outputs and generatedSql, position and revision, with both page IDs.

Parameters

reportIdquery · stringRequired

Report ID. Also accepted as report_id.

typequery · stringRequired

Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind.

idquery · string | integerRequired

The visual's UUID (visualUid), or its legacy numeric ID.

Response 200

Errors

403 Scope, access or subscription · 422 Cannot be applied. Every error has error, message and code.

Applies only the given changes (title, query, rendererSpec, customization, position, pageId to move it, ...). Send expectedRevision from the last read; a stale one answers 409 visual_conflict with currentRevision.

Body

reportIdstringRequired

Report ID.

typestringRequired

Native visual kind. Chart presets (bar, line, scatter, pie) are declarativeChart specifications; an older name (barGraph, pieChart, ...) is refused with the current kind.

enum: ["declarativeChart","dataTable","matrix","dataCard","textBox","shape"]

idstring | integerRequired

The visual's UUID (visualUid), or its legacy numeric ID.

changesobjectRequired

Fields to change; GET /api/visuals/capabilities lists them per kind.

expectedRevisionstringOptional

The revision you read, for example 0x000000000000c356.

refreshDatabooleanOptional

Return a fresh read.

default: true

clientRequestIdstringOptional

Retry key, a UUID or any string up to 64 characters. A retry of a committed request writes nothing and answers the first attempt's outcome with replayed true; the same key with a different body answers 409.

maxLength: 64

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "type": "declarativeChart",
  "id": "3976903A-10E2-4861-B202-A29CF2BD7531",
  "expectedRevision": "0x000000000000c356",
  "changes": {
    "title": "Debit spend by category"
  },
  "refreshData": false
}

Response 200

A visual change receipt. The change is one report version: GET /api/reports/{reportId}/versions lists it, and restoring the version listed before it brings the visual back as it was.

persistedbooleanOptional

visualUidstringOptional

visual_idstringOptional

visual_typestringOptional

visualvalueOptional

mutationobjectOptional

changeobjectOptional

The visual before and after the change (null: created, deleted), for the tabs that show it.

layoutobjectOptional

Geometry feedback: canvasBounds, fitsWithinPage, overflowPixels, overlaps.

warningsarray<object>Optional

reportIdstringOptional

Report ID.

visual_dataobjectOptional

The saved definition and, for charts and cards, the first read (sql_data, outputs, generatedSql).

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied. Every error has error, message and code.

Reads 1 to 40 saved visuals of one page, with saved report, page and visual filters applied. The response is NDJSON: one line per read as it completes, {"key": index in reads, "status": HTTP status, "data": payload}, then {"done": true}. A read still running after the synchronous wait has status 202 and data {readJob}; collect it with GET /api/read-jobs/{job_id}.

Parameters

report_idpath · stringRequired

Body

pageIdstringRequired

The page: its UUID or numeric ID.

readsarray<object>Required

Example request body

{
  "pageId": "678AE2F0-1469-489E-AE28-B729A0000E51",
  "reads": [
    {
      "type": "declarativeChart",
      "id": "3976903A-10E2-4861-B202-A29CF2BD7531"
    },
    {
      "type": "dataTable",
      "id": "755B3D02-0153-4031-BE24-73E1DB250E5B",
      "options": {
        "pageIndex": 0,
        "pageSize": 50
      }
    }
  ]
}

Response 200 (application/x-ndjson)

One NDJSON line.

keyintegerOptional

statusintegerOptional

dataobjectOptional

donebooleanOptional

Example response

{
  "key": 0,
  "status": 200,
  "data": {
    "visualUid": "3976903A-10E2-4861-B202-A29CF2BD7531",
    "sql_data": {
      "columns": [
        "Category",
        "Spend"
      ],
      "rows": [
        [
          "Groceries",
          "27711.43"
        ]
      ],
      "column_metadata": [
        {
          "name": "Spend",
          "type_code": "DECIMAL(38,2)",
          "valueEncoding": "decimal-string"
        }
      ]
    }
  }
}

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

InspectFilters: the report's filters, and with pageId the page's and each of its native visuals', with the value that applies to you. sorts lists your own table sorts (the page's; every page's without pageId). differs is true when any of your values in this report differs from its default, or you sort a table yourself. Viewers don't see hidden filters. filterRevision is what PUT /api/filters sends back.

Parameters

reportIdquery · stringRequired

pageIdquery · stringOptional

The page's UUID; omit for the report's filters only.

Response 200

filtersarray<object>Optional

sortsarray<object>Optional

differsbooleanOptional

filterRevisionintegerOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

UpdateFilters: add (filterUid null), change or remove filters (report design; Edit access, and report Edit for report scope). A filter's field and scope are fixed. A new default keeps the values people set themselves; changing kind, locked or hidden, or removing a filter, deletes everyone's values for it. filterRevision is the one GET /api/filters returned; if the filters changed since, nothing is saved (409 filter_conflict).

Body

reportIdstringRequired

filtersarray<object>Required

removearray<string>Required

filterRevisionintegerRequired

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "filterRevision": 12,
  "remove": [],
  "filters": [
    {
      "filterUid": null,
      "scope": "page",
      "target": "678ae2f0-1469-489e-ae28-b729a0000e51",
      "fieldUid": "6f1d2c9a8b7e4f30a1c5d9e2b4f7a8c1",
      "kind": "basic",
      "default": {
        "values": [
          "Dining",
          "Groceries"
        ],
        "exclude": false
      },
      "locked": false,
      "hidden": false,
      "label": null
    }
  ]
}

Response 200

filtersarray<object>Optional

removedarray<string>Optional

filterRevisionintegerOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

A field's members on a page (and visual), under your filters there without the filter being edited (filterUid). (Blank) is null. A measure answers manualEntryOnly: true with no values. Report access; with access to the page only, the members of a filter you see on it (filterUid), as your page reads them.

Parameters

reportIdquery · stringRequired

pageIdquery · stringRequired

The page's UUID.

fieldUidquery · stringRequired

visualUidquery · stringOptional

filterUidquery · stringOptional

The filter being edited.

qquery · stringOptional

Search text (contains, ignoring case).

offsetquery · integerOptional

limitquery · integerOptional

Response 200

fieldUidstringOptional

fieldstringOptional

valuesarray<value>Optional

manualEntryOnlybooleanOptional

offsetintegerOptional

limitintegerOptional

hasMorebooleanOptional

nextOffsetinteger | nullOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

UpdateMyView: your own filter values and table sorts in this report; only you see them, and they're kept between visits. Each value replaces yours for that filter (null shows all); each sort replaces yours for that table (direction null returns it to the table's own order, its query's sort); reset true first returns all of yours to the defaults. Locked and hidden filters need Edit access.

Body

reportIdstringRequired

valuesarray<object>Required

sortsarray<object>Optional

resetbooleanRequired

Response 200

filtersarray<object>Optional

sortsarray<object>Optional

differsbooleanOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Every entity, field, measure, relationship and source of the report, with the model revision that writes must send. Report SQL (POST /api/sql/execute) reads exactly this namespace.

Parameters

report_idpath · stringRequired

Response 200

statusstringOptional

modelobjectOptional

The report's semantic model: the namespace report SQL reads.

Report SQL (DuckDB) over the report's tables whose output columns become fields. It is static: computed from all rows of its tables; filters reach it only through its relationships. Saving runs the SQL once to set its fields and types; a column keeps its fieldUid while its name stays. The entity key cannot change. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.

Parameters

report_idpath · stringRequired

Body

entityKeystringRequired

Its report name: lowercase letters, digits and underscores.

sqlstringRequired

One SELECT or WITH statement over the report's tables.

entityNamestringOptional

Display name.

descriptionstringOptional

expectedModelRevisionintegerRequired

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

Example request body

{
  "entityKey": "customer_orders",
  "entityName": "Customer orders",
  "expectedModelRevision": 4,
  "sql": "SELECT o.customer_id, COUNT(*) AS orders FROM dbo_transactions o GROUP BY o.customer_id"
}

Response 200

statusstringOptional

modelobjectOptional

The report's semantic model: the namespace report SQL reads.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Removes it and its relationships, listed in removedRelationships. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.

Parameters

report_idpath · stringRequired

entity_keypath · stringRequired

Body

expectedModelRevisionintegerRequired

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

Response 200

statusstringOptional

modelobjectOptional

The report's semantic model: the namespace report SQL reads.

removedRelationshipsarray<object>Optional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Removes a field (by fieldUid): a definition, or a column of a tables-mode table, whose generated query then selects the others. A custom-SQL table's columns come from its SQL: remove one from its query. A table keeps at least one column. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.

Parameters

report_idpath · stringRequired

field_uidpath · stringRequired

Body

expectedModelRevisionintegerOptional

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

checkbooleanOptional

true removes nothing (a column only): the answer is 409 in_use with what the removal would remove or break, an empty readers list when nothing.

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Runs report SQL over the model and returns up to 200 rows with column details, for checking a model while editing it. For analysis use POST /api/sql/execute.

Parameters

report_idpath · stringRequired

Body

sqlstringRequired

Report SQL (DuckDB).

rowLimitintegerOptional

Example request body

{
  "sql": "SELECT region, COUNT(*) AS n FROM dbo_customers GROUP BY region",
  "rowLimit": 10
}

Response 200

columnsarray<string>Optional

rowsarray<array<value>>Optional

column_metadataarray<value>Optional

columnDetailsarray<object>Optional

Errors

400 Invalid input · 409 Conflict: re-read and reconcile. Every error has error, message and code.

The report's complete relationship collection, including edges between sources. Entity keys and output columns identify each end. A relationship change (added, removed, activated, deactivated or a new crossFilter) that would break a saved visual or page dataset, change what it shows (another join path), or stop or change a filter's reach to one is refused with code in_use and the readers (effect breaks, changes or stopsFiltering); confirm=true makes it anyway, and the result lists them (breaks). A key (to) end with duplicate or blank values is refused (code duplicate_key or blank_key), as is a both that gives a filter a second path (code ambiguous_both).

Parameters

report_idpath · stringRequired

Body

relationshipsarray<object>Required

expectedModelRevisionintegerRequired

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

entityLayoutsobjectOptional

Optional diagram positions by entity key.

Example request body

{
  "expectedModelRevision": 3,
  "relationships": [
    {
      "fromEntityKey": "dbo_transactions",
      "fromColumn": "customer_id",
      "toEntityKey": "dbo_customers",
      "toColumn": "customer_id",
      "isActive": true
    }
  ]
}

Response 200

statusstringOptional

modelobjectOptional

The report's semantic model: the namespace report SQL reads.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Removes the source's outputs from this report's model; the source stays attached, with no tables. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

Body

expectedModelRevisionintegerOptional

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

Response 200

statusstringOptional

Errors

400 Invalid input · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Entities, fields and relationships of one source, searchable and paged; lighter than the whole model.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

kindquery · stringOptional

queryquery · stringOptional

Search by model terminology.

fieldUidquery · array<string>Optional

offsetquery · integerOptional

limitquery · integerOptional

reportIdquery · stringOptional

Compatibility path only: the report.

Response 200

statusstringOptional

itemsarray<object>Optional

totalintegerOptional

offsetintegerOptional

completebooleanOptional

nextOffsetinteger | nullOptional

modelRevisionintegerOptional

snapshotVersionstringOptional

missingFieldUidsarray<string>Optional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Replaces this source's definitions: send every definition to keep (with its definitionId) plus new ones. Each is validated against the source before saving; a definition sent with its definitionId and a new aliasName is renamed and keeps its fieldUid. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules. Edit access.

Use a measure in report SQL through its entity: SELECT t."Total Spend" FROM dbo_transactions t.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

Body

definitionsarray<value | value>Required

expectedModelRevisionintegerOptional

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

Example request body

{
  "expectedModelRevision": 2,
  "definitions": [
    {
      "aliasName": "Total Spend",
      "description": "Sum of absolute debit amounts, excluding internal transfers.",
      "sqlExpression": "SUM(CASE WHEN direction = 'debit' AND type <> 'INTERNAL_TRANSFER' THEN ABS(signed_amount) ELSE 0 END)",
      "definitionType": "measure",
      "sourceEntityKey": "dbo_transactions",
      "sourceColumns": [
        "direction",
        "type",
        "signed_amount"
      ]
    }
  ]
}

Response 200

statusstringOptional

definitionsarray<value | value>Optional

modelobjectOptional

Errors

400 Invalid input · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

What a source editor needs: discovered schema, current selection and mode, saved entities and relationships, and entities suggested for the selected tables.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

Response 200

statusstringOptional

connectionobjectOptional

schemaobjectOptional

selectedSchemaobjectOptional

selectedTablesarray<string>Optional

sourceModestringOptional

modelobjectOptional

suggestedEntitiesarray<object>Optional

entitiesarray<object>Optional

relationshipsarray<object>Optional

Errors

400 Invalid input · 404 Not found. Every error has error, message and code.

Saves this source's part of the model: its mode, selection, entities and optionally its relationships and definitions. Sent without entities, each selected table with no query yet gets a full-table query; saved queries stay. Other reports using the same connection are unaffected. An entity key cannot change after saving. Sent entities can't be empty: removing a source's last table is removing its outputs (the source DELETE). Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules. A relationship change (added, removed, activated, deactivated or a new crossFilter) that would break a saved visual or page dataset, change what it shows (another join path), or stop or change a filter's reach to one is refused with code in_use and the readers (effect breaks, changes or stopsFiltering); confirm=true makes it anyway, and the result lists them (breaks). A key (to) end with duplicate or blank values is refused (code duplicate_key or blank_key), as is a both that gives a filter a second path (code ambiguous_both). Edit access.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

Body

sourceModestringOptional

tables: entities read whole tables; custom_sql: authored queries.

enum: ["tables","custom_sql"]

selectedTablesarray<string>Optional

Tables to model, as discovered (dbo.transactions). Sent without entities, each one with no query yet gets one, and the saved queries stay.

selectedSchemaobjectOptional

tables mode: the selection; columns come from discovery.

entitiesarray<object>Optional

Replaces this source's entities.

relationshipsarray<object>Optional

Relationships within this source.

definitionsarray<value | value>Optional

This source's reusable fields and measures.

descriptionstring | nullOptional

expectedModelRevisionintegerOptional

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

finalizeConnectionbooleanOptional

Mark the source configured (the editor's Save).

Example request body

{
  "sourceMode": "tables",
  "selectedTables": [
    "dbo.customers",
    "dbo.transactions"
  ],
  "selectedSchema": {
    "tables": {
      "dbo.customers": {},
      "dbo.transactions": {}
    }
  },
  "finalizeConnection": true,
  "expectedModelRevision": 1
}

Response 200

statusstringOptional

modelobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Runs a native-dialect entity query (or a saved entity, by entityKey) on the source and returns the first rows and typed columns, without saving.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

Body

entitySqlQuerystringOptional

Native-dialect SELECT.

entityKeystringOptional

Or a saved entity.

rowLimitintegerOptional

Example request body

{
  "entitySqlQuery": "SELECT TOP 10 * FROM dbo.transactions",
  "rowLimit": 10
}

Response 200

statusstringOptional

previewobjectOptional

Errors

400 Invalid input · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Rediscovers the cube's columns and measures as the caller: existing fields keep their names, new ones are added, removed ones disappear. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.

Parameters

report_idpath · stringRequired

connection_idpath · integerRequired

Body

expectedModelRevisionintegerOptional

The model revision you inspected. A stale revision answers 409 model_conflict.

minimum: 0

confirmbooleanOptional

true makes the change after 409 in_use.

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Connections the caller owns, whether or not a report uses them. Credentials are never returned.

Response 200

idintegerOptional

Connection ID.

ownerUserIdstringOptional

namestringOptional

serverTypestringOptional

authTypestring | nullOptional

serverNamestringOptional

Empty for uploaded-file connections.

databaseNamestring | nullOptional

connectionTypestring | nullOptional

enum: ["database","api","file"]

fileTypestring | nullOptional

createdAtstring | nullOptional

For the connection's owner (anyone else: 404): where its credentials go (recipients: host, port, account, token endpoint, provider) and which its sign-in takes (fields: who signs in, the user name or client ID, then the secrets), never their values. credentials is set or missing, null when the sign-in takes none.

Parameters

connection_idpath · integerRequired

Response 200

connectionIdintegerOptional

namestringOptional

typestring | nullOptional

authTypestring | nullOptional

databaseNamestring | nullOptional

credentialsstring | nullOptional

enum: ["set","missing"]

recipientsarray<object>Optional

fieldsarray<object>Optional

readerSignInbooleanOptional

Each reader signs in with their own account.

Errors

404 Not found. Every error has error, message and code.

For the connection's owner (anyone else: 404): connects with its saved settings and credentials and rediscovers its tables, as the TestConnection tool does. An API provider is checked as configured (recognized, its key present), without calling it.

Parameters

connection_idpath · integerRequired

Response 200

connectionIdintegerOptional

okbooleanOptional

checkedstringOptional

enum: ["source","configuration"]

tablesintegerOptional

Tables discovered.

modelobjectOptional

Analysis Services: the model's cube and counts.

needsCredentialsbooleanOptional

credentialsUrlstringOptional

errorstringOptional

The source's error, without credentials.

sourceAuthobjectOptional

A reader must sign in.

Errors

404 Not found. Every error has error, message and code.

The one create: saves a source connection owned by the caller, and attaches it to reportId when given. It does not connect (except an Analysis Services model, discovered as it is attached): test it (POST /api/connections/{connection_id}/test) or list its tables (POST /get-schema). Add the source to the report's data model to query it. In production, a server whose address is private (a private network, loopback, link-local or cloud metadata address) is refused when Unity connects.

Body

reportIdstringOptional

Attach to this report (Edit access).

serverTypestringRequired

Source kind; fixed once created.

enum: ["SQLServer","Snowflake","Databricks","AnalysisServices","API"]

serverNamestringRequired

Server or host (SQL Server: host[,port]; Snowflake: account; API: the provider, FRED, WORLDBANK or USCENSUS).

databaseNamestringOptional

Database, catalog, or Analysis Services model.

authTypestringOptional

How Unity signs in. SQL Server: UserPassAuth (SQL login), EntraPassword, EntraServicePrincipal (username = client ID, password = secret), EntraBrowser. Snowflake: UserPassAuth, KeyPairAuth (privateKey), OAuthClientCredentials, SnowflakeOAuth. Databricks: DatabricksEntraServicePrincipalSecret (default), DatabricksEntraServicePrincipalCert, DatabricksEntraUserSSO (databricksAccessToken), DatabricksEntraBrowser, DatabricksOAuth. Analysis Services: AASInteractive, EntraServicePrincipal, AASServicePrincipalCertificate, EntraPassword. API providers: ApiKey. Browser methods (EntraBrowser, SnowflakeOAuth, DatabricksEntraBrowser, DatabricksOAuth, AASInteractive) sign each reader in through the browser application and cannot complete headlessly. Server-identity methods (WindowsAuth, EntraIntegrated, EntraManagedIdentity) need a platform administrator.

enum: ["UserPassAuth","EntraPassword","EntraServicePrincipal","EntraBrowser","EntraIntegrated","EntraManagedIdentity","WindowsAuth","KeyPairAuth","OAuthClientCredentials","SnowflakeOAuth","DatabricksEntraServicePrincipalSecret","DatabricksEntraServicePrincipalCert","DatabricksEntraUserSSO","DatabricksEntraBrowser","DatabricksOAuth","AASInteractive","AASServicePrincipalCertificate","ApiKey"]

usernamestringOptional

Login.

clientIdstringOptional

Client (application) ID of a service principal.

passwordstringOptional

Password, API key, client secret or access token. Stored encrypted; never returned.

portintegerOptional

connectionNamestringOptional

Display name; generated from server and database when omitted, numbered when taken.

apiKeystringOptional

API providers: the provider's key.

accountstringOptional

Snowflake account.

warehousestringOptional

Snowflake warehouse.

schemaNamestringOptional

Snowflake schema.

rolestringOptional

Snowflake role.

privateKeystringOptional

Snowflake key-pair private key (PEM).

privateKeyPassphrasestringOptional

oauthClientIdstringOptional

oauthClientSecretstringOptional

oauthTokenUrlstringOptional

oauthScopestringOptional

httpPathstringOptional

Databricks SQL warehouse HTTP path.

databricksSchemastringOptional

Databricks schema.

tenantIdstringOptional

Microsoft Entra tenant.

databricksClientIdstringOptional

databricksClientSecretstringOptional

databricksAccessTokenstringOptional

Databricks personal access token.

analysisServicesOptionsobjectOptional

Analysis Services sign-in options (tenant, client, endpoint).

Example request body

{
  "serverType": "SQLServer",
  "serverName": "sql.example.com",
  "databaseName": "Sales",
  "authType": "UserPassAuth",
  "username": "unity_reader",
  "password": "********",
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82"
}

Response 201

statusstringOptional

messagestringOptional

connectionobjectOptional

Example response

{
  "status": "success",
  "message": "Connection created successfully",
  "connection": {
    "id": 31,
    "name": "SQLServer - sql.example.com - Sales",
    "serverType": "SQLServer",
    "serverName": "sql.example.com",
    "databaseName": "Sales"
  }
}

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Reports the caller can open that use the connection; others are only counted. A report being deleted no longer uses it: deletingReports names those the caller can open.

Parameters

connection_idpath · stringRequired

Response 200

statusstringOptional

affectedReportsarray<object>Optional

otherReportCountintegerOptional

deletingReportsarray<object>Optional

Errors

400 Invalid input · 404 Not found. Every error has error, message and code.

Deletes a connection the caller owns. While reports use it the answer is 409 connection_in_use naming them; confirm=true deletes it anyway and those reports show an error until an editor replaces the source. A connection an organization's report uses is never deleted this way (409 company_source_in_use, even with confirm): detach it from that report first.

Parameters

connection_idpath · stringRequired

confirmquery · stringOptional

Response 200

statusstringOptional

messagestringOptional

Errors

400 Invalid input · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Connections attached to the report, with each one's model state.

Parameters

report_idpath · stringRequired

Response 200

connectionIdintegerOptional

namestringOptional

serverTypestringOptional

Errors

403 Scope, access or subscription. Every error has error, message and code.

Edit access to the report and access to the connection. Then add its outputs to the report's data model (PUT /api/reports/{report_id}/data-model/sources/{connection_id}).

Body

reportIdstringRequired

connectionIdintegerRequired

Response 200

statusstringOptional

messagestringOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Removes the source and its model outputs from the report. Removing a field also removes the calculated fields, measures and relationships that use it. When anything reads what a write removes, or SQL names what it renames, the write is refused with code in_use (HTTP 409) and the readers (kind, title, id, pageId, page, effect); confirm=true makes it anyway, and the result lists what went with it (removedWith) and what now shows an error (breaks). Documentation topic connections has the full rules.

Body

reportIdstringRequired

connectionIdintegerRequired

confirmbooleanOptional

true makes the change after 409 in_use.

Response 200

statusstringOptional

messagestringOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Changes the given settings of a connection the caller owns; omitted settings keep their values. serverType and connectionType cannot change. An uploaded file's connection only renames. An API key may change only connectionName: other settings and secrets change in Unity, signed in (403 otherwise); create a new connection instead.

Parameters

connection_idpath · stringRequired

Body

serverNamestringOptional

Server or host (SQL Server: host[,port]; Snowflake: account; API: the provider, FRED, WORLDBANK or USCENSUS).

databaseNamestringOptional

Database, catalog, or Analysis Services model.

authTypestringOptional

How Unity signs in. SQL Server: UserPassAuth (SQL login), EntraPassword, EntraServicePrincipal (username = client ID, password = secret), EntraBrowser. Snowflake: UserPassAuth, KeyPairAuth (privateKey), OAuthClientCredentials, SnowflakeOAuth. Databricks: DatabricksEntraServicePrincipalSecret (default), DatabricksEntraServicePrincipalCert, DatabricksEntraUserSSO (databricksAccessToken), DatabricksEntraBrowser, DatabricksOAuth. Analysis Services: AASInteractive, EntraServicePrincipal, AASServicePrincipalCertificate, EntraPassword. API providers: ApiKey. Browser methods (EntraBrowser, SnowflakeOAuth, DatabricksEntraBrowser, DatabricksOAuth, AASInteractive) sign each reader in through the browser application and cannot complete headlessly. Server-identity methods (WindowsAuth, EntraIntegrated, EntraManagedIdentity) need a platform administrator.

enum: ["UserPassAuth","EntraPassword","EntraServicePrincipal","EntraBrowser","EntraIntegrated","EntraManagedIdentity","WindowsAuth","KeyPairAuth","OAuthClientCredentials","SnowflakeOAuth","DatabricksEntraServicePrincipalSecret","DatabricksEntraServicePrincipalCert","DatabricksEntraUserSSO","DatabricksEntraBrowser","DatabricksOAuth","AASInteractive","AASServicePrincipalCertificate","ApiKey"]

usernamestringOptional

Login.

clientIdstringOptional

Client (application) ID of a service principal.

passwordstringOptional

Password, API key, client secret or access token. Stored encrypted; never returned.

portintegerOptional

connectionNamestringOptional

Display name; generated from server and database when omitted, numbered when taken.

apiKeystringOptional

API providers: the provider's key.

accountstringOptional

Snowflake account.

warehousestringOptional

Snowflake warehouse.

schemaNamestringOptional

Snowflake schema.

rolestringOptional

Snowflake role.

privateKeystringOptional

Snowflake key-pair private key (PEM).

privateKeyPassphrasestringOptional

oauthClientIdstringOptional

oauthClientSecretstringOptional

oauthTokenUrlstringOptional

oauthScopestringOptional

httpPathstringOptional

Databricks SQL warehouse HTTP path.

databricksSchemastringOptional

Databricks schema.

tenantIdstringOptional

Microsoft Entra tenant.

databricksClientIdstringOptional

databricksClientSecretstringOptional

databricksAccessTokenstringOptional

Databricks personal access token.

analysisServicesOptionsobjectOptional

Analysis Services sign-in options (tenant, client, endpoint).

Example request body

{
  "connectionName": "Sales warehouse"
}

Response 200

statusstringOptional

messagestringOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Connects with the saved connection's settings and credentials and lists its tables and columns, through its connector, saving them as its discovery. The connection's owner, or an editor of reportId when the connection belongs to it. Create connections with POST /api/connections/add. No /api prefix.

A source that needs the reader's own sign-in answers 409 with code source_auth_sign_in_required and a sourceAuth payload; sign in through the browser application.

Body

connectionIdintegerRequired

The connection whose tables to list.

reportIdstringOptional

Example request body

{
  "connectionId": 42,
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82"
}

Response 200

schemaobjectOptional

Tables, each with its columns and types.

selectedSchemaobjectOptional

connectionIdintegerOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 500 · 503 Unavailable or read stopped. Every error has error, message and code.

The tables and columns selected for a source in this report. No /api prefix.

Parameters

report_idpath · stringRequired

connectionIdquery · integerRequired

Response 200

statusstringOptional

selectedSchemaobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Parameters

query_idpath · integerRequired

Response 200

messagestringOptional

Errors

404 Not found. Every error has error, message and code.

Runs one read-only DuckDB query over the report's whole model: every entity of every source, joins across sources, model fields and measures (t."Total Spend"). Name each entity by its entity key alone, as the model lists it, with no schema (FROM dbo_transactions); case is ignored. Writes, commands and multiple statements are refused. Unity adds LIMIT rowLimit when the outermost query has none. Saved report filters do not apply here.

A read still running after the synchronous wait answers 202 with {readJob}: poll GET /api/read-jobs/{job_id}.

A name that is not in the model answers 400 naming it and the closest entity keys. A table name, display name or schema-qualified name is not a name.

Body

reportIdstringRequired

sqlQuerystringRequired

Report SQL (DuckDB).

rowLimitintegerOptional

Rows to return when the query has no LIMIT of its own.

default: 1000 minimum: 1

skipLimitbooleanOptional

Return every row (within Unity's result bound) instead of rowLimit.

default: false

connectionIdintegerOptional

Compatibility hint; the report model decides the sources.

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "sqlQuery": "SELECT c.region, COUNT(*) AS n, t.\"Total Spend\" AS spend FROM dbo_transactions t JOIN dbo_customers c ON c.customer_id = t.customer_id GROUP BY 1 ORDER BY 1",
  "rowLimit": 100
}

Response 200

Example response

{
  "columns": [
    "region",
    "n",
    "spend"
  ],
  "rows": [
    [
      "East",
      71,
      "14520.11"
    ]
  ],
  "column_metadata": [
    {
      "name": "region",
      "type_code": "VARCHAR",
      "valueEncoding": "string"
    },
    {
      "name": "n",
      "type_code": "BIGINT",
      "valueEncoding": "big-integer"
    },
    {
      "name": "spend",
      "type_code": "DECIMAL(38,2)",
      "valueEncoding": "decimal-string"
    }
  ],
  "limitApplied": true,
  "rowLimit": 100
}

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 503 Unavailable or read stopped. Every error has error, message and code.

Keeps a named query with a report, in your saved queries (SQL Playground).

Body

reportIdstringRequired

namestringRequired

sqlQuerystringRequired

Response 201

idintegerOptional

namestringOptional

messagestringOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Your saved queries across reports, newest first.

Response 200

idintegerOptional

namestringOptional

sqlQuerystringOptional

reportIdstringOptional

reportNamestringOptional

createdAtstringOptional

202 with {readJob} (state and progress) while the read runs; afterwards the original operation's own response and status, once (collecting it removes the job). Poll at least every 45 seconds or the read is abandoned. 404 read_job_gone: the job ended, was collected, or its server restarted; start the read again. A stopped read answers 503 read_stopped with its reason.

Read jobs belong to the account that started them.

Parameters

job_idpath · stringRequired

Response 200

The original operation's response.

Errors

404 Not found · 503 Unavailable or read stopped. Every error has error, message and code.

Stops your read; it never undoes saved changes.

Parameters

job_idpath · stringRequired

Response 200

cancelledbooleanOptional

Whether a running job was found.

Parameters

datachat_idpath · integerRequired

Body

reportIdstringRequired

Response 200

last_seen_message_idinteger | nullOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Browser latency telemetry.

Response 200

Platform administrators: recent assistant runs with what entered their context.

Parameters

reportIdquery · stringOptional

offsetquery · integerOptional

entryquery · stringOptional

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

The guides Unity's assistant reads, from the running deployment: how report SQL, the model, visuals, HTML pages, files and testing work. Give these to your own AI.

Parameters

topicquery · stringOptional

Response 200

versionstringOptional

Content version.

topicstringOptional

titlestringOptional

markdownstringOptional

The guide (topics).

sourcestringOptional

topicsarray<object>Optional

With topic index.

Errors

400 Invalid input. Every error has error, message and code.

Queues a run of Unity's own assistant in one of your conversations (POST /api/datachats/add creates one) and answers 202 at once. The assistant inspects, queries and, with Edit access, changes the report through its tools; with View access it only reads. One run per conversation at a time (409 returns the active run). Requires an active subscription.

To control Unity with your own AI instead, call the same tools directly: GET /api/reports/{report_id}/tools, or connect an MCP client to /mcp.

Body

reportIdstringRequired

dataChatIdintegerRequired

The conversation's DataChatID.

user_inputstringRequired

The request, up to 50,000 characters.

maxLength: 50000

clientRequestIdstringOptional

Deduplicates a retried submission.

maxLength: 64

modestringOptional

enum: ["data_chat"] default: "data_chat"

layoutContextobjectOptional

Optional: pageId the user is on, selected visuals, referenceFiles [{id}] to attach report files (report Edit, Admin or Owner only; anyone else is refused 403).

attachmentsarray<object>Optional

Optional images.

Example request body

{
  "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
  "dataChatId": 37,
  "user_input": "Summarize spending by category and add a bar chart to the Spending page.",
  "clientRequestId": "run-spending-summary-1"
}

Response 202

runvalueOptional

createdbooleanOptional

False when clientRequestId matched an earlier run.

timingsobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Parameters

run_idpath · stringRequired

Response 200

runvalueOptional

Errors

404 Not found. Every error has error, message and code.

Platform administrators: one run's context receipts (export=json for a download).

Parameters

run_idpath · stringRequired

exportquery · stringOptional

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Parameters

run_idpath · stringRequired

digestpath · stringRequired

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

view=conversation: the run and its conversation events after afterSequence (messages, tool activity, answers), plus a cursor for the next poll; works while queued. Without view: stored events and tool_calls (each tool's arguments and result) of an initialized run.

Parameters

run_idpath · stringRequired

viewquery · stringOptional

afterSequencequery · integerOptional

Return events after this sequence (the last cursor).

Response 200

runvalueOptional

eventsarray<object>Optional

cursorintegerOptional

With view=conversation.

tool_callsarray<object>Optional

Errors

400 Invalid input · 404 Not found. Every error has error, message and code.

A queued run is cancelled at once; a running run stops its future work and a running read promptly. A write in progress finishes and keeps its receipt. Nothing is rolled back.

Parameters

run_idpath · stringRequired

Response 200

runvalueOptional

Errors

403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Server-sent events for a run executing on the serving worker; resume with afterSequence or Last-Event-ID. data: {"fallback":true} means poll the events endpoint instead (another worker, a finished run, or stream capacity). A browser EventSource cannot send a bearer header.

Parameters

run_idpath · stringRequired

afterSequencequery · integerOptional

Response 200 (text/event-stream)

Server-sent events.

Errors

400 Invalid input · 404 Not found. Every error has error, message and code.

Multipart form: reportId and an audio file. Returns the text for a message.

Body (multipart/form-data)

reportIdstringOptional

audiostringOptional

Response 200

textstringOptional

Errors

400 Invalid input · 413 Too large · 415 Unsupported media type. Every error has error, message and code.

Your conversations in a report with their latest run state and unread counts.

Parameters

reportIdquery · stringRequired

Response 200

sessionsarray<object>Optional

summaryobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

The tools Unity's own assistant uses, offered to your AI for this report: each with its description, access (view or edit), readOnly, and exact JSON input schema. available says whether you can call it here (Edit access and a workspace:write key for tools that change the report); tools your access could never call are left out. A report Viewer (or Edit content person) who also holds Edit on some pages can call the tools that change those pages (editablePages), and only for those pages. Give these to your model as function definitions; call them with POST /api/reports/{report_id}/tools/{name}.

Parameters

report_idpath · stringRequired

Response 200

reportIdstringOptional

accessLevelstringOptional

contentEditbooleanOptional

True for an Edit content share (View access: the tools are a Viewer's).

toolsarray<object>Optional

editablePagesarray<object>Optional

Present for a Viewer who holds Edit on pages: the pages the change tools work on (every other page, and every report-level action, stays a Viewer's).

Errors

403 Scope, access or subscription. Every error has error, message and code.

Runs one tool as you, exactly as Unity's assistant would: the arguments are validated against its schema, your report access and key scope apply, and the result is what the assistant would receive. A change returns its receipt and reportVersion, the report version it made: ListReportVersions lists it and RestoreReportVersion brings back the version before it. View tools accept a workspace:read key; tools that change the report need workspace:write and Edit access. Parameters named *Json (also inside a list's items, and HTML operation) take the JSON as text or as the value.

The HTTP status says whether the call ran: 200 for an executed call (status success or error), 4xx when it did not (unknown tool 404 tool_not_found, invalid arguments 422 invalid_tool_arguments with the failing field, access or scope 403).

Parameters

report_idpath · stringRequired

namepath · stringRequired

Body

argumentsobjectRequired

The tool's arguments, per its inputSchema.

sessionIdstringOptional

Optional, up to 64 characters: groups your calls into one recorded session (an external assistant run without a conversation).

maxLength: 64

Example request body

{
  "arguments": {
    "visuals": [
      {
        "pageId": "678AE2F0-1469-489E-AE28-B729A0000E51",
        "visualType": "dataCard",
        "definitionJson": {
          "title": "Total spend",
          "query": {
            "values": [
              {
                "name": "Spend",
                "field": "fld_0a1b2c3d4e5f60718293a4b5c6d7e8f9"
              }
            ]
          }
        }
      }
    ]
  },
  "sessionId": "my-agent-session-1"
}

Response 200

toolstringOptional

statusstringOptional

error: the tool ran and refused or failed; read result.error.

enum: ["success","error"]

resultobjectOptional

The tool's result as the assistant receives it.

imagesarray<object>Optional

Screenshots from preview tools (PreviewPage, PreviewFile, ...).

runIdstringOptional

callIdstringOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found · 422 Cannot be applied. Every error has error, message and code.

Parameters

report_idpath · stringRequired

namepath · stringRequired

Response 200

namestringOptional

descriptionstringOptional

accessstringOptional

enum: ["view","edit"]

readOnlybooleanOptional

The tool only reads: a workspace:read key may call it.

reacharray<string>Optional

availablebooleanOptional

unavailableReasonstringOptional

inputSchemaobjectOptional

The exact JSON Schema of the tool's arguments.

Errors

403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Connect any MCP client (Claude, ChatGPT, Cursor, Grok, your own agent) to Unity: Streamable HTTP transport, one JSON-RPC message per POST, answered with JSON; no session. Authenticate with a Unity API key (Authorization: Bearer). tools/list returns the agent tools you may call; tools/call runs one with the same validation, access, receipts and versions as POST /api/reports/{report_id}/tools/{name} (images come back as image content). resources/list offers Unity's guides (unity://docs/{topic}) and this API's OpenAPI document. With ?reportId= the server is bound to that report; without it every tool takes reportId, and ListReports and CreateReport are added.

A workspace:read key can list tools, read resources and call view tools; changing tools need workspace:write and Edit access on the report.

Claude Code: claude mcp add --transport http unity https://api.x4tech.org/mcp --header "Authorization: Bearer $UNITY_API_KEY".

Parameters

reportIdquery · stringOptional

Bind the server to one report.

Body

jsonrpcstringRequired

enum: ["2.0"]

idvalueOptional

Request ID; omitted for notifications.

methodstringRequired

enum: ["initialize","ping","tools/list","tools/call","resources/list","resources/read","resources/templates/list","prompts/list","notifications/initialized"]

paramsobjectOptional

Example request body

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "InspectReport",
    "arguments": {
      "reportId": "9af3fb53-34e2-4e88-a953-ffdecdeece82",
      "query": "",
      "kind": "page",
      "pageId": null,
      "visualKeys": [],
      "detail": false,
      "offset": 0,
      "limit": 20
    }
  }
}

Response 200

The JSON-RPC response; 202 with no body for a notification.

jsonrpcstringOptional

idvalueOptional

resultobjectOptional

errorobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Answers 405: this server sends no server-initiated messages; every response comes on its POST.

Response 405

The browser's inline chat-visual edits.

Response 200

Your conversation's messages, the actions its runs took (with change receipts) and its timeline, in one read. Conversations are private to their creator (404 otherwise).

Parameters

reportIdquery · stringRequired

dataChatIdquery · integerRequired

Response 200

messagesarray<object>Optional

actionsarray<object>Optional

projectionobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Body

reportIdstringRequired

dataChatIdintegerRequired

newNamestringRequired

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Deletes your conversation and its history (202: cleanup continues). Refused while a run is active.

Body

reportIdstringRequired

idintegerRequired

DataChatID.

Response 202

messagestringOptional

detailsobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found · 409 Conflict: re-read and reconcile. Every error has error, message and code.

The browser's Add to page of an inline chat preview.

Response 200

One page's source, registered datasets and visuals, filters and its version (`version`), which changes to it must send as baseVersion.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Response 200

An HTML page (or, for a report-wide read, every page the caller can see) with its version.

idstringOptional

Report ID.

reportIdstringOptional

Report ID.

pageIdstringOptional

The page (single-page projection).

namestringOptional

Report name.

versionintegerOptional

This page's version: send it as baseVersion (for a report-wide read, the highest page version).

pageVersionsobjectOptional

{pageUid: version} for every page in the document.

revisionScopestringOptional

enum: ["page"]

accessLevelstringOptional

documentobjectOptional

nativePagesarray<object>Optional

feedbackobjectOptional

updatedAtstring | nullOptional

scopestringOptional

Present for a page-only reader (page grants, no report access): the page is returned without queries, filters or renderer feedback.

enum: ["pages"]

dataContextstringOptional

An opaque fingerprint of the page's data definitions and the filters as they apply to you. Data responses and renderer feedback repeat it.

Errors

403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

The bytes of an asset the page's current content references as `unity-asset:<assetId>` (any part: HTML, visual HTML/CSS/script, registrations), for anyone who can open the page, including a page-only reader. An asset the page does not reference is refused, and nothing is listed: the report file library routes are for report Edit, Admin and Owner only.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

asset_idpath · stringRequired

The 64-character asset ID in a `unity-asset:` reference.

Response 200 (image/png)

Errors

400 Invalid input · 403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

Applies one document operation as one saved version of this page (a report version: GET /api/reports/{reportId}/versions lists it). A baseVersion older than the page's version still applies when what the operation reads or writes is the same in that version and now (element identities aside); otherwise it answers 409 revision_conflict with the page's currentVersion and the changes since, and nothing is saved. A repeated clientRequestId returns the first outcome.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

baseVersionintegerRequired

operationobjectRequired

One atomic change to one HTML page. The html-authoring guide (GET /api/agent/documentation?topic=html-authoring) describes each kind, the renderer API (unity.bind, unity.query) and examples.

labelstringOptional

History label.

clientRequestIdstringOptional

A UUID or short string naming this command: a retry with the same ID and body answers with the original outcome instead of saving twice.

Example request body

{
  "baseVersion": 1,
  "label": "Headline",
  "operation": {
    "kind": "patch_source",
    "part": "html",
    "edits": [
      {
        "find": "Your data.<br>A different perspective.",
        "replace": "Spending at a glance",
        "expectedMatches": 1
      }
    ]
  }
}

Response 200

The page as saved and the change receipt.

idstringOptional

Report ID.

reportIdstringOptional

Report ID.

pageIdstringOptional

The page (single-page projection).

namestringOptional

Report name.

versionintegerOptional

This page's version: send it as baseVersion (for a report-wide read, the highest page version).

pageVersionsobjectOptional

{pageUid: version} for every page in the document.

revisionScopestringOptional

enum: ["page"]

accessLevelstringOptional

documentobjectOptional

nativePagesarray<object>Optional

feedbackobjectOptional

updatedAtstring | nullOptional

scopestringOptional

Present for a page-only reader (page grants, no report access): the page is returned without queries, filters or renderer feedback.

enum: ["pages"]

dataContextstringOptional

An opaque fingerprint of the page's data definitions and the filters as they apply to you. Data responses and renderer feedback repeat it.

receiptobjectOptional

Receipt: {resourceType: 'html', label, mutation, change: {before: {pageUid}, after: {pageUid, version}}, pageVersion, changedPageIds, verificationKeys}.

changedElementsarray<string>Optional

element_ops: the uids written.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 413 Too large · 422 Cannot be applied. Every error has error, message and code.

What `unity.save(element, text)` in an HTML page sends. Writes `text` as plain text into the element whose `data-unity-id` is `uid`, which the page's editors marked `data-unity-writable` (a text-only element), as one new attributed version of the page (ActorKind `page_script`, the label 'Saved text from the page'); every viewer sees it through the live feed. Needs Edit content or above on the page: report Admin/Owner/Edit, a page Edit or Edit content grant, or a report share at Edit content (HTML pages open to everyone). A person who can only view is refused `view_only`; public links have no save route. At most 20,000 characters, 30 saves a minute per person per page. Refusals: 403 `view_only` / `no_access` / `page_unavailable`, 422 `not_writable` (no marker, not a text-only element, unknown uid, or the page has no element identities) / `too_long` / `invalid_text` (a report image reference), 409 `page_held` (another person is editing: {holder}) / `changed` (the element no longer holds previousText: someone changed it; {currentVersion}), 429 `rate_limited` ({retryAfter}, Retry-After). Changes to other elements never refuse it. A repeated clientRequestId answers the first outcome.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

uidstringRequired

The element's data-unity-id.

textstringRequired

Plain text, up to 20,000 characters.

previousTextstringRequired

The element's text as the saver's page last applied it (after its own earlier saves; not a change held back while they type).

clientRequestIdstringRequired

A UUID or short string naming this command: a retry with the same ID and body answers with the original outcome instead of saving twice.

Example request body

{
  "uid": "k3m9xq",
  "text": "Approved",
  "previousText": "Pending",
  "clientRequestId": "a-new-id-per-save"
}

Response 200

savedbooleanOptional

pageIdstringOptional

uidstringOptional

versionintegerOptional

The page version holding the text.

appliedbooleanOptional

False when the element already held exactly this text (no new version).

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 422 Cannot be applied · 429 Rate limited. Every error has error, message and code.

Every HTML page the caller can see, with `pageVersions` ({pageUid: version}).

Parameters

report_idpath · stringRequired

Response 200

An HTML page (or, for a report-wide read, every page the caller can see) with its version.

idstringOptional

Report ID.

reportIdstringOptional

Report ID.

pageIdstringOptional

The page (single-page projection).

namestringOptional

Report name.

versionintegerOptional

This page's version: send it as baseVersion (for a report-wide read, the highest page version).

pageVersionsobjectOptional

{pageUid: version} for every page in the document.

revisionScopestringOptional

enum: ["page"]

accessLevelstringOptional

documentobjectOptional

nativePagesarray<object>Optional

feedbackobjectOptional

updatedAtstring | nullOptional

scopestringOptional

Present for a page-only reader (page grants, no report access): the page is returned without queries, filters or renderer feedback.

enum: ["pages"]

dataContextstringOptional

An opaque fingerprint of the page's data definitions and the filters as they apply to you. Data responses and renderer feedback repeat it.

Errors

403 Scope, access or subscription · 404 Not found. Every error has error, message and code.

The browser renderer's diagnostics; `revision` is the page's version.

Parameters

report_idpath · stringRequired

Response 200

Reads the page's registered visual queries with saved and interactive filters and returns their results: columns, rows, records, outputs and generatedSql. A dataset saved as SQL answers code legacy_sql. The browser renderer calls it; an agent previews pages with the PreviewPage tool.

Parameters

report_idpath · stringRequired

page_idpath · stringRequired

The HTML page UUID.

statequery · stringOptional

JSON runtime state, at most 16,000 characters: a click (interaction: {visualId, dataId, fields: [{column, value}]}, each column a group output of that dataset's query; Unity builds its filters from the stored query), a table window, targets.

targetquery · stringOptional

One dataset or visual ID.

Response 200

versionintegerOptional

contextobjectOptional

resultsobjectOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile · 503 Unavailable or read stopped. Every error has error, message and code.

NDJSON: {context, keys}, then {results} as datasets finish, {jobs} for reads continuing as read jobs, then {done: true}.

Parameters

report_idpath · stringRequired

page_idpath · stringRequired

statequery · stringOptional

Response 200 (application/x-ndjson)

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

Reads a visual query under the report's filters (and the page's, with a pageId) as they apply to you and returns a sample with its outputs and generatedSql, to design datasets. Edit access.

Parameters

report_idpath · stringRequired

Body

queryobjectRequired

A visual query, as a dataset takes it.

pageIdstringOptional

filtersarray<value>Optional

Dataset filters for this query.

Response 200

Errors

400 Invalid input · 403 Scope, access or subscription. Every error has error, message and code.

An HTML page: starts or joins the caller's editing session (409 page_held when another person holds it). A native page: leases the chart named by `target` (`visual:<id>`; 409 element_held when another person holds it). A browser session only: an API key, MCP or OAuth token answers 403 browser_session_required. A browser sends the tab's edit session as the X-Unity-Edit-Session header on every write and on the hold and presence routes, so they start or join the caller's session or lease (an API caller's credential is a one-shot participant that never extends it).

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

targetstringOptional

Native pages: `visual:<visual uid>`. HTML pages: omit or `page`.

Response 200

One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live.

pageUidstringOptional

targetstringOptional

`page` for an HTML page's session; `visual:<uid>` for a native page's element lease.

modestringOptional

`session`: an HTML page's editing session (45 s from the last renewal, 10 minutes from the last write); `lease`: a chart on a native page (10 s from the last activity); `oneshot`: held for one write.

enum: ["session","lease","oneshot"]

holdIdstringOptional

Only the holder sees it: send it with every renew, leave and answer (a stale one answers 409 hold_lost).

holderobjectOptional

sincestringOptional

kindsarray<string>Optional

Who is acting under the hold.

minebooleanOptional

The caller is the holder.

expiresAtstringOptional

The hold lapses then unless a participant renews.

participantsarray<object>Optional

The holder's live participants (holder only).

takeoverRequestedbooleanOptional

takeoverRequestedByobject | nullOptional

takeoverDeadlinestring | nullOptional

Server time at which an unanswered request is granted.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Ends only this session's participation; the lease ends when no participant remains. 409 hold_lost for a stale `holdId`. A browser session only: an API key, MCP or OAuth token answers 403 browser_session_required.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

holdIdstringRequired

Response 200

releasedbooleanOptional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

Renews this session's participation (every 30 s while the tab is focused, every 4 s while a chart's drawer holds unsaved edits). 409 hold_lost when `holdId` is no longer current (lapsed, ended at its limit, taken over or released); the response then carries the page's session. Renewing is not a write: it does not move the 10 minute (page) or 5 minute (chart) limit. A browser session only: an API key, MCP or OAuth token answers 403 browser_session_required.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

holdIdstringRequired

Response 200

One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live.

pageUidstringOptional

targetstringOptional

`page` for an HTML page's session; `visual:<uid>` for a native page's element lease.

modestringOptional

`session`: an HTML page's editing session (45 s from the last renewal, 10 minutes from the last write); `lease`: a chart on a native page (10 s from the last activity); `oneshot`: held for one write.

enum: ["session","lease","oneshot"]

holdIdstringOptional

Only the holder sees it: send it with every renew, leave and answer (a stale one answers 409 hold_lost).

holderobjectOptional

sincestringOptional

kindsarray<string>Optional

Who is acting under the hold.

minebooleanOptional

The caller is the holder.

expiresAtstringOptional

The hold lapses then unless a participant renews.

participantsarray<object>Optional

The holder's live participants (holder only).

takeoverRequestedbooleanOptional

takeoverRequestedByobject | nullOptional

takeoverDeadlinestring | nullOptional

Server time at which an unanswered request is granted.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

`hold` is an HTML page's editing session (null when free or native). `leases` are the live element leases of a native page (a chart is leased while someone drags or resizes it, has unsaved edits in its edit drawer, or their assistant is changing it, and never more than 5 minutes after it was taken or last written; the caller's own are flagged `mine`). `presence` lists the people on the page and what each has selected. `granularity` is `page` (HTML: one editor at a time) or `element` (native: everyone edits at once; a chart is protected for about 10 s after the activity stops). The same for HTML and native pages.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Response 200

granularitystringOptional

enum: ["page","element"]

holdobject | nullOptional

One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live.

leasesarray<object>Optional

presencearray<object>Optional

Errors

403 Scope, access or subscription. Every error has error, message and code.

An HTML page: asks the holder to hand the page over: granted when the holder releases, when 30 s pass unanswered, or when the session ends. `force` (report Owner or Admin) takes it immediately. A takeover issues a new holdId, so the previous holder's requests answer 409 hold_lost. A native page has no takeover (409 page_kind_unsupported) unless `force` is set: a report Owner or Admin then ends the other people's chart leases (`target`: `visual:<id>` for one chart, else every lease on the page) and the answer is `{ended}`; anyone else gets 403. A browser session only: an API key, MCP or OAuth token answers 403 browser_session_required.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

forcebooleanOptional

targetstringOptional

Native pages with `force`: the chart whose lease to end.

Response 200

One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live.

pageUidstringOptional

targetstringOptional

`page` for an HTML page's session; `visual:<uid>` for a native page's element lease.

modestringOptional

`session`: an HTML page's editing session (45 s from the last renewal, 10 minutes from the last write); `lease`: a chart on a native page (10 s from the last activity); `oneshot`: held for one write.

enum: ["session","lease","oneshot"]

holdIdstringOptional

Only the holder sees it: send it with every renew, leave and answer (a stale one answers 409 hold_lost).

holderobjectOptional

sincestringOptional

kindsarray<string>Optional

Who is acting under the hold.

minebooleanOptional

The caller is the holder.

expiresAtstringOptional

The hold lapses then unless a participant renews.

participantsarray<object>Optional

The holder's live participants (holder only).

takeoverRequestedbooleanOptional

takeoverRequestedByobject | nullOptional

takeoverDeadlinestring | nullOptional

Server time at which an unanswered request is granted.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

The holder's answer: `release: true` hands the page to the requester (new holdId), `release: false` keeps editing and rejects the request. A browser session only: an API key, MCP or OAuth token answers 403 browser_session_required.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

Body

holdIdstringRequired

releasebooleanRequired

Response 200

One person's lease on a target of a page: an HTML page's editing session, or a chart of a native page. A participant (a browser tab, an assistant run, an API caller) is live for the mode's window after its last renewal (see `mode`); the lease ends when none is live.

pageUidstringOptional

targetstringOptional

`page` for an HTML page's session; `visual:<uid>` for a native page's element lease.

modestringOptional

`session`: an HTML page's editing session (45 s from the last renewal, 10 minutes from the last write); `lease`: a chart on a native page (10 s from the last activity); `oneshot`: held for one write.

enum: ["session","lease","oneshot"]

holdIdstringOptional

Only the holder sees it: send it with every renew, leave and answer (a stale one answers 409 hold_lost).

holderobjectOptional

sincestringOptional

kindsarray<string>Optional

Who is acting under the hold.

minebooleanOptional

The caller is the holder.

expiresAtstringOptional

The hold lapses then unless a participant renews.

participantsarray<object>Optional

The holder's live participants (holder only).

takeoverRequestedbooleanOptional

takeoverRequestedByobject | nullOptional

takeoverDeadlinestring | nullOptional

Server time at which an unanswered request is granted.

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.

The net change from `after` (the version the viewer shows) to the page's head, for anyone who can view the page: in-place patches addressed by `data-unity-id`, or `rebuild: true` asking the viewer to rebuild. It never reveals what happened in between: every patch is taken from the head markup. HTML pages only (a native page answers 400: its viewers follow the report liveness poll). `rebuild: false` carries patches addressed by `data-unity-id`: `attrs` (the element's full final attributes and start tag), `text` (text-only elements) and `children` (new inner HTML), at most 40 patches and 200 KB; `rebuild: true` asks the viewer to rebuild the page (reason: styles, script, visuals, data, filters, settings, unidentified, structure, too_large, unverified or history_unavailable: the version shown isn't in the report's versions). `after` must be between 1 and the head version. Answers are cached for 30 s.

Parameters

page_uidpath · stringRequired

The HTML page UUID.

afterquery · integerRequired

The page version the viewer shows.

Response 200

pageUidstringOptional

fromVersionintegerOptional

versionintegerOptional

rebuildbooleanOptional

reasonstringOptional

Why the viewer must rebuild; present when rebuild is true.

patchesarray<object>Optional

Errors

400 Invalid input · 403 Scope, access or subscription · 409 Conflict: re-read and reconcile. Every error has error, message and code.