Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

API Boards

Routes pour lister, lire, créer, modifier, copier, exporter et importer des tableaux de bord, les démarrer à partir de modèles et gérer les liens d'affichage depuis le code.

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étient dashboard.boards.read. Les modifier, les supprimer ou en créer un nécessite aussi dashboard.boards.manage sur la clé elle-même.
  • Tableaux personnels (scope: "PRIVATE") : appartiennent au titulaire de la clé. Le tableau personnel d’un autre membre répond 404, 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éthodeCheminPermissionAction
GET/api/dashboard/boardsdashboard.boards.readLister les tableaux que la clé peut ouvrir
POST/api/dashboard/boardsdashboard.boards.writeCréer un tableau vide
GET/api/dashboard/boards/{boardId}dashboard.boards.readUn tableau avec ses cartes
PATCH/api/dashboard/boards/{boardId}dashboard.boards.writeModifier 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.writeSupprimer le tableau et ses cartes
POST/api/dashboard/boards/{boardId}/duplicatedashboard.boards.writeCopier un tableau
GET/api/dashboard/boards/{boardId}/exportdashboard.boards.readLe tableau sous forme de fichier de tableau
POST/api/dashboard/boards/importdashboard.boards.writeVérifier (essai à blanc) ou importer un fichier de tableau
GET/api/dashboard/boards/templates?for=newdashboard.boards.readModèles à partir desquels un nouveau tableau peut être créé
POST/api/dashboard/boards/templates/{templateKey}/applydashboard.boards.writeCréer un tableau à partir d’un modèle
GET, POST/api/dashboard/boards/{boardId}/display-linksdashboard.boards.manageLister les liens d’affichage d’un tableau, ou en créer un
DELETE/api/dashboard/boards/{boardId}/display-links/{linkId}dashboard.boards.manageRé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 :

ChampRègle
titleObligatoire, de 1 à 120 caractères
descriptionJusqu’à 1 000 caractères
iconJusqu’à 64 caractères
scopeTENANT (par défaut) ou PRIVATE ; une clé sans dashboard.boards.manage doit envoyer PRIVATE
workspace ou moduleIdLe menu d’espace de travail qui affiche le tableau ; pas les deux
isDefaulttrue en fait le tableau ouvert en premier par le menu de son espace de travail
gridCols12 (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 .../export renvoie le fichier lui-même (Content-Disposition: attachment). Ajoutez report=1 pour obtenir { package, skipped } en JSON à la place. Ajoutez linked=1 pour inclure, dans un seul fichier, les tableaux ouverts par les actions de ce tableau (jusqu’à 20 tableaux ; leftOut nomme ceux qui ne sont pas repris).
  • POST /api/dashboard/boards/import accepte { "package": <the file>, "dryRun": true, "title": "…", "scope": "PRIVATE" }. dryRun vaut true par défaut : la réponse { dryRun: true, report } indique ce qui serait importé, réparé ou ignoré, sans rien écrire. Envoyez "dryRun": false pour créer le tableau : 201 { dryRun: false, board, report }. Pour un fichier contenant plusieurs tableaux, boards liste 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).

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

StatutMessage
400Validation error avec issues (un champ inconnu, une valeur hors plage)
403Seul un administrateur peut créer ou modifier un tableau de bord partagé
403Votre offre n’autorise plus de tableaux de bord partagés (details.reason shared_board_limit, avec used et limit)
403Vous avez atteint la limite de tableaux de bord personnels (personal_board_limit)
403Vous n’êtes pas autorisé à placer ce widget (un modèle dont le titulaire ne peut pas utiliser les cartes)
404Tableau de bord introuvable / Modèle de tableau de bord inconnu
409Ce tableau de bord a été modifié par une autre personne depuis que vous l’avez chargé
409Un 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é)
409Ce tableau de bord a déjà atteint le nombre maximal de liens d’affichage actifs
422Un widget privé ne peut pas être placé sur un tableau de bord partagé (partager un tableau contenant de telles cartes ; details.placements les nomme)
422Une 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é
422Ce 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

LimiteValeur
Tableaux de bord partagésDéfini par votre offre ; voir Utilisation et quotas
Tableaux de bord personnels20 par membre (le titulaire de la clé)
Cartes dans un fichier de tableau de bord200
Tableaux de bord dans un fichier lié20
Liens d’affichage20 actifs par tableau de bord ; 1 à 365 jours, 30 par défaut ; libellé de 80 caractères maximum
Débit de requêtesIdentique pour chaque clé d’API ; voir Erreurs et limites de débit