Ces routes permettent à un script ou à un autre système de travailler avec des tableaux de bord (dashboards) : en dresser la liste, en copier un, le sauvegarder sous forme de fichier, le transférer vers une autre organisation ou créer des tableaux à partir de modèles. Le fonctionnement des tableaux pour les utilisateurs est décrit dans Create and organise boards et Sharing dashboards.
Les chemins se trouvent sous https://<your host>/tenant/<tenantId>. Les conventions (corps stricts, erreurs, limites de débit) sont décrites dans REST API basics.
Les tableaux visibles par une clé
Une clé agit au nom du membre qui la détient (voir Authentication). Pour les tableaux, cela signifie :
- Tableaux partagés (
scope: "TENANT") : visibles par la clé lorsqu’elle détientdashboard.boards.read. Les modifier, les supprimer ou en créer un nécessite aussidashboard.boards.managesur la clé elle-même. - Tableaux personnels (
scope: "PRIVATE") : appartiennent au titulaire de la clé. Le tableau personnel d’un autre membre répond404, comme un tableau inexistant. - Une carte dont le widget n’est pas visible par le titulaire est omise des copies et des fichiers, et citée dans
skipped.
Routes
| Méthode | Chemin | Permission | Action |
|---|---|---|---|
| GET | /api/dashboard/boards | dashboard.boards.read | Lister les tableaux que la clé peut ouvrir |
| POST | /api/dashboard/boards | dashboard.boards.write | Créer un tableau vide |
| GET | /api/dashboard/boards/{boardId} | dashboard.boards.read | Un tableau avec ses cartes |
| PATCH | /api/dashboard/boards/{boardId} | dashboard.boards.write | Modifier le titre, la description, l’icône, la grille, la fenêtre temporelle, les paramètres, les pages ; partager un tableau personnel |
| DELETE | /api/dashboard/boards/{boardId} | dashboard.boards.write | Supprimer le tableau et ses cartes |
| POST | /api/dashboard/boards/{boardId}/duplicate | dashboard.boards.write | Copier un tableau |
| GET | /api/dashboard/boards/{boardId}/export | dashboard.boards.read | Le tableau sous forme de fichier de tableau |
| POST | /api/dashboard/boards/import | dashboard.boards.write | Vérifier (essai à blanc) ou importer un fichier de tableau |
| GET | /api/dashboard/boards/templates?for=new | dashboard.boards.read | Modèles à partir desquels un nouveau tableau peut être créé |
| POST | /api/dashboard/boards/templates/{templateKey}/apply | dashboard.boards.write | Créer un tableau à partir d’un modèle |
| GET, POST | /api/dashboard/boards/{boardId}/display-links | dashboard.boards.manage | Lister les liens d’affichage d’un tableau, ou en créer un |
| DELETE | /api/dashboard/boards/{boardId}/display-links/{linkId} | dashboard.boards.manage | Révoquer un lien d’affichage |
Toute écriture qui crée ou modifie un tableau partagé nécessite aussi dashboard.boards.manage ; sans elle, la réponse est 403 « Only an admin may create or change a shared dashboard ». Rôles par défaut : lecture et écriture sont des permissions User, manage est une permission Admin.
L’éditeur de tableaux et la vue de tableau dans le navigateur utilisent d’autres routes (placement et déplacement des cartes, exécution de la requête d’une carte, bibliothèque de widgets, copie conservée pendant la personnalisation). Elles ne font pas partie de cette référence. Pour modifier les cartes depuis du code, exportez le tableau, modifiez le fichier et réimportez-le.
Lister les tableaux
GET /api/dashboard/boards sans paramètres de pagination renvoie tous les tableaux que la clé peut ouvrir :
{
"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
}
Avec page ou pageSize, la réponse contient une page sous la forme { "data": [...], "total": n, "canManage": true }. Les pages commencent à 0 ; pageSize va de 1 à 100 (valeur par défaut 20) ; search jusqu’à 200 caractères ; sort par title, updatedAt, scope ou workspace (par défaut updatedAt:desc) ; filtres scope (TENANT, PRIVATE) et workspace (liste séparée par des virgules ; none pour les tableaux figurant dans aucun menu d’espace de travail). Ajoutez quota=1 pour obtenir sharedQuota: { used, limit } (limit null : pas de limite) lorsque la clé détient dashboard.boards.manage.
GET /api/dashboard/boards/{boardId} renvoie { board, instances, widgets, pinned } : le tableau, ses cartes (emplacement, taille, titre, paramètres, liaisons de données, actions) et les widgets utilisés.
Créer, modifier et supprimer
POST /api/dashboard/boards accepte :
| Champ | Règle |
|---|---|
title | Obligatoire, de 1 à 120 caractères |
description | Jusqu’à 1 000 caractères |
icon | Jusqu’à 64 caractères |
scope | TENANT (par défaut) ou PRIVATE ; une clé sans dashboard.boards.manage doit envoyer PRIVATE |
workspace ou moduleId | Le menu d’espace de travail qui affiche le tableau ; pas les deux |
isDefault | true en fait le tableau ouvert en premier par le menu de son espace de travail |
gridCols | 12 (par défaut) ou 24 |
La réponse est 201 { "board": {...} }. Un slug est créé à partir du titre ; vous ne pouvez pas en envoyer un.
PATCH accepte les mêmes champs (sauf workspace et moduleId) ainsi que settings, timeWindow, params, filters, pages et mainPage, et ne modifie que ce que vous envoyez. Envoyez expectedRevision (la revision du tableau au moment de sa lecture) pour obtenir un 409 « This dashboard was changed by someone else since you loaded it » au lieu d’écraser une modification plus récente. "scope": "TENANT" partage un tableau personnel ; un tableau partagé ne redevient jamais personnel. DELETE répond { "ok": true }.
Copier un tableau
POST /api/dashboard/boards/{boardId}/duplicate avec { "title": "Cold rooms (night shift)", "scope": "PRIVATE" } (les deux sont facultatifs ; le titre par défaut ajoute » (copy) », le scope par défaut est PRIVATE). La réponse est 201 { board, skipped, droppedCommands } : skipped liste les cartes dont le widget n’a pas pu être copié, droppedCommands compte les actions de commande que le titulaire de la clé ne peut pas configurer, lesquelles ont été supprimées.
Fichiers de tableau : export et import
Le format de fichier et son contenu sont expliqués dans Board templates and board files.
GET .../exportrenvoie le fichier lui-même (Content-Disposition: attachment). Ajoutezreport=1pour obtenir{ package, skipped }en JSON à la place. Ajoutezlinked=1pour inclure, dans un seul fichier, les tableaux ouverts par les actions de ce tableau (jusqu’à 20 tableaux ;leftOutnomme ceux qui ne sont pas repris).POST /api/dashboard/boards/importaccepte{ "package": <the file>, "dryRun": true, "title": "…", "scope": "PRIVATE" }.dryRunvauttruepar défaut : la réponse{ dryRun: true, report }indique ce qui serait importé, réparé ou ignoré, sans rien écrire. Envoyez"dryRun": falsepour créer le tableau :201 { dryRun: false, board, report }. Pour un fichier contenant plusieurs tableaux,boardsliste chaque tableau créé ; ils sont tous créés ensemble ou aucun ne l’est.
Une clé ne fonctionne que dans sa propre organisation ; déplacer un tableau nécessite donc une clé dans chacune d’elles.
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 @-
Lisez report.issues, puis envoyez le même corps avec "dryRun": false.
Partir d’un modèle
GET /api/dashboard/boards/templates?for=new liste les modèles à partir desquels un nouveau tableau peut être créé : key, title, description, cardCount, pageCount, paramCount et, pour un modèle qui pose une question, ask. Les modèles des modules désactivés dans votre organisation ne sont pas listés.
POST /api/dashboard/boards/templates/{templateKey}/apply avec asNew crée un nouveau tableau de bord :
{
"asNew": { "title": "Plant sites", "scope": "TENANT", "description": null, "workspace": null },
"answers": { "sites": { "choose": "all" } }
}
answers n’est utilisé que pour un modèle qui pose une question : la clé est le ask.param du modèle, la valeur l’une de { "choose": "all" }, { "choose": "subtype", "subtype": "…" } ou { "choose": "under", "entityId": "…" }. La réponse est 201 { board, created: true, skipped, droppedCommands }. Avec { "boardId": "…" } à la place de asNew, les cartes du modèle sont ajoutées sous les cartes d’un tableau de bord existant (200, created: false).
Liens d’affichage
Un lien d’affichage montre un tableau de bord sur un écran où personne ne se connecte. POST .../display-links avec { "label": "Lobby TV", "expiresInDays": 30 } répond 201 { link, token, url } ; le jeton et l’adresse ne figurent que dans cette réponse. L’émetteur du lien est le titulaire de la clé, et l’écran affiche le tableau de bord avec les droits du titulaire. GET liste les liens (status active, expired ou revoked) sans jetons ; DELETE .../display-links/{linkId} révoque un lien. Voir Écrans muraux, plein écran et zoom.
Erreurs
| Statut | Message |
|---|---|
| 400 | Validation error avec issues (un champ inconnu, une valeur hors plage) |
| 403 | Seul un administrateur peut créer ou modifier un tableau de bord partagé |
| 403 | Votre offre n’autorise plus de tableaux de bord partagés (details.reason shared_board_limit, avec used et limit) |
| 403 | Vous avez atteint la limite de tableaux de bord personnels (personal_board_limit) |
| 403 | Vous n’êtes pas autorisé à placer ce widget (un modèle dont le titulaire ne peut pas utiliser les cartes) |
| 404 | Tableau de bord introuvable / Modèle de tableau de bord inconnu |
| 409 | Ce tableau de bord a été modifié par une autre personne depuis que vous l’avez chargé |
| 409 | Un paramètre de tableau de bord est encore utilisé par une liaison de widget et ne peut pas être supprimé (idem pour une page ou un filtre encore utilisé) |
| 409 | Ce tableau de bord a déjà atteint le nombre maximal de liens d’affichage actifs |
| 422 | Un widget privé ne peut pas être placé sur un tableau de bord partagé (partager un tableau contenant de telles cartes ; details.placements les nomme) |
| 422 | Une copie personnelle qui remplace un tableau de bord partagé ne peut pas être partagée ; dupliquez-la plutôt en tant que tableau de bord partagé |
| 422 | Ce fichier utilise un format de package de tableau de bord que cette application ne peut pas importer / a été exporté par une version plus récente |
Limites
| Limite | Valeur |
|---|---|
| Tableaux de bord partagés | Défini par votre offre ; voir Utilisation et quotas |
| Tableaux de bord personnels | 20 par membre (le titulaire de la clé) |
| Cartes dans un fichier de tableau de bord | 200 |
| Tableaux de bord dans un fichier lié | 20 |
| Liens d’affichage | 20 actifs par tableau de bord ; 1 à 365 jours, 30 par défaut ; libellé de 80 caractères maximum |
| Débit de requêtes | Identique pour chaque clé d’API ; voir Erreurs et limites de débit |

