Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

API de tableros

Rutas para listar, leer, crear, modificar, copiar, exportar e importar tableros, iniciarlos desde plantillas y gestionar enlaces de visualización desde código.

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 tiene dashboard.boards.read. Para modificar, eliminar o crear uno también se necesita dashboard.boards.manage en la propia clave.
  • Paneles personales (scope: "PRIVATE") son propiedad del titular de la clave. Un panel personal de otro miembro responde 404, 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étodoRutaPermisoFunción
GET/api/dashboard/boardsdashboard.boards.readLista los paneles que la clave puede abrir
POST/api/dashboard/boardsdashboard.boards.writeCrea un panel vacío
GET/api/dashboard/boards/{boardId}dashboard.boards.readUn panel con sus tarjetas
PATCH/api/dashboard/boards/{boardId}dashboard.boards.writeCambia título, descripción, icono, cuadrícula, ventana temporal, parámetros, páginas; comparte un panel personal
DELETE/api/dashboard/boards/{boardId}dashboard.boards.writeElimina el panel y sus tarjetas
POST/api/dashboard/boards/{boardId}/duplicatedashboard.boards.writeCopia un panel
GET/api/dashboard/boards/{boardId}/exportdashboard.boards.readEl panel como archivo de panel
POST/api/dashboard/boards/importdashboard.boards.writeComprueba (simulación) o importa un archivo de panel
GET/api/dashboard/boards/templates?for=newdashboard.boards.readPlantillas desde las que puede empezar un panel nuevo
POST/api/dashboard/boards/templates/{templateKey}/applydashboard.boards.writeCrea un panel a partir de una plantilla
GET, POST/api/dashboard/boards/{boardId}/display-linksdashboard.boards.manageLista los enlaces de visualización de un panel, o crea uno
DELETE/api/dashboard/boards/{boardId}/display-links/{linkId}dashboard.boards.manageRevoca 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:

CampoRegla
titleObligatorio, de 1 a 120 caracteres
descriptionHasta 1.000 caracteres
iconHasta 64 caracteres
scopeTENANT (por defecto) o PRIVATE; una clave sin dashboard.boards.manage debe enviar PRIVATE
workspace o moduleIdEl menú de espacio de trabajo que muestra el panel; no ambos
isDefaulttrue hace que sea el panel que abre primero su menú de espacio de trabajo
gridCols12 (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 .../export responde con el propio archivo (Content-Disposition: attachment). Añade report=1 para obtener { package, skipped } como JSON. Añade linked=1 para incluir, en un solo archivo, los paneles que abren las acciones de este panel (hasta 20 paneles; leftOut nombra los que quedaron fuera).
  • POST /api/dashboard/boards/import recibe { "package": <the file>, "dryRun": true, "title": "…", "scope": "PRIVATE" }. dryRun es true por defecto: la respuesta { dryRun: true, report } indica lo que se importaría, repararía u omitiría, y no escribe nada. Envía "dryRun": false para crear el panel: 201 { dryRun: false, board, report }. En un archivo de varios paneles, boards lista 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).

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

EstadoMensaje
400Validation error con issues (un campo desconocido, un valor fuera de rango)
403Solo un administrador puede crear o cambiar un tablero compartido
403Su plan no permite más tableros compartidos (details.reason shared_board_limit, con used y limit)
403Ha alcanzado el límite de tableros personales (personal_board_limit)
403No tiene permiso para colocar este widget (una plantilla cuyas tarjetas el titular no puede usar)
404Tablero no encontrado / Plantilla de tablero desconocida
409Este tablero fue modificado por otra persona desde que lo cargó
409Un 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)
409Este tablero ya tiene el máximo de enlaces de visualización activos
422Un widget privado no puede colocarse en un tablero compartido (al compartir un tablero con estas tarjetas; details.placements las nombra)
422Una copia personal que sustituye a un tablero compartido no puede compartirse; duplíquela como tablero compartido en su lugar
422Este 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ímiteValor
Tableros compartidosLo fija su plan; consulte Uso y cuotas
Tableros personales20 por miembro (el titular de la clave)
Tarjetas en un archivo de tablero200
Tableros en un archivo vinculado20
Enlaces de visualización20 activos por tablero; de 1 a 365 días, por defecto 30; etiqueta de hasta 80 caracteres
Límite de peticionesIgual que para cada clave de API; consulte Errores y límites de peticiones