Estas rutas permiten a un programa trabajar con los flujos del motor de automatización: mantener los flujos en control de versiones y desplegarlos, revertirlos, supervisar las ejecuciones y gestionar los mensajes fallidos. El funcionamiento de los flujos en la aplicación se explica en Flows y Versions, testing and rollback.
Las rutas están bajo https://<your host>/tenant/<tenantId>. Envía Authorization: Bearer <API key> en cada llamada; consulta Authentication. Los tiempos en esta API son milisegundos desde la época.
Permisos y claves de API
| Permiso | Rol por defecto | Permite |
|---|---|---|
automation.read | Admin | Leer flujos, versiones, ejecuciones sin contenido de los mensajes, mensajes fallidos sin su entrada, webhooks, uso |
automation.manage | Admin | Crear, guardar, desplegar, eliminar, restaurar, probar, importar y exportar flujos; reproducir y descartar mensajes fallidos |
automation.manage_privileged | Admin | Desplegar flujos con bloques de nivel de control |
automation.debug | Admin | Ver el contenido de los mensajes en ejecuciones y mensajes fallidos; probar a partir de mensajes registrados y del estado en vivo |
Una clave de API puede tener las cuatro. Un despliegue también pide los permisos que necesitan los bloques del flujo: un bloque Send command necesita el permiso de envío del nivel del comando (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical), y automation.manage_privileged cuando el comando es de alto impacto. Un método de comando en bruto necesita iot_rpc.send.raw, que solo tiene un Owner y ninguna clave puede tener, por lo que una clave no puede desplegar un flujo que envíe métodos en bruto.
Un flujo pertenece a un host: generic (el host General) o iot (el host IoT). Consulta Hosts, the root flow and profile root flows.
Rutas
| Método | Ruta | Permiso | Función |
|---|---|---|---|
| GET | /api/automation/flows | automation.read | Listar flujos |
| POST | /api/automation/flows | automation.manage | Crear un flujo como primer borrador (nunca desplegado, desactivado) |
| GET | /api/automation/flows/{flowId} | automation.read | El flujo, su contenido desplegado y su borrador compartido |
| PUT | /api/automation/flows/{flowId} | automation.manage | Guardar el borrador compartido |
| PATCH | /api/automation/flows/{flowId} | automation.manage | Cambiar la descripción |
| DELETE | /api/automation/flows/{flowId} | automation.manage | Eliminar (restaurable durante 7 días) |
| DELETE | /api/automation/flows/{flowId}/draft | automation.manage | Descartar el borrador |
| POST | /api/automation/flows/{flowId}/restore | automation.manage | Restaurar un flujo eliminado; vuelve desactivado |
| POST | /api/automation/flows/{flowId}/resume | automation.manage | Reanudar un flujo pausado |
| POST | /api/automation/flows/{flowId}/detach | automation.manage | Convertir el flujo de una regla en un flujo ordinario, de forma permanente |
| GET | /api/automation/flows/{flowId}/versions | automation.read | Versiones desplegadas, las más recientes primero, sin contenido |
| GET | /api/automation/flows/{flowId}/versions/{version} | automation.read | Una versión con su contenido |
| GET | /api/automation/flows/{flowId}/status | automation.read | El estado en vivo del flujo en ejecución |
| POST | /api/automation/deploy | automation.manage | Desplegar flujos y operaciones, todo o nada |
| POST | /api/automation/deploy/preflight | automation.manage | Lo que haría el mismo despliegue, sin hacerlo |
| POST | /api/automation/test | automation.manage | Ejecutar el borrador guardado una vez como simulación |
| GET | /api/automation/debug/runs?flowId= | automation.read | Ejecuciones registradas de un flujo |
| GET | /api/automation/debug/runs/{runId} | automation.read | Una ejecución con sus pasos |
| GET | /api/automation/flows/{flowId}/hooks | automation.read | Los webhooks del flujo |
| POST | /api/automation/flows/{flowId}/hooks/{nodeId}/rotate | automation.manage | Un nuevo secreto para un webhook |
| GET | /api/automation/dlq | automation.read | Mensajes fallidos |
| POST | /api/automation/dlq/{entryId}/replay | automation.manage | Reproducir un mensaje fallido |
| DELETE | /api/automation/dlq/{entryId} | automation.manage | Descartar un mensaje fallido |
| GET | /api/automation/export?ids= | automation.manage | Exportar flujos desplegados como archivo |
| POST | /api/automation/import | automation.manage | Previsualizar y, después, confirmar una importación |
| DELETE | /api/automation/import/{batchId} | automation.manage | Deshacer una importación |
| GET, POST | /api/automation/emergency-stop | lectura: automation.read; cambio: automation.manage | La parada de emergencia |
| GET | /api/automation/hosts | automation.read | Los hosts y si tu organización puede usarlos |
| GET | /api/automation/blocks?host= | automation.read | Los bloques disponibles en un host |
| GET | /api/automation/usage | automation.read | Las ejecuciones, pasos y tiempo de script de este mes, y los flujos frente a tu plan |
Listar y leer flujos
GET /api/automation/flows pagina desde 1, con 50 filas por defecto y como máximo 100. Filtros: host, kind, state (listas separadas por comas; los estados son running, disabled, invalid, not_approved, paused), enabled, owned (true para flujos de reglas, false para los ordinarios), updatedFrom / updatedTo (días), search, deleted=true (los flujos eliminados de los últimos 7 días), ids. Campos de ordenación: name, slug, host, kind, state, enabled, version, updatedAt, createdAt, deletedAt, sortOrder. La respuesta es { "flows": [...], "data": [...], "total": n, "page": 1, "pageSize": 50 }; data contiene las mismas filas.
Una fila de flujo tiene flowId, host, slug (el id fijo del flujo, ^[a-z0-9_-]{1,32}$), name, description, enabled, state, stateReason, version (la versión desplegada, 0 antes del primer despliegue), draftRev, deletedAt, createdAt, updatedAt, y ownerModule para un flujo que gestiona la tarjeta Rules.
GET /api/automation/flows/{flowId} responde { "flow", "current", "draft", "permissions" }: current es la versión desplegada con su content, draft el borrador compartido, y permissions qué de automation.manage, automation.manage_privileged y automation.debug tiene quien llama.
Contenido, borradores y creación de un flujo
El contenido de un flujo es { "id": "<slug>", "name": "…", "nodes": [...], "edges": [...] }. Un nodo es { "id", "type", "params", "name"?, "disabled"? }; una arista es { "from", "from_port", "to" }. Los tipos de bloque y sus parámetros se listan con GET /api/automation/blocks?host=generic y se describen desde Trigger blocks en adelante. La forma más sencilla de obtener un contenido válido es crear un flujo en el editor y leerlo con GET /api/automation/flows/{flowId}.
- Crear:
POST /api/automation/flowsconhost,kind(flow),slug,name(hasta 100 caracteres),descriptionytemplateopcionales. Responde201 { "flow" }. Un slug en uso devuelve409 slug_taken. - Guardar el borrador:
PUT /api/automation/flows/{flowId}con{ "draftRev": n, "draft": <content> }, dondedraftReves la revisión que leíste. Responde{ "draftRev" }con la nueva revisión; envíala con tu siguiente guardado. Si alguien guardó entre medias:409 { "error": "conflict", "draftRev", "by", "at", "theirs" }. Un borrador nunca se ejecuta.
Desplegar
POST /api/automation/deploy despliega a la vez cualquier número de flujos y operaciones, todo o nada.
| Campo | Significado |
|---|---|
items | Flujos a desplegar: host, kind, content, enabled, note opcional (hasta 500 caracteres). Para un flujo existente, flowId y baseVersion (la versión que leíste; 0 si nunca se desplegó). Sin flowId se crea un flujo nuevo. |
ops | Operaciones: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root |
confirm | Tus confirmaciones, por slug de flujo: { "<slug>": { "check": true } } o { "<slug>": { "typed": "<flow name>" } } |
Hasta 100 items y 100 ops; el contenido de cada flujo como máximo 1 MiB. Envía enabled explícitamente en cada item.
curl -X POST "https://<your host>/tenant/<tenantId>/api/automation/deploy" \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"items":[{"flowId":"9e8f…","baseVersion":4,"host":"generic","kind":"flow","enabled":true,"note":"Raise the threshold","content":{"id":"tank-alert","name":"Tank alert","nodes":[],"edges":[]}}]}'
La respuesta es { "deployRev", "versions": [ { "flowId", "slug", "kind", "version", "approved" } ], "plan", "dropped", "warnings"?, "notified" }. notified: false significa que el cambio está guardado y los workers lo recogen en menos de un minuto.
Confirmaciones
Un flujo con bloques de riesgo debe confirmarse, como en el diálogo de despliegue del editor. Sin confirmación, el despliegue responde 428:
{ "error": "confirm", "need": [ { "flow": "tank-alert", "name": "Tank alert", "level": "typed", "kinds": ["external"], "reasons": [ { "node": "n4", "type": "action.rpc", "risk": "external", "text": "…" } ], "permission": "automation.manage" } ] }
Envía el mismo cuerpo otra vez con confirm: { "check": true } para el nivel check, o { "typed": "Tank alert" } (el nombre del flujo, exactamente) para el nivel typed. Una aprobación se mantiene para el siguiente despliegue del mismo contenido por el mismo miembro, así que volver a desplegar contenido sin cambios no pide nada.
Usa POST /api/automation/deploy/preflight con el mismo cuerpo para ver la respuesta sin desplegar: no se escribe, bloquea ni audita nada.
Versiones y rollback
GET .../versions responde { "versions": [ { "version", "at", "by", "note", "mode", "hashShort", "approvedBy" } ] }. Para hacer rollback, despliega { "ops": [ { "op": "rollback", "flowId": "9e8f…", "version": 3 } ] }. Un rollback es una versión nueva con el contenido antiguo y requiere los mismos permisos y confirmaciones. El tiempo que se conservan las versiones está en Versiones, pruebas y rollback.
Probar el borrador
POST /api/automation/test ejecuta el borrador guardado una vez, en modo de simulación: los bloques que actúan fuera indican lo que harían, y no se escribe ni envía nada.
{ "flowId": "9e8f…", "mode": "flow", "nodeId": "trigger-1", "input": { "msgType": "inject", "payload": { "level": 92 }, "originator": { "type": "tenant", "id": "<tenantId>" } } }
mode es flow (entra por el disparador nodeId) o node (ejecuta solo nodeId). En lugar de un mensaje, input puede ser { "sample": "declaration" } (la muestra del bloque) o, con automation.debug, { "sample": "last_run" } o { "fromRun": { "runId", "step" } }. La respuesta tiene steps, outputs, would, errors, ms, truncated y state. Una prueba se detiene a los 2 segundos o a los 200 pasos. Cada miembro puede ejecutar 10 pruebas por minuto; si no, 429 rate_limited con Retry-After.
Ejecuciones y estado
GET /api/automation/debug/runs?flowId=<flowId or slug> lista las ejecuciones registradas, de la más reciente a la más antigua. Filtros: nodeId, status (ok, error, left_open, dropped), msgType, originatorType, originatorId, port, from y to (milisegundos), limit (como máximo 100) y cursor (el next de la página anterior). Sin automation.debug, las filas llegan sin el contenido de los mensajes. Solo aparece lo que conserva el nivel de registro del flujo; consulta Solución de problemas en flujos. Un tercer análisis simultáneo en tu organización responde 429.
GET /api/automation/flows/{flowId}/status responde { "status" }: líneas de estado de nodos, contadores, tasa y cola tal como los reportó por última vez el flujo en ejecución, o null antes del primer informe. El flujo en directo del editor es solo para personas que han iniciado sesión; un programa consulta esta ruta en su lugar.
Webhooks
GET /api/automation/flows/{flowId}/hooks lista los disparadores webhook de un flujo desplegado y activado: { "hooks": [ { "nodeId", "hookId", "auth", "reply", "path" } ] }. La respuesta nunca incluye un secreto.
POST .../hooks/{nodeId}/rotate crea un secreto nuevo y lo muestra una sola vez: { "hookId", "secret", "previousValidHours": 24 }. El secreto anterior sigue funcionando durante 24 horas; envía { "revokePrevious": true } para terminarlo de inmediato. Un webhook de tipo session no tiene secreto (409 no_secret).
Un programa que llama a un webhook no usa una clave de API: usa el secreto propio del hook, como se describe en Webhook en Bloques de disparo.
Mensajes fallidos
GET /api/automation/dlq lista los mensajes fallidos, de más reciente a más antiguo, con pageSize de hasta 200 (por defecto 50). Para la página siguiente, pasa next como before (o como after si ordenas por firstSeenAt:asc); next es null al final de la cola. Filtros: reason (tenant_backlog, decode_failed, poison, host_refused, run_abandoned, retries_exhausted, expired), flow (un slug), host (por defecto generic). La respuesta tiene total, byReason (contado sobre los 900 más recientes), entries y next. Cada entrada tiene id, reason, error, firstSeenAt, deliveries y, con automation.debug, la entrada original en fields.
POST /api/automation/dlq/{entryId}/replayresponde{ "replayed": true, "entryId" };404 gonesi ya se reprocesó o descartó,404 unreadablesi su entrada está dañada,429 backpressureconRetry-After: 30.DELETE /api/automation/dlq/{entryId}responde{ "discarded": true }.
Añade ?host=iot para la cola del host IoT. Un reprocesado puede repetir trabajo que hizo el primer intento; consulta Protecciones y mensajes fallidos.
Exportar e importar
- Exportar:
GET /api/automation/export?ids=<flowId>,<flowId>(de 1 a 100) responde{ "file", "skipped" }con la versión desplegada de cada flujo y las conexiones que usa. Los secretos nunca están en el archivo. - Vista previa de una importación:
POST /api/automation/importcon{ "file", "choices": { "<slug>": "replace" }, "host": "generic" }.choicesesreplace,copyoskippor cada slug que ya existe. No se escribe nada; la respuesta{ "preview" }contiene lo que cambiaría, las confirmaciones que incluye y unpreviewToken, válido durante 30 minutos. - Confirmar: el mismo cuerpo más
previewToken. Responde201 { "imported": { "importBatchId", … } }. Los flujos importados llegan desactivados y sin aprobar; introduce de nuevo sus secretos y, después, despliégalos. - Deshacer:
DELETE /api/automation/import/{importBatchId}(?dryRun=truepara ver el plan). Un flujo desplegado desde la importación se deja como está y aparece enskipped.
El archivo puede tener como máximo 5 MiB. Una confirmación responde 409 stale_preview cuando se desplegó algo después de la vista previa, 409 preview_expired después de 30 minutos y 409 token_mismatch cuando el token no coincide con el cuerpo. En cada caso, vuelve a hacer la vista previa.
Flujos de las reglas de la tarjeta Rules
Una regla de la tarjeta Rules se ejecuta como un flujo que la API de flujos lista con ownerModule. Guardar, desplegar, eliminar o reemplazarlo responde 409 owned_flow: cambia la regla a través de la API de Rules en su lugar. POST .../detach lo convierte en un flujo ordinario de forma definitiva: la regla se elimina y el flujo pasa a contar para el límite de flujos de tu plan.
Errores
Las denegaciones de las rutas de automatización incluyen un código error junto a los campos habituales:
| Estado | error | Significado |
|---|---|---|
| 400 | bad_request | La solicitud no es válida. Un cuerpo que incumple las reglas de campos es Validation error con issues. |
| 403 | forbidden | Un bloque del flujo necesita un permiso que la clave no tiene (missing) |
| 403 | (ninguno) | Un límite del plan: details.key max_flows o max_script_blocks, con limit, current, adding |
| 404 | not_found | “Flow not found.” o “Flow version not found.” |
| 409 | conflict | Alguien desplegó o guardó desde tu última lectura; la respuesta del despliegue contiene conflicts y current |
| 409 | in_use, slug_taken, owned_flow, not_owned | Todavía lo usa un flujo raíz u otro flujo (uses); el slug ya existe; el flujo de una regla; no es el flujo de una regla |
| 410 | expired | “The flow was deleted too long ago to restore.” |
| 413 | “The request body is too large.” | |
| 422 | invalid | El flujo no compila; problems enumera cada uno |
| 428 | confirm | Faltan confirmaciones; need las enumera |
| 503 | secrets_unavailable, owner_unavailable | Vuelve a intentarlo más tarde |
Consulta Errores y límites de frecuencia para el cuerpo general de los errores y los límites de frecuencia.
Límites
| Límite | Valor |
|---|---|
| Elementos y operaciones en un solo despliegue | 100 cada uno |
| Contenido del flujo, borrador | 1 MiB cada uno |
| Archivo de importación | 5 MiB |
| Nota del despliegue | 500 caracteres |
| Nombre y descripción del flujo | 100, 1.000 caracteres |
| Pruebas | 10 por minuto por miembro; 2 segundos y 200 pasos cada una |
| Ejecuciones por página de lista | 100 |
| Mensajes fallidos por página de lista | 200 |
| Restaurar un flujo eliminado | En un plazo de 7 días |
| Secreto de webhook anterior tras una rotación | 24 horas |
Los límites del plan y los límites de ejecución de los flujos están en Límites de flujos.

