Mit diesen Routen können ein Skript oder ein anderes System mit Boards (Dashboards) arbeiten: eine Liste davon abrufen, ein Board kopieren, es als Datei sichern, in eine andere Organisation verschieben oder Boards aus Vorlagen erstellen. Wie Boards für Personen funktionieren, steht unter Create and organise boards und Sharing dashboards.
Pfade liegen unter https://<your host>/tenant/<tenantId>. Konventionen (strikte Bodies, Fehler, Rate Limits) stehen unter REST API basics.
Welche Boards ein Schlüssel sieht
Ein Schlüssel handelt als das Mitglied, dem er gehört (siehe Authentication). Für Boards heißt das:
- Gemeinsame Boards (
scope: "TENANT") sind für den Schlüssel sichtbar, wenn erdashboard.boards.readbesitzt. Zum Ändern, Löschen oder Anlegen eines solchen Boards braucht der Schlüssel selbst zusätzlichdashboard.boards.manage. - Persönliche Boards (
scope: "PRIVATE") gehören dem Schlüsselinhaber. Ein persönliches Board eines anderen Mitglieds liefert404, genauso wie ein Board, das nicht existiert. - Eine Karte, deren Widget der Inhaber nicht sehen darf, wird aus Kopien und Dateien ausgelassen und in
skippedgenannt.
Routen
| Methode | Pfad | Berechtigung | Funktion |
|---|---|---|---|
| GET | /api/dashboard/boards | dashboard.boards.read | Listet die Boards auf, die der Schlüssel öffnen darf |
| POST | /api/dashboard/boards | dashboard.boards.write | Legt ein leeres Board an |
| GET | /api/dashboard/boards/{boardId} | dashboard.boards.read | Ein Board mit seinen Karten |
| PATCH | /api/dashboard/boards/{boardId} | dashboard.boards.write | Ändert Titel, Beschreibung, Icon, Raster, Zeitfenster, Parameter, Seiten; teilt ein persönliches Board |
| DELETE | /api/dashboard/boards/{boardId} | dashboard.boards.write | Löscht das Board und seine Karten |
| POST | /api/dashboard/boards/{boardId}/duplicate | dashboard.boards.write | Kopiert ein Board |
| GET | /api/dashboard/boards/{boardId}/export | dashboard.boards.read | Das Board als Board-Datei |
| POST | /api/dashboard/boards/import | dashboard.boards.write | Prüft (Trockenlauf) oder importiert eine Board-Datei |
| GET | /api/dashboard/boards/templates?for=new | dashboard.boards.read | Vorlagen, von denen ein neues Board ausgehen kann |
| POST | /api/dashboard/boards/templates/{templateKey}/apply | dashboard.boards.write | Legt ein Board aus einer Vorlage an |
| GET, POST | /api/dashboard/boards/{boardId}/display-links | dashboard.boards.manage | Listet die Anzeige-Links eines Boards auf oder legt einen an |
| DELETE | /api/dashboard/boards/{boardId}/display-links/{linkId} | dashboard.boards.manage | Widerruft einen Anzeige-Link |
Jeder Schreibvorgang, der ein gemeinsames Board anlegt oder ändert, braucht zusätzlich dashboard.boards.manage; ohne diese Berechtigung lautet die Antwort 403 „Only an admin may create or change a shared dashboard“. Standardrollen: Lesen und Schreiben sind Benutzerberechtigungen, Verwalten ist eine Administratorberechtigung.
Der Board-Editor und die Board-Ansicht im Browser verwenden weitere Routen (Karten platzieren und verschieben, die Abfrage einer Karte ausführen, die Widget-Bibliothek, die Kopie, die beim Anpassen entsteht). Sie gehören nicht zu dieser Referenz. Um Karten aus Code zu ändern, exportieren Sie das Board, bearbeiten die Datei und importieren sie wieder.
Boards auflisten
GET /api/dashboard/boards ohne Paging-Parameter liefert alle Boards, die der Schlüssel öffnen darf:
{
"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
}
Mit page oder pageSize liefert es eine Seite als { "data": [...], "total": n, "canManage": true }. Seiten beginnen bei 0; pageSize reicht von 1 bis 100 (Standard 20); search bis 200 Zeichen; sort nach title, updatedAt, scope oder workspace (Standard updatedAt:desc); Filter scope (TENANT, PRIVATE) und workspace (eine kommagetrennte Liste; none für Boards in keinem Workspace-Menü). Mit quota=1 erhalten Sie sharedQuota: { used, limit } (limit null: kein Limit), sofern der Schlüssel dashboard.boards.manage besitzt.
GET /api/dashboard/boards/{boardId} liefert { board, instances, widgets, pinned }: das Board, seine Karten (Position, Größe, Titel, Einstellungen, Datenbindungen, Aktionen) und die verwendeten Widgets.
Anlegen, ändern und löschen
POST /api/dashboard/boards erwartet:
| Feld | Regel |
|---|---|
title | Pflicht, 1 bis 120 Zeichen |
description | Bis zu 1.000 Zeichen |
icon | Bis zu 64 Zeichen |
scope | TENANT (Standard) oder PRIVATE; ein Schlüssel ohne dashboard.boards.manage muss PRIVATE senden |
workspace oder moduleId | Das Workspace-Menü, in dem das Board erscheint; nicht beides |
isDefault | true macht es zum Board, das sich im Workspace-Menü zuerst öffnet |
gridCols | 12 (Standard) oder 24 |
Die Antwort ist 201 { "board": {...} }. Ein Slug wird aus dem Titel erzeugt; einen Slug können Sie nicht senden.
PATCH nimmt dieselben Felder (außer workspace und moduleId) sowie settings, timeWindow, params, filters, pages und mainPage und ändert nur, was Sie senden. Senden Sie expectedRevision (die revision des Boards, als Sie es gelesen haben), wird die Änderung mit 409 „This dashboard was changed by someone else since you loaded it“ abgelehnt, statt eine neuere Änderung zu überschreiben. "scope": "TENANT" teilt ein persönliches Board; ein gemeinsames Board wird nie wieder persönlich. DELETE antwortet mit { "ok": true }.
Ein Board kopieren
POST /api/dashboard/boards/{boardId}/duplicate mit { "title": "Kühlräume (Nachtschicht)", "scope": "PRIVATE" } (beide optional; der Standardtitel fügt “ (copy)“ an, der Standardbereich ist PRIVATE). Die Antwort ist 201 { board, skipped, droppedCommands }: skipped listet Karten, deren Widget nicht kopiert werden konnte, droppedCommands zählt Befehlsaktionen, die der Schlüsselinhaber nicht einrichten darf und die daher entfernt wurden.
Board-Dateien: exportieren und importieren
Das Dateiformat und dessen Inhalt werden unter Board templates and board files erklärt.
GET .../exportliefert die Datei selbst (Content-Disposition: attachment). Mitreport=1erhalten Sie stattdessen{ package, skipped }als JSON. Mitlinked=1werden die Boards, die die Aktionen dieses Boards öffnen, als eine Datei mit eingeschlossen (bis zu 20 Boards;leftOutnennt die nicht übernommenen).POST /api/dashboard/boards/importerwartet{ "package": <die Datei>, "dryRun": true, "title": "…", "scope": "PRIVATE" }.dryRunist standardmäßigtrue: Die Antwort{ dryRun: true, report }sagt, was importiert, repariert oder übersprungen würde, und schreibt nichts. Mit"dryRun": falsewird das Board angelegt:201 { dryRun: false, board, report }. Bei einer Datei mit mehreren Boards listetboardsjedes angelegte Board; sie werden alle zusammen oder gar nicht angelegt.
Ein Schlüssel arbeitet nur in seiner eigenen Organisation, daher braucht das Verschieben eines Boards einen Schlüssel in jeder der beiden Organisationen.
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 @-
Lesen Sie report.issues und senden Sie dann denselben Body mit "dryRun": false.
Aus einer Vorlage starten
GET /api/dashboard/boards/templates?for=new listet die Vorlagen, von denen ein neues Board ausgehen kann: key, title, description, cardCount, pageCount, paramCount und, bei einer Vorlage, die eine Frage stellt, ask. Vorlagen von Modulen, die in Ihrer Organisation deaktiviert sind, werden nicht aufgelistet.
POST /api/dashboard/boards/templates/{templateKey}/apply mit asNew erstellt ein neues Board:
{
"asNew": { "title": "Plant sites", "scope": "TENANT", "description": null, "workspace": null },
"answers": { "sites": { "choose": "all" } }
}
answers gilt nur für eine Vorlage, die eine Frage stellt: Der Schlüssel ist das ask.param der Vorlage, der Wert einer von { "choose": "all" }, { "choose": "subtype", "subtype": "…" } oder { "choose": "under", "entityId": "…" }. Die Antwort ist 201 { board, created: true, skipped, droppedCommands }. Mit { "boardId": "…" } statt asNew werden die Karten der Vorlage unterhalb der Karten eines bestehenden Boards hinzugefügt (200, created: false).
Anzeige-Links
Ein Anzeige-Link zeigt ein Board auf einem Bildschirm, an dem sich niemand anmeldet. POST .../display-links mit { "label": "Lobby TV", "expiresInDays": 30 } antwortet mit 201 { link, token, url }; das Token und die Adresse sind nur in dieser Antwort enthalten. Der Aussteller des Links ist der Inhaber des Schlüssels, und der Bildschirm zeigt das Board mit den Berechtigungen des Inhabers. GET listet die Links (status active, expired oder revoked) ohne Tokens auf; DELETE .../display-links/{linkId} widerruft einen Link. Siehe Wall screens, full screen and zoom.
Fehler
| Status | Meldung |
|---|---|
| 400 | Validation error mit issues (ein unbekanntes Feld, ein Wert außerhalb des Bereichs) |
| 403 | Nur ein Admin darf ein gemeinsames Dashboard erstellen oder ändern |
| 403 | Ihr Tarif erlaubt keine weiteren gemeinsamen Dashboards (details.reason shared_board_limit, mit used und limit) |
| 403 | Sie haben das Limit persönlicher Dashboards erreicht (personal_board_limit) |
| 403 | Sie dürfen dieses Widget nicht platzieren (eine Vorlage, deren Karten der Inhaber nicht verwenden darf) |
| 404 | Dashboard nicht gefunden / Unbekannte Dashboard-Vorlage |
| 409 | Dieses Dashboard wurde von jemand anderem geändert, seit Sie es geladen haben |
| 409 | Ein Dashboard-Parameter wird noch von einer Widget-Bindung verwendet und kann nicht entfernt werden (ebenso eine Seite oder ein Filter, die noch in Gebrauch sind) |
| 409 | Dieses Dashboard hat bereits die maximale Anzahl aktiver Anzeige-Links erreicht |
| 422 | Ein privates Widget kann nicht auf einem gemeinsamen Dashboard platziert werden (bei der Freigabe eines Boards mit solchen Karten; details.placements nennt sie) |
| 422 | Eine persönliche Kopie, die ein gemeinsames Dashboard ersetzt, kann nicht freigegeben werden; duplizieren Sie sie stattdessen als gemeinsames Dashboard |
| 422 | Diese Datei verwendet ein Dashboard-Paketformat, das diese App nicht importieren kann / wurde mit einer neueren Version exportiert |
Limits
| Limit | Wert |
|---|---|
| Gemeinsame Boards | Durch Ihren Tarif festgelegt; siehe Usage and quotas |
| Persönliche Boards | 20 pro Mitglied (der Inhaber des Schlüssels) |
| Karten in einer Board-Datei | 200 |
| Boards in einer verknüpften Datei | 20 |
| Anzeige-Links | 20 aktive pro Board; 1 bis 365 Tage, Standard 30; Bezeichnung bis zu 80 Zeichen |
| Anfragerate | Wie für jeden API-Schlüssel; siehe Errors and rate limits |

