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

API de Flows

Crea, guarda, despliega, prueba, revierte, restaura y exporta flujos por REST, lee sus ejecuciones y webhooks, y reenvía mensajes fallidos.

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

PermisoRol por defectoPermite
automation.readAdminLeer flujos, versiones, ejecuciones sin contenido de los mensajes, mensajes fallidos sin su entrada, webhooks, uso
automation.manageAdminCrear, guardar, desplegar, eliminar, restaurar, probar, importar y exportar flujos; reproducir y descartar mensajes fallidos
automation.manage_privilegedAdminDesplegar flujos con bloques de nivel de control
automation.debugAdminVer 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étodoRutaPermisoFunción
GET/api/automation/flowsautomation.readListar flujos
POST/api/automation/flowsautomation.manageCrear un flujo como primer borrador (nunca desplegado, desactivado)
GET/api/automation/flows/{flowId}automation.readEl flujo, su contenido desplegado y su borrador compartido
PUT/api/automation/flows/{flowId}automation.manageGuardar el borrador compartido
PATCH/api/automation/flows/{flowId}automation.manageCambiar la descripción
DELETE/api/automation/flows/{flowId}automation.manageEliminar (restaurable durante 7 días)
DELETE/api/automation/flows/{flowId}/draftautomation.manageDescartar el borrador
POST/api/automation/flows/{flowId}/restoreautomation.manageRestaurar un flujo eliminado; vuelve desactivado
POST/api/automation/flows/{flowId}/resumeautomation.manageReanudar un flujo pausado
POST/api/automation/flows/{flowId}/detachautomation.manageConvertir el flujo de una regla en un flujo ordinario, de forma permanente
GET/api/automation/flows/{flowId}/versionsautomation.readVersiones desplegadas, las más recientes primero, sin contenido
GET/api/automation/flows/{flowId}/versions/{version}automation.readUna versión con su contenido
GET/api/automation/flows/{flowId}/statusautomation.readEl estado en vivo del flujo en ejecución
POST/api/automation/deployautomation.manageDesplegar flujos y operaciones, todo o nada
POST/api/automation/deploy/preflightautomation.manageLo que haría el mismo despliegue, sin hacerlo
POST/api/automation/testautomation.manageEjecutar el borrador guardado una vez como simulación
GET/api/automation/debug/runs?flowId=automation.readEjecuciones registradas de un flujo
GET/api/automation/debug/runs/{runId}automation.readUna ejecución con sus pasos
GET/api/automation/flows/{flowId}/hooksautomation.readLos webhooks del flujo
POST/api/automation/flows/{flowId}/hooks/{nodeId}/rotateautomation.manageUn nuevo secreto para un webhook
GET/api/automation/dlqautomation.readMensajes fallidos
POST/api/automation/dlq/{entryId}/replayautomation.manageReproducir un mensaje fallido
DELETE/api/automation/dlq/{entryId}automation.manageDescartar un mensaje fallido
GET/api/automation/export?ids=automation.manageExportar flujos desplegados como archivo
POST/api/automation/importautomation.managePrevisualizar y, después, confirmar una importación
DELETE/api/automation/import/{batchId}automation.manageDeshacer una importación
GET, POST/api/automation/emergency-stoplectura: automation.read; cambio: automation.manageLa parada de emergencia
GET/api/automation/hostsautomation.readLos hosts y si tu organización puede usarlos
GET/api/automation/blocks?host=automation.readLos bloques disponibles en un host
GET/api/automation/usageautomation.readLas 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/flows con host, kind (flow), slug, name (hasta 100 caracteres), description y template opcionales. Responde 201 { "flow" }. Un slug en uso devuelve 409 slug_taken.
  • Guardar el borrador: PUT /api/automation/flows/{flowId} con { "draftRev": n, "draft": <content> }, donde draftRev es 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.

CampoSignificado
itemsFlujos 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.
opsOperaciones: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root
confirmTus 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}/replay responde { "replayed": true, "entryId" }; 404 gone si ya se reprocesó o descartó, 404 unreadable si su entrada está dañada, 429 backpressure con Retry-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/import con { "file", "choices": { "<slug>": "replace" }, "host": "generic" }. choices es replace, copy o skip por cada slug que ya existe. No se escribe nada; la respuesta { "preview" } contiene lo que cambiaría, las confirmaciones que incluye y un previewToken, válido durante 30 minutos.
  • Confirmar: el mismo cuerpo más previewToken. Responde 201 { "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=true para ver el plan). Un flujo desplegado desde la importación se deja como está y aparece en skipped.

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:

EstadoerrorSignificado
400bad_requestLa solicitud no es válida. Un cuerpo que incumple las reglas de campos es Validation error con issues.
403forbiddenUn 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
404not_found“Flow not found.” o “Flow version not found.”
409conflictAlguien desplegó o guardó desde tu última lectura; la respuesta del despliegue contiene conflicts y current
409in_use, slug_taken, owned_flow, not_ownedTodaví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
410expired“The flow was deleted too long ago to restore.”
413“The request body is too large.”
422invalidEl flujo no compila; problems enumera cada uno
428confirmFaltan confirmaciones; need las enumera
503secrets_unavailable, owner_unavailableVuelve 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ímiteValor
Elementos y operaciones en un solo despliegue100 cada uno
Contenido del flujo, borrador1 MiB cada uno
Archivo de importación5 MiB
Nota del despliegue500 caracteres
Nombre y descripción del flujo100, 1.000 caracteres
Pruebas10 por minuto por miembro; 2 segundos y 200 pasos cada una
Ejecuciones por página de lista100
Mensajes fallidos por página de lista200
Restaurar un flujo eliminadoEn un plazo de 7 días
Secreto de webhook anterior tras una rotación24 horas

Los límites del plan y los límites de ejecución de los flujos están en Límites de flujos.