Estas rutas permiten que un script u otro sistema trabaje con los paneles (dashboards): obtener una lista de ellos, copiar un panel, guardarlo como archivo de respaldo, moverlo a otra organización o crear paneles a partir de plantillas. Cómo funcionan los paneles para las personas se explica en Create and organise boards y Sharing dashboards.
Las rutas están bajo https://<your host>/tenant/<tenantId>. Las convenciones (cuerpos estrictos, errores, límites de tasa) están en REST API basics.
De qué paneles ve una clave
Una clave actúa como el miembro que la posee (ver Authentication). En cuanto a los paneles, esto significa:
- Paneles compartidos (
scope: "TENANT") son visibles para la clave cuando tienedashboard.boards.read. Para modificar, eliminar o crear uno también se necesitadashboard.boards.manageen la propia clave. - Paneles personales (
scope: "PRIVATE") son propiedad del titular de la clave. Un panel personal de otro miembro responde404, igual que un panel que no existe. - Una tarjeta cuyo widget el titular no puede ver se omite de las copias y los archivos, y se nombra en
skipped.
Rutas
| Método | Ruta | Permiso | Función |
|---|---|---|---|
| GET | /api/dashboard/boards | dashboard.boards.read | Lista los paneles que la clave puede abrir |
| POST | /api/dashboard/boards | dashboard.boards.write | Crea un panel vacío |
| GET | /api/dashboard/boards/{boardId} | dashboard.boards.read | Un panel con sus tarjetas |
| PATCH | /api/dashboard/boards/{boardId} | dashboard.boards.write | Cambia título, descripción, icono, cuadrícula, ventana temporal, parámetros, páginas; comparte un panel personal |
| DELETE | /api/dashboard/boards/{boardId} | dashboard.boards.write | Elimina el panel y sus tarjetas |
| POST | /api/dashboard/boards/{boardId}/duplicate | dashboard.boards.write | Copia un panel |
| GET | /api/dashboard/boards/{boardId}/export | dashboard.boards.read | El panel como archivo de panel |
| POST | /api/dashboard/boards/import | dashboard.boards.write | Comprueba (simulación) o importa un archivo de panel |
| GET | /api/dashboard/boards/templates?for=new | dashboard.boards.read | Plantillas desde las que puede empezar un panel nuevo |
| POST | /api/dashboard/boards/templates/{templateKey}/apply | dashboard.boards.write | Crea un panel a partir de una plantilla |
| GET, POST | /api/dashboard/boards/{boardId}/display-links | dashboard.boards.manage | Lista los enlaces de visualización de un panel, o crea uno |
| DELETE | /api/dashboard/boards/{boardId}/display-links/{linkId} | dashboard.boards.manage | Revoca un enlace de visualización |
Toda escritura que cree o cambie un panel compartido también necesita dashboard.boards.manage; sin él la respuesta es 403 «Only an admin may create or change a shared dashboard». Roles por defecto: lectura y escritura son permisos de Usuario; manage es un permiso de Administrador.
El editor de paneles y la vista de panel en el navegador usan otras rutas (colocar y mover tarjetas, ejecutar la consulta de una tarjeta, la biblioteca de widgets, la copia que se guarda mientras personalizas). No forman parte de esta referencia. Para cambiar tarjetas desde código, exporta el panel, edita el archivo e impórtalo.
Listar paneles
GET /api/dashboard/boards sin parámetros de paginación devuelve todos los paneles que la clave puede abrir:
{
"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
}
Con page o pageSize devuelve una página como { "data": [...], "total": n, "canManage": true }. Las páginas empiezan en 0; pageSize va de 1 a 100 (por defecto 20); search hasta 200 caracteres; sort por title, updatedAt, scope o workspace (por defecto updatedAt:desc); filtros scope (TENANT, PRIVATE) y workspace (una lista separada por comas; none para paneles en ningún menú de espacio de trabajo). Añade quota=1 para obtener sharedQuota: { used, limit } (limit null: sin límite) cuando la clave tiene dashboard.boards.manage.
GET /api/dashboard/boards/{boardId} devuelve { board, instances, widgets, pinned }: el panel, sus tarjetas (posición, tamaño, título, ajustes, enlaces de datos y acciones) y los widgets que usan.
Crear, cambiar y eliminar
POST /api/dashboard/boards recibe:
| Campo | Regla |
|---|---|
title | Obligatorio, de 1 a 120 caracteres |
description | Hasta 1.000 caracteres |
icon | Hasta 64 caracteres |
scope | TENANT (por defecto) o PRIVATE; una clave sin dashboard.boards.manage debe enviar PRIVATE |
workspace o moduleId | El menú de espacio de trabajo que muestra el panel; no ambos |
isDefault | true hace que sea el panel que abre primero su menú de espacio de trabajo |
gridCols | 12 (por defecto) o 24 |
La respuesta es 201 { "board": {...} }. El slug se genera a partir del título; no puedes enviarlo.
PATCH recibe los mismos campos (excepto workspace y moduleId) más settings, timeWindow, params, filters, pages y mainPage, y solo cambia lo que envíes. Envía expectedRevision (el revision del panel al leerlo) para que se rechace con 409 «This dashboard was changed by someone else since you loaded it» en lugar de sobrescribir un cambio más reciente. "scope": "TENANT" comparte un panel personal; un panel compartido nunca vuelve a ser personal. DELETE responde { "ok": true }.
Copiar un panel
POST /api/dashboard/boards/{boardId}/duplicate con { "title": "Cold rooms (night shift)", "scope": "PRIVATE" } (ambos opcionales; el título por defecto añade » (copy)», el scope por defecto es PRIVATE). La respuesta es 201 { board, skipped, droppedCommands }: skipped lista las tarjetas cuyo widget no pudo copiarse, y droppedCommands cuenta las acciones de comando que el titular de la clave no puede configurar, que se han eliminado.
Archivos de panel: exportar e importar
El formato del archivo y su contenido se explican en Board templates and board files.
GET .../exportresponde con el propio archivo (Content-Disposition: attachment). Añadereport=1para obtener{ package, skipped }como JSON. Añadelinked=1para incluir, en un solo archivo, los paneles que abren las acciones de este panel (hasta 20 paneles;leftOutnombra los que quedaron fuera).POST /api/dashboard/boards/importrecibe{ "package": <the file>, "dryRun": true, "title": "…", "scope": "PRIVATE" }.dryRunestruepor defecto: la respuesta{ dryRun: true, report }indica lo que se importaría, repararía u omitiría, y no escribe nada. Envía"dryRun": falsepara crear el panel:201 { dryRun: false, board, report }. En un archivo de varios paneles,boardslista cada panel creado; se crean todos juntos o ninguno.
Una clave solo funciona en su propia organización, así que mover un panel requiere una clave en cada una:
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 @-
Lee report.issues y después envía el mismo cuerpo con "dryRun": false.
Empezar desde una plantilla
GET /api/dashboard/boards/templates?for=new lista las plantillas desde las que puede empezar un panel nuevo: key, title, description, cardCount, pageCount, paramCount y, para una plantilla que hace una pregunta, ask. No se listan las plantillas de módulos desactivados en tu organización.
POST /api/dashboard/boards/templates/{templateKey}/apply con asNew crea un tablero nuevo:
{
"asNew": { "title": "Plant sites", "scope": "TENANT", "description": null, "workspace": null },
"answers": { "sites": { "choose": "all" } }
}
answers solo sirve para una plantilla que hace una pregunta: la clave es el ask.param de la plantilla, y el valor es uno de { "choose": "all" }, { "choose": "subtype", "subtype": "…" } o { "choose": "under", "entityId": "…" }. La respuesta es 201 { board, created: true, skipped, droppedCommands }. Con { "boardId": "…" } en lugar de asNew, las tarjetas de la plantilla se añaden debajo de las tarjetas de un tablero existente (200, created: false).
Enlaces de visualización
Un enlace de visualización muestra un tablero en una pantalla donde nadie inicia sesión. POST .../display-links con { "label": "Lobby TV", "expiresInDays": 30 } responde 201 { link, token, url }; el token y la dirección solo aparecen en esta respuesta. El emisor del enlace es el titular de la clave, y la pantalla muestra el tablero con los permisos del titular. GET lista los enlaces (status active, expired o revoked) sin tokens; DELETE .../display-links/{linkId} revoca uno. Consulte Pantallas de pared, pantalla completa y zoom.
Errores
| Estado | Mensaje |
|---|---|
| 400 | Validation error con issues (un campo desconocido, un valor fuera de rango) |
| 403 | Solo un administrador puede crear o cambiar un tablero compartido |
| 403 | Su plan no permite más tableros compartidos (details.reason shared_board_limit, con used y limit) |
| 403 | Ha alcanzado el límite de tableros personales (personal_board_limit) |
| 403 | No tiene permiso para colocar este widget (una plantilla cuyas tarjetas el titular no puede usar) |
| 404 | Tablero no encontrado / Plantilla de tablero desconocida |
| 409 | Este tablero fue modificado por otra persona desde que lo cargó |
| 409 | Un parámetro del tablero todavía lo usa un enlace de un widget y no puede eliminarse (lo mismo para una página o un filtro que sigue en uso) |
| 409 | Este tablero ya tiene el máximo de enlaces de visualización activos |
| 422 | Un widget privado no puede colocarse en un tablero compartido (al compartir un tablero con estas tarjetas; details.placements las nombra) |
| 422 | Una copia personal que sustituye a un tablero compartido no puede compartirse; duplíquela como tablero compartido en su lugar |
| 422 | Este archivo usa un formato de paquete de tableros que esta aplicación no puede importar / fue exportado por una versión más reciente |
Límites
| Límite | Valor |
|---|---|
| Tableros compartidos | Lo fija su plan; consulte Uso y cuotas |
| Tableros personales | 20 por miembro (el titular de la clave) |
| Tarjetas en un archivo de tablero | 200 |
| Tableros en un archivo vinculado | 20 |
| Enlaces de visualización | 20 activos por tablero; de 1 a 365 días, por defecto 30; etiqueta de hasta 80 caracteres |
| Límite de peticiones | Igual que para cada clave de API; consulte Errores y límites de peticiones |

