Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Dashboards-API

Routen zum Auflisten, Lesen, Erstellen, Ändern, Kopieren, Exportieren und Importieren von Boards sowie zum Starten aus Vorlagen und zur Verwaltung von Anzeige-Links aus Code.

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 er dashboard.boards.read besitzt. Zum Ändern, Löschen oder Anlegen eines solchen Boards braucht der Schlüssel selbst zusätzlich dashboard.boards.manage.
  • Persönliche Boards (scope: "PRIVATE") gehören dem Schlüsselinhaber. Ein persönliches Board eines anderen Mitglieds liefert 404, genauso wie ein Board, das nicht existiert.
  • Eine Karte, deren Widget der Inhaber nicht sehen darf, wird aus Kopien und Dateien ausgelassen und in skipped genannt.

Routen

MethodePfadBerechtigungFunktion
GET/api/dashboard/boardsdashboard.boards.readListet die Boards auf, die der Schlüssel öffnen darf
POST/api/dashboard/boardsdashboard.boards.writeLegt ein leeres Board an
GET/api/dashboard/boards/{boardId}dashboard.boards.readEin 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.writeLöscht das Board und seine Karten
POST/api/dashboard/boards/{boardId}/duplicatedashboard.boards.writeKopiert ein Board
GET/api/dashboard/boards/{boardId}/exportdashboard.boards.readDas Board als Board-Datei
POST/api/dashboard/boards/importdashboard.boards.writePrüft (Trockenlauf) oder importiert eine Board-Datei
GET/api/dashboard/boards/templates?for=newdashboard.boards.readVorlagen, von denen ein neues Board ausgehen kann
POST/api/dashboard/boards/templates/{templateKey}/applydashboard.boards.writeLegt ein Board aus einer Vorlage an
GET, POST/api/dashboard/boards/{boardId}/display-linksdashboard.boards.manageListet die Anzeige-Links eines Boards auf oder legt einen an
DELETE/api/dashboard/boards/{boardId}/display-links/{linkId}dashboard.boards.manageWiderruft 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:

FeldRegel
titlePflicht, 1 bis 120 Zeichen
descriptionBis zu 1.000 Zeichen
iconBis zu 64 Zeichen
scopeTENANT (Standard) oder PRIVATE; ein Schlüssel ohne dashboard.boards.manage muss PRIVATE senden
workspace oder moduleIdDas Workspace-Menü, in dem das Board erscheint; nicht beides
isDefaulttrue macht es zum Board, das sich im Workspace-Menü zuerst öffnet
gridCols12 (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 .../export liefert die Datei selbst (Content-Disposition: attachment). Mit report=1 erhalten Sie stattdessen { package, skipped } als JSON. Mit linked=1 werden die Boards, die die Aktionen dieses Boards öffnen, als eine Datei mit eingeschlossen (bis zu 20 Boards; leftOut nennt die nicht übernommenen).
  • POST /api/dashboard/boards/import erwartet { "package": <die Datei>, "dryRun": true, "title": "…", "scope": "PRIVATE" }. dryRun ist standardmäßig true: Die Antwort { dryRun: true, report } sagt, was importiert, repariert oder übersprungen würde, und schreibt nichts. Mit "dryRun": false wird das Board angelegt: 201 { dryRun: false, board, report }. Bei einer Datei mit mehreren Boards listet boards jedes 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).

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

StatusMeldung
400Validation error mit issues (ein unbekanntes Feld, ein Wert außerhalb des Bereichs)
403Nur ein Admin darf ein gemeinsames Dashboard erstellen oder ändern
403Ihr Tarif erlaubt keine weiteren gemeinsamen Dashboards (details.reason shared_board_limit, mit used und limit)
403Sie haben das Limit persönlicher Dashboards erreicht (personal_board_limit)
403Sie dürfen dieses Widget nicht platzieren (eine Vorlage, deren Karten der Inhaber nicht verwenden darf)
404Dashboard nicht gefunden / Unbekannte Dashboard-Vorlage
409Dieses Dashboard wurde von jemand anderem geändert, seit Sie es geladen haben
409Ein 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)
409Dieses Dashboard hat bereits die maximale Anzahl aktiver Anzeige-Links erreicht
422Ein privates Widget kann nicht auf einem gemeinsamen Dashboard platziert werden (bei der Freigabe eines Boards mit solchen Karten; details.placements nennt sie)
422Eine persönliche Kopie, die ein gemeinsames Dashboard ersetzt, kann nicht freigegeben werden; duplizieren Sie sie stattdessen als gemeinsames Dashboard
422Diese Datei verwendet ein Dashboard-Paketformat, das diese App nicht importieren kann / wurde mit einer neueren Version exportiert

Limits

LimitWert
Gemeinsame BoardsDurch Ihren Tarif festgelegt; siehe Usage and quotas
Persönliche Boards20 pro Mitglied (der Inhaber des Schlüssels)
Karten in einer Board-Datei200
Boards in einer verknüpften Datei20
Anzeige-Links20 aktive pro Board; 1 bis 365 Tage, Standard 30; Bezeichnung bis zu 80 Zeichen
AnfragerateWie für jeden API-Schlüssel; siehe Errors and rate limits