API: Dashboards

Manage dashboards and their cards, bookmarks, and comments. All endpoints require authentication unless noted. 64 endpoints, 3 of them app only: an API key gets 403 there.

POST /api/comments

Create a comment

Request body (JSON)

Field	Type	Required	Description
resourceType	"dashboard" | "card" | "story"	yes
resourceId	string	yes
content	string	yes
parentId	string	no
context	object	no
kind	"comment" | "suggestion" | "ai"	no
mentions	array of string	no

Responses: 201 · 400 · 401 · 409

PUT /api/comments/{id}

Update a comment

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
content	string	yes

Responses: 200 · 400 · 401 · 404

DELETE /api/comments/{id}

Delete a comment

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 204 — No content · 401 · 404

PATCH /api/comments/{id}/resolve

Resolve or reopen a comment thread

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
resolved	boolean	yes

Responses: 200 · 400 · 401 · 404

GET /api/comments/{resourceType}/{resourceId}

List comments for a resource

Path parameters

Name	Type	Required	Description
resourceType	"dashboard" | "card" | "story"	yes
resourceId	string	yes

Query parameters

Name	Type	Required	Description
limit	integer	no
offset	integer	no

Responses: 200 · 400 · 401

GET /api/comments/story/{resourceId}/mentions/v1

Search active Story comment mention candidates with bounded continuation

Path parameters

Name	Type	Required	Description
resourceId	string	yes

Query parameters

Name	Type	Required	Description
q	string	no
after	string	no
sectionId	string	no
parentId	string	no

Responses: 200 · 400 · 401 · 404

GET /api/comments/story/{resourceId}/reader

Read current permitted Story comments with stable paging and native action permissions

Path parameters

Name	Type	Required	Description
resourceId	string	yes

Query parameters

Name	Type	Required	Description
limit	integer	no
cursor	string	no

Responses: 200 · 400 · 401 · 404

POST /api/content-reports

Report an Ask AI answer, an AI analysis or a comment for review

App only. An API key gets 403: A report comes from a person signed in to DataSquares, not from an API key.

Files a report against an item the caller can read — the same rule as reading it, in the caller’s workspace — with a reason and an optional note. The text is kept as it was. A repeat report of the same item by the same person returns the first report (200, repeated: true). A new report (201) is mailed for review to the content-report address (CONTENT_REPORT_TO: DataSquares, on the hosted service; the receipt’s reviewer says whose it is, or that there is none) and, for a comment, shown to the workspace admins who can open it without the reporter’s name; the comment’s author is never told. Signed-in people only: an API key is refused.

Request body (JSON)

Field	Type	Required	Description
targetType	"ai_answer" | "card_analysis" | "metric_analysis" | "comment" | "report_analysis" | "story_analysis"	yes	ai_answer (an Ask AI answer), card_analysis (an AI analysis of a dashboard card), metric_analysis (the AI explanation of a metric), report_analysis (the AI summary of a change between two runs of a saved report), story_analysis (the AI proposal of a Story section’s review of its numbers) or comment (on a dashboard, a card or a Story).
targetId	string	yes	The answer’s message id, the card’s id, the metric’s id, the report’s id, the Story section’s id or the comment’s id.
dashboardId	string	no	card_analysis only: the card’s dashboard.
storyId	string	no	story_analysis only: the section’s Story.
analysisKind	"explain" | "anomalies" | "forecast" | "influencers" | "summary" | "proposal"	no	The analysis targets only: which analysis was shown. A card’s: explain, anomalies, forecast, influencers or summary (the AI summary note it keeps); a metric’s: explain, anomalies, forecast or influencers; a report’s: explain; a Story section’s: proposal.
text	string	no	The analysis targets only: the AI text as shown (an analysis is not stored). An answer’s or a comment’s text is the server’s own copy.
reason	"offensive" | "harassment" | "sexual" | "harmful" | "misleading" | "spam" | "other"	yes
note	string	no
platform	"android" | "ios" | "macos" | "windows" | "web"	no
appVersion	string	no

Responses: 200 · 201 · 400 · 401 · 403 · 404

GET /api/dashboards

List dashboards (optionally filtered by stage)

Query parameters

Name	Type	Required	Description
includeDeleted	boolean	no
stage	string	no
publishedOnly	boolean	no
limit	integer	no
offset	integer	no
include	"viewerMeta"	no
omitLayout	boolean	no	Leave layout out of each row; thumbnail_url still points at the library thumbnail.

Responses: 200 · 400 · 401

POST /api/dashboards

Create a new dashboard

Request body (JSON)

Field	Type	Required	Description
name	string	yes
description	string	no
layout	string	no
theme	string	no

Responses: 201 · 400 · 401 · 409

GET /api/dashboards/{id}

Get dashboard by ID

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

PUT /api/dashboards/{id}

Update a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
description	string	no
layout	string	no
theme	string	no
filterState	string	no
isPublished	boolean	no

Responses: 200 · 400 · 401 · 404

DELETE /api/dashboards/{id}

Delete a dashboard (soft delete)

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

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 204 — No content · 401 · 404

GET /api/dashboards/{id}/access

List per-user access grants for a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/access

Grant a workspace member access to a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

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

Responses: 201 · 400 · 401 · 409

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

Revoke a dashboard access grant

Path parameters

Name	Type	Required	Description
id	string	yes
accessId	string	yes

Responses: 204 — No content · 401 · 404

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

Search workspace members to share a dashboard with

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
q	string	no

Responses: 200 · 400 · 401

GET /api/dashboards/{id}/ai-built

What the AI built on a dashboard

Whether the AI built the dashboard and which of its cards it added, and when, so each can say “AI-built”. conversationId names the conversation that built it only for the person whose conversation it is; nobody else can open it. A dashboard the AI built has no row for each card: its cards are the dashboard’s.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

GET /api/dashboards/{id}/bookmarks

List bookmarks for a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/bookmarks

Create a dashboard bookmark

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	yes
state	object	yes
isDefault	boolean	no
isPersonal	boolean	no

Responses: 201 · 400 · 401 · 409

GET /api/dashboards/{id}/cards

List cards in a dashboard

A card’s AI summary, and an AI snapshot card’s frozen chart, are left out for a caller row-level security restricts (or whose restriction cannot be checked); ai_narrative_withheld and snapshot_withheld then carry the reason.

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
pageId	string	no

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/cards

Add a card to a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
id	string	no
cardType	string	yes
title	string	no
description	string	no
position	object	yes
chartSpec	object	no
savedQueryId	string	no
compositeModelId	string	no
textContent	string	no
imageUrl	string	no
value	string	no
pageId	string	no

Responses: 201 · 400 · 401 · 409

PUT /api/dashboards/{id}/cards/{cardId}

Update a dashboard card

Path parameters

Name	Type	Required	Description
id	string	yes
cardId	string	yes

Request body (JSON)

Field	Type	Required	Description
cardType	string	no
title	string	no
description	string	no
position	object	no
chartSpec	object	no
savedQueryId	string | null	no
textContent	string	no
imageUrl	string	no
value	string	no
ordinal	integer	no
pageId	string	no

Responses: 200 · 400 · 401 · 404

DELETE /api/dashboards/{id}/cards/{cardId}

Delete a dashboard card

Path parameters

Name	Type	Required	Description
id	string	yes
cardId	string	yes

Responses: 204 — No content · 401 · 404

POST /api/dashboards/{id}/cards/{cardId}/summarize

Preview an AI summary of a card’s data, for you alone (AIX-12)

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

Reads the card’s model-backed rows through the governed pipeline as everyone who may read the summary sees them: under your row-level security, with sensitivity-labelled values masked (a card whose numbers use a labelled field as a value, a filter or a sort is refused, 400 SUMMARY_LABELLED_FIELD). Every row the card shows is read, up to 5000; it computes the facts the summary may quote, and writes 2-4 sentences around them with the AI service; a card that offers no computed fact is described from its first 50 rows. rowsRead is how many rows the summary was written from, and complete is false when the rest were left out. The preview is kept for you only; POST …/summarize/publish shows it to everyone. flags lists figures the AI typed that match no computed number. 503 AI_NOT_CONFIGURED when AI isn’t set up on this server; fail-closed RLS gate on the card’s source as on card-data.

Path parameters

Name	Type	Required	Description
id	string	yes
cardId	string	yes

Responses: 200 · 400 · 401 · 403 · 404 · 502 · 503

DELETE /api/dashboards/{id}/cards/{cardId}/summarize

Clear a card’s AI summary (AIX-12)

Path parameters

Name	Type	Required	Description
id	string	yes
cardId	string	yes

Responses: 204 — No content · 401 · 404

POST /api/dashboards/{id}/cards/{cardId}/summarize/publish

Show your previewed AI summary to everyone who opens the card (AIX-12)

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

Puts exactly the previewed text on the card, with when it was written and how many rows it read. Refuses a preview that is gone or not yours (404 SUMMARY_PREVIEW_GONE), more than a day old, of a card that changed since, or written before sensitivity-labelled values were masked in summaries (409 SUMMARY_PREVIEW_STALE). Uses no AI.

Path parameters

Name	Type	Required	Description
id	string	yes
cardId	string	yes

Request body (JSON)

Field	Type	Required	Description
draftId	string	yes

Responses: 200 · 400 · 401 · 403 · 404 · 409

PUT /api/dashboards/{id}/cards/batch

Batch-update dashboard cards (layout/spec) in one request

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
updates	array of object	yes

Responses: 200 · 400 · 401 · 404

POST /api/dashboards/{id}/cards/from-blend

Create a card from a cross-source blend

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
compositeModelId	string	yes
blendRun	object	yes	The run, as POST /api/composite-models/:id/execute takes it
chartType	string	no	The chart the card draws, as a query-backed card names it
columnMap	object	no	x, y[], series, value — result column names
title	string	no
position	object	no
pageId	string	no

Responses: 201 · 400 · 401 · 409

POST /api/dashboards/{id}/cards/from-query

Create a card from a saved query

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
savedQueryId	string	yes
title	string	no
position	object	no
pageId	string	no

Responses: 201 · 400 · 401 · 409

PUT /api/dashboards/{id}/cards/reorder

Reorder dashboard cards

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
cardIds	array of string	yes

Responses: 200 · 400 · 401 · 404

GET /api/dashboards/{id}/dataset-freshness

Freshness of the Warehouse datasets this dashboard’s cards read

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200

POST /api/dashboards/{id}/duplicate

Duplicate a dashboard with its pages, cards and filters

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 201 · 400 · 401 · 409

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

Preview the canonical scheduled-dashboard email

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

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

Responses: 200

POST /api/dashboards/{id}/entity-color-slots

Resolve the colour slots of the members a reader’s cards draw

Answers the slot of exactly the keys sent, in the caller’s own access scope, never a map. Signed-in members who read a field’s rows unrestricted and in clear share the scope ‘all’ (whose rows a card reads is the catalogue’s: its model’s source); a member whom row-level security restricts or a label masks keeps their own, as does every link (shared by its guests) and each embedded customer (its tenant), measures included, so none learns another’s members. A key the scope does not keep yet takes the lowest slot free in its field, in the order sent, appended only (unless assign is false, a lookup); only a signed-in member adds to ‘all’ (an API key only looks it up), and a link, an embed or an API key adds at most 32 new members a request. A field keeps 64 members a scope; past them a key is answered no slot. A masked member (‘***’) is never kept, and a key no dashboard keeps (no field, over 512 characters, U+0000 or half a surrogate pair) is answered 400. Resolving never claims the dashboard for editing or moves its edit token or its updated time; a request that adds members to colours a scope shares (members’ ‘all’, a link’s, a tenant’s) writes one audit row, dashboard.colors_kept, naming who and how many.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
keys	array of string	yes	Colour keys (\<field id>=\<member>, or measure=\<name>) of the members the caller’s cards draw, in the order they draw them.
assign	boolean	no	Give a key the caller’s scope does not keep yet the lowest slot free in its field (false: only look up kept ones).

Responses: 200 · 400 · 401 · 404

DELETE /api/dashboards/{id}/entity-color-slots

Reset a dashboard’s colours: clear the slot every scope keeps for its members

Every reader’s next view gives each member its colour again, from the theme’s first. Audited (dashboard.colors_reset). Not an edit of the dashboard: its edit token and updated time stay.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 204 — Reset · 404

POST /api/dashboards/{id}/export

Export the dashboard as a file (server-rendered), optionally as the viewer sees it

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx"	no
view	object	no

Responses: 200

GET /api/dashboards/{id}/filters

List filters for a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/filters

Add a filter to a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
fieldId	string	yes
filterType	string	yes
label	string	no
defaultValue	string	no
linkedCardIds	array of string	no

Responses: 201 · 400 · 401 · 409

PUT /api/dashboards/{id}/filters/{filterId}

Update a dashboard filter

Path parameters

Name	Type	Required	Description
id	string	yes
filterId	string	yes

Request body (JSON)

Field	Type	Required	Description
fieldId	string	no
filterType	string	no
label	string	no
defaultValue	string	no
linkedCardIds	array of string	no
ordinal	integer	no

Responses: 200 · 400 · 401 · 404

DELETE /api/dashboards/{id}/filters/{filterId}

Delete a dashboard filter

Path parameters

Name	Type	Required	Description
id	string	yes
filterId	string	yes

Responses: 204 — No content · 401 · 404

GET /api/dashboards/{id}/pages

List pages in a dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/pages

Create a dashboard page

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
id	string	no
name	string	yes
pageIndex	integer	no
isHidden	boolean	no

Responses: 201 · 400 · 401 · 409

PUT /api/dashboards/{id}/pages/{pageId}

Update a dashboard page

Path parameters

Name	Type	Required	Description
id	string	yes
pageId	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
pageIndex	integer	no
isHidden	boolean	no

Responses: 204 — No content · 401 · 404

DELETE /api/dashboards/{id}/pages/{pageId}

Delete a dashboard page

Path parameters

Name	Type	Required	Description
id	string	yes
pageId	string	yes

Responses: 204 — No content · 401 · 404

POST /api/dashboards/{id}/pages/reorder

Reorder dashboard pages

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
pageIds	array of string	yes

Responses: 204 — No content · 401 · 404

POST /api/dashboards/{id}/publish

Publish a dashboard version (snapshot current state)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

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

Responses: 200 · 400 · 401 · 404

GET /api/dashboards/{id}/schedules

List dashboard delivery schedules

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

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/schedules

Create a dashboard delivery schedule

A schedule starts from its next occurrence after it is made. Word (docx) is refused (400): a dashboard is sent as PDF, Excel, PowerPoint or CSV. The same request again within two minutes (a double click, a second Save) makes no second schedule: it answers 200 with the one already made.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	yes
cronExpression	string	yes
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx"	no
recipients	array of string	no
timezone	string	no
isActive	boolean	no
emailTemplateVersionId	string	no
partialRenderPolicy	"fail_without_send" | "send_with_warning"	no

Responses: 200 · 201 · 400 · 401 · 409

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

Update a dashboard delivery schedule

A schedule sends the dashboard as its creator sees it, so only its creator or a workspace admin can change who it sends to or the filters it sends: anyone else gets 403. It sends the dashboard’s filters as they were when its creator made it, resumed it after a pause, or chose the current ones (pinFilters): a later change to the dashboard’s filters by anyone changes no send until then, and resuming a paused schedule makes it send the filters as they are then. The other fields change how and when the same dashboard goes out, not what it shows. Sending the stored recipients back unchanged is not a change.

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
cronExpression	string	no
format	"pdf" | "csv" | "xlsx" | "pptx" | "docx"	no
recipients	array of string	no
timezone	string	no
isActive	boolean	no
emailTemplateVersionId	string	no
partialRenderPolicy	"fail_without_send" | "send_with_warning"	no
baseEditVersion	integer	no
pinFilters	boolean	no	true: the schedule sends the dashboard’s filters (its filter pane, every page) as they are now.

Responses: 200 · 400 · 401 · 403 · 404

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

Delete a dashboard delivery schedule

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Responses: 200

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

Delivery run history for a dashboard schedule

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Responses: 200 · 400 · 401

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

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

Path parameters

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

Responses: 200 · 400 · 401

GET /api/dashboards/{id}/subscriptions

List your subscriptions to this dashboard

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

POST /api/dashboards/{id}/subscriptions

Subscribe yourself to this dashboard on a schedule

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

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

Responses: 201 · 400 · 401 · 409

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

Pause, resume or re-time your subscription

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Request body (JSON)

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

Responses: 200 · 400 · 401 · 404

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

Delete your subscription

Path parameters

Name	Type	Required	Description
id	string	yes
scheduleId	string	yes

Responses: 204 — No content · 401 · 404

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

Send the canonical scheduled-dashboard email to the caller

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

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

Responses: 200

GET /api/dashboards/{id}/thumbnail

The dashboard’s library thumbnail (JPEG, PNG or WebP)

The editor’s low-resolution snapshot of the dashboard. 404 when there is none, or when the caller is under row-level security in the workspace — the snapshot shows its author’s rows.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200

PUT /api/dashboards/bookmarks/{bookmarkId}

Update a dashboard bookmark

Path parameters

Name	Type	Required	Description
bookmarkId	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
state	object	no
isDefault	boolean	no
isPersonal	boolean	no

Responses: 200 · 400 · 401 · 404

DELETE /api/dashboards/bookmarks/{bookmarkId}

Delete a dashboard bookmark

Path parameters

Name	Type	Required	Description
bookmarkId	string	yes

Responses: 204 — No content · 401 · 404

POST /api/dashboards/bulk-delete

Delete multiple dashboards in bulk (soft delete)

Request body (JSON)

Field	Type	Required	Description
ids	array of string	yes

Responses: 200 · 400 · 401 · 404

GET /api/dashboards/frequent

The caller’s most-opened dashboards over the last 30 days, most first

Counts the caller’s own views (web and mobile) in this workspace. Deleted dashboards and dashboards the caller can no longer open are left out.

Query parameters

Name	Type	Required	Description
limit	integer	no
include	"viewerMeta"	no
omitLayout	boolean	no	Leave layout out of each row; thumbnail_url still points at the library thumbnail.

Responses: 200 · 400 · 401 · 404

GET /api/dashboards/page

List dashboards with authoritative totals, server-side refinements and cursor or offset pagination

Shared means an explicit active dashboard access grant received by the caller, directly or through a workspace group. Ownership, workspace visibility, public links and embeds are excluded. q, favorite, publication, certification, updatedWithinDays and sort refine the result set on the server; total counts the refined set while allTotal and sharedTotal describe the whole library. A cursor is only accepted with sort=created.

Query parameters

Name	Type	Required	Description
includeDeleted	boolean	no
stage	string	no
publishedOnly	boolean	no
limit	integer	no
offset	integer	no
cursor	string	no
scope	"all" | "shared"	no
include	"viewerMeta"	no
omitLayout	boolean	no	Leave layout out of each row; thumbnail_url still points at the library thumbnail.
q	string	no	Case-insensitive substring over name and description.
favorite	boolean	no	Only the caller’s favourites.
publication	"published" | "draft"	no
certification	"certified" | "standard"	no
updatedWithinDays	integer	no
sort	"created" | "recent" | "name" | "cards"	no	created is the keyset order used by cursors; the others are offset-paged.

Responses: 200 · 400 · 401 · 404