New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Boards API

Routes to list, read, create, change, copy, export and import boards, start them from templates and manage display links from code.

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 holds dashboard.boards.read. Changing, deleting or creating one also needs dashboard.boards.manage on the key itself.
  • Personal boards (scope: "PRIVATE") are the key holder’s own. Another member’s personal board answers 404, 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

MethodPathPermissionDoes
GET/api/dashboard/boardsdashboard.boards.readList the boards the key may open
POST/api/dashboard/boardsdashboard.boards.writeCreate an empty board
GET/api/dashboard/boards/{boardId}dashboard.boards.readOne board with its cards
PATCH/api/dashboard/boards/{boardId}dashboard.boards.writeChange title, description, icon, grid, time window, parameters, pages; share a personal board
DELETE/api/dashboard/boards/{boardId}dashboard.boards.writeDelete the board and its cards
POST/api/dashboard/boards/{boardId}/duplicatedashboard.boards.writeCopy a board
GET/api/dashboard/boards/{boardId}/exportdashboard.boards.readThe board as a board file
POST/api/dashboard/boards/importdashboard.boards.writeCheck (dry run) or import a board file
GET/api/dashboard/boards/templates?for=newdashboard.boards.readTemplates a new board can start from
POST/api/dashboard/boards/templates/{templateKey}/applydashboard.boards.writeCreate a board from a template
GET, POST/api/dashboard/boards/{boardId}/display-linksdashboard.boards.manageList a board’s display links, or create one
DELETE/api/dashboard/boards/{boardId}/display-links/{linkId}dashboard.boards.manageRevoke 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:

FieldRule
titleRequired, 1 to 120 characters
descriptionUp to 1,000 characters
iconUp to 64 characters
scopeTENANT (default) or PRIVATE; a key without dashboard.boards.manage must send PRIVATE
workspace or moduleIdThe workspace menu that shows the board; not both
isDefaulttrue makes it the board its workspace menu opens first
gridCols12 (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 .../export answers the file itself (Content-Disposition: attachment). Add report=1 to get { package, skipped } as JSON instead. Add linked=1 to include, as one file, the boards this board’s actions open (up to 20 boards; leftOut names those not taken).
  • POST /api/dashboard/boards/import takes { "package": <the file>, "dryRun": true, "title": "…", "scope": "PRIVATE" }. dryRun defaults to true: the answer { dryRun: true, report } says what would be imported, repaired or skipped and writes nothing. Send "dryRun": false to create the board: 201 { dryRun: false, board, report }. For a file of several boards, boards lists 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).

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

StatusMessage
400Validation error with issues (an unknown field, a value out of range)
403Only an admin may create or change a shared dashboard
403Your plan allows no more shared dashboards (details.reason shared_board_limit, with used and limit)
403You have reached the limit of personal dashboards (personal_board_limit)
403You are not allowed to place this widget (a template whose cards the holder may not use)
404Dashboard not found / Unknown dashboard template
409This dashboard was changed by someone else since you loaded it
409A 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)
409This dashboard already has the maximum number of active display links
422A private widget cannot be placed on a shared dashboard (sharing a board with such cards; details.placements names them)
422A personal copy that stands in for a shared dashboard cannot be shared; duplicate it as a shared dashboard instead
422This file uses a dashboard package format this app cannot import / was exported by a newer version

Limits

LimitValue
Shared boardsSet by your plan; see Usage and quotas
Personal boards20 per member (the key’s holder)
Cards in one board file200
Boards in one linked file20
Display links20 active per board; 1 to 365 days, default 30; label up to 80 characters
Request rateAs for every API key; see Errors and rate limits