These routes let a script or another system work with boards (dashboards): keep a list of them, copy a board, back it up as a file, move it to another organisation or create boards from templates. How boards work for people is in Create and organise boards and Sharing dashboards.
Paths are under https://<your host>/tenant/<tenantId>. Conventions (strict bodies, errors, rate limits) are in REST API basics.
Whose boards a key sees
A key acts as the member who holds it (see Authentication). For boards this means:
- Shared boards (
scope: "TENANT") are visible to the key when it holdsdashboard.boards.read. Changing, deleting or creating one also needsdashboard.boards.manageon the key itself. - Personal boards (
scope: "PRIVATE") are the key holder’s own. Another member’s personal board answers404, the same as a board that does not exist. - A card whose widget the holder may not see is left out of copies and files, and named in
skipped.
Routes
| Method | Path | Permission | Does |
|---|---|---|---|
| GET | /api/dashboard/boards | dashboard.boards.read | List the boards the key may open |
| POST | /api/dashboard/boards | dashboard.boards.write | Create an empty board |
| GET | /api/dashboard/boards/{boardId} | dashboard.boards.read | One board with its cards |
| PATCH | /api/dashboard/boards/{boardId} | dashboard.boards.write | Change title, description, icon, grid, time window, parameters, pages; share a personal board |
| DELETE | /api/dashboard/boards/{boardId} | dashboard.boards.write | Delete the board and its cards |
| POST | /api/dashboard/boards/{boardId}/duplicate | dashboard.boards.write | Copy a board |
| GET | /api/dashboard/boards/{boardId}/export | dashboard.boards.read | The board as a board file |
| POST | /api/dashboard/boards/import | dashboard.boards.write | Check (dry run) or import a board file |
| GET | /api/dashboard/boards/templates?for=new | dashboard.boards.read | Templates a new board can start from |
| POST | /api/dashboard/boards/templates/{templateKey}/apply | dashboard.boards.write | Create a board from a template |
| GET, POST | /api/dashboard/boards/{boardId}/display-links | dashboard.boards.manage | List a board’s display links, or create one |
| DELETE | /api/dashboard/boards/{boardId}/display-links/{linkId} | dashboard.boards.manage | Revoke a display link |
Every write that creates or changes a shared board also needs dashboard.boards.manage; without it the answer is 403 “Only an admin may create or change a shared dashboard”. Default roles: read and write are User permissions, manage is an Admin permission.
The board editor and the board view in the browser use further routes (placing and moving cards, running a card’s query, the widget library, the copy kept while you customise). They are not part of this reference. To change cards from code, export the board, edit the file and import it.
List boards
GET /api/dashboard/boards without paging parameters answers every board the key may open:
{
"boards": [
{
"boardId": "2c7d…", "title": "Cold rooms", "description": null, "icon": null,
"scope": "TENANT", "workspace": null, "moduleId": null, "isDefault": false,
"gridCols": 12, "revision": 14, "createdByUserId": "u-55…",
"createdAt": "2026-10-02T08:00:00.000Z", "updatedAt": "2026-11-12T09:30:00.000Z",
"canWrite": true, "ownerLabel": "Ana Lima", "…": "…"
}
],
"canManage": true
}
With page or pageSize it answers one page as { "data": [...], "total": n, "canManage": true }. Pages start at 0; pageSize is 1 to 100 (default 20); search up to 200 characters; sort by title, updatedAt, scope or workspace (default updatedAt:desc); filters scope (TENANT, PRIVATE) and workspace (a comma list; none for boards in no workspace menu). Add quota=1 to get sharedQuota: { used, limit } (limit null: no limit) when the key holds dashboard.boards.manage.
GET /api/dashboard/boards/{boardId} answers { board, instances, widgets, pinned }: the board, its cards (place, size, title, settings, data bindings, actions) and the widgets they use.
Create, change and delete
POST /api/dashboard/boards takes:
| Field | Rule |
|---|---|
title | Required, 1 to 120 characters |
description | Up to 1,000 characters |
icon | Up to 64 characters |
scope | TENANT (default) or PRIVATE; a key without dashboard.boards.manage must send PRIVATE |
workspace or moduleId | The workspace menu that shows the board; not both |
isDefault | true makes it the board its workspace menu opens first |
gridCols | 12 (default) or 24 |
The answer is 201 { "board": {...} }. A slug is made from the title; you cannot send one.
PATCH takes the same fields (except workspace and moduleId) plus settings, timeWindow, params, filters, pages and mainPage, and only changes what you send. Send expectedRevision (the board’s revision when you read it) to be refused with 409 “This dashboard was changed by someone else since you loaded it” instead of overwriting a newer change. "scope": "TENANT" shares a personal board; a shared board is never made personal again. DELETE answers { "ok": true }.
Copy a board
POST /api/dashboard/boards/{boardId}/duplicate with { "title": "Cold rooms (night shift)", "scope": "PRIVATE" } (both optional; the default title adds ” (copy)”, the default scope is PRIVATE). The answer is 201 { board, skipped, droppedCommands }: skipped lists cards whose widget could not be copied, droppedCommands counts command actions the key’s holder may not set up, which were removed.
Board files: export and import
The file format and what it holds are explained in Board templates and board files.
GET .../exportanswers the file itself (Content-Disposition: attachment). Addreport=1to get{ package, skipped }as JSON instead. Addlinked=1to include, as one file, the boards this board’s actions open (up to 20 boards;leftOutnames those not taken).POST /api/dashboard/boards/importtakes{ "package": <the file>, "dryRun": true, "title": "…", "scope": "PRIVATE" }.dryRundefaults totrue: the answer{ dryRun: true, report }says what would be imported, repaired or skipped and writes nothing. Send"dryRun": falseto create the board:201 { dryRun: false, board, report }. For a file of several boards,boardslists every board created; they are created all together or not at all.
A key works only in its own organisation, so moving a board needs a key in each:
curl -s 'https://<your-host>/tenant/{sourceTenantId}/api/dashboard/boards/{boardId}/export' \
-H 'Authorization: Bearer sk_live_…source key…' > cold-rooms.board.json
jq '{package: ., dryRun: true}' cold-rooms.board.json | \
curl -X POST 'https://<your-host>/tenant/{targetTenantId}/api/dashboard/boards/import' \
-H 'Authorization: Bearer sk_live_…target key…' \
-H 'Content-Type: application/json' \
-d @-
Read report.issues, then send the same body with "dryRun": false.
Start from a template
GET /api/dashboard/boards/templates?for=new lists the templates a new board can start from: key, title, description, cardCount, pageCount, paramCount and, for a template that asks a question, ask. Templates of modules that are off in your organisation are not listed.
POST /api/dashboard/boards/templates/{templateKey}/apply with asNew creates a new board:
{
"asNew": { "title": "Plant sites", "scope": "TENANT", "description": null, "workspace": null },
"answers": { "sites": { "choose": "all" } }
}
answers is only for a template that asks a question: the key is the ask.param of the template, the value one of { "choose": "all" }, { "choose": "subtype", "subtype": "…" } or { "choose": "under", "entityId": "…" }. The answer is 201 { board, created: true, skipped, droppedCommands }. With { "boardId": "…" } instead of asNew, the template’s cards are added below the cards of an existing board (200, created: false).
Display links
A display link shows a board on a screen where nobody signs in. POST .../display-links with { "label": "Lobby TV", "expiresInDays": 30 } answers 201 { link, token, url }; the token and the address are in this answer only. The link’s issuer is the key’s holder, and the screen shows the board with the holder’s permissions. GET lists the links (status active, expired or revoked) without tokens; DELETE .../display-links/{linkId} revokes one. See Wall screens, full screen and zoom.
Errors
| Status | Message |
|---|---|
| 400 | Validation error with issues (an unknown field, a value out of range) |
| 403 | Only an admin may create or change a shared dashboard |
| 403 | Your plan allows no more shared dashboards (details.reason shared_board_limit, with used and limit) |
| 403 | You have reached the limit of personal dashboards (personal_board_limit) |
| 403 | You are not allowed to place this widget (a template whose cards the holder may not use) |
| 404 | Dashboard not found / Unknown dashboard template |
| 409 | This dashboard was changed by someone else since you loaded it |
| 409 | A dashboard parameter is still used by a widget binding and cannot be removed (and the same for a page or a filter still in use) |
| 409 | This dashboard already has the maximum number of active display links |
| 422 | A private widget cannot be placed on a shared dashboard (sharing a board with such cards; details.placements names them) |
| 422 | A personal copy that stands in for a shared dashboard cannot be shared; duplicate it as a shared dashboard instead |
| 422 | This file uses a dashboard package format this app cannot import / was exported by a newer version |
Limits
| Limit | Value |
|---|---|
| Shared boards | Set by your plan; see Usage and quotas |
| Personal boards | 20 per member (the key’s holder) |
| Cards in one board file | 200 |
| Boards in one linked file | 20 |
| Display links | 20 active per board; 1 to 365 days, default 30; label up to 80 characters |
| Request rate | As for every API key; see Errors and rate limits |

