Workflows desde la API y MCP

• No hay ninguna operación ni herramienta que lea una ejecución, la cancele, la reintente, liste ejecuciones o te avise cuando termine una. El progreso de una ejecución solo se ve en la app de Filmo.
• No hay forma de crear, editar, publicar ni eliminar un workflow desde la API o MCP, ni un scope para escribir workflows. El scope de lectura no puede ejecutar un workflow.
• Ambas operaciones son para administradores: una clave de API funciona solo mientras su propietario es un administrador activo, y si no responde 401.

curl -sS --fail-with-body "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/workflows?isActive=true&limit=50" \
  -H "Authorization: Bearer $FILMO_API_KEY"

• Devuelve todos los workflows de la cuenta que coinciden, incluidos los pausados y archivados y los workflows con cualquier trigger. Filtra con isActive, triggerType o triggerTypes, y rangos de fechas en createdAt y updatedAt. La ordenación admite hasta tres campos (name, isActive, triggerType, createdAt, updatedAt); por defecto, por name. limit va de 1 a 500 y por defecto es 50.
• Cada workflow tiene id, name, isActive, archivedAt, trigger y currentVersion (version y createdAt, o null si nunca se publicó), createdAt y updatedAt. No se devuelven la definición, las integraciones, la visibilidad, el creador ni las estadísticas de ejecución.
• trigger se lee de la versión publicada: type (manual, schedule, webhook, event, signal, entity, o null si nunca se publicó o su trigger es "Desde otro workflow"), event y entity cuando corresponden, y form.
• En un trigger manual, form lista los campos del formulario de la ejecución, cada uno con un name, un label y un type. Todos los campos son obligatorios en el payload de una ejecución.

curl -sS --fail-with-body -X POST "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Idempotency-Key: order-2026-0042-report" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"orderNumber":"P-2026-0042"}}'

{
  "data": {
    "runId": "run_example_001",
    "state": "queued"
  }
}

• El cuerpo es { "payload": { … } }, con una entrada por campo del formulario. Las claves desconocidas en el nivel superior se rechazan; las claves desconocidas dentro de payload se ignoran. Un workflow sin formulario ignora payload.
• La petición es asíncrona: responde 201 con el id de la ejecución y su estado, queued, y no espera a que la ejecución termine.
• Hace lo que hace el botón Ejecutar: ejecuta la versión publicada, no el borrador. Un workflow que nunca se ha publicado responde 409.
• No comprueba Live. Un workflow pausado se puede ejecutar así, como con el botón.
• Un campo que falta o es incorrecto en el formulario responde 400 validation_error y no pone nada en cola. (La propia pantalla de la app responde 422 para el mismo error.)
• Un workflow de otra cuenta responde 404.
• El workflow cuyo trigger es "Desde otro workflow" responde 409. El resto de triggers no se rechazan, pero el endpoint está pensado para el manual. Para un workflow iniciado desde un registro, el payload necesita entityId; el registro debe existir en la cuenta.
• El límite es de 120 peticiones por minuto y clave, con cabeceras RateLimit-*.

Envía una Idempotency-Key de 1 a 255 caracteres. La misma clave con el mismo cuerpo, dentro de 24 horas, devuelve la respuesta guardada con Idempotent-Replay: true en lugar de poner en cola otra ejecución. La misma clave con un cuerpo distinto responde 422 idempotency_key_reused; una petición que sigue en curso responde 409. Sin la cabecera, dos peticiones son dos ejecuciones, igual que dos clics en el botón. La herramienta MCP genera una clave por ti si no das ninguna. Consulta Idempotencia.

La ejecución no actúa como el dueño de tu clave de API. Cada paso de capacidad se ejecuta con los permisos del creador del workflow, y el registro de actividad lo anota como ese workflow. La clave solo necesita tener permiso para iniciarlo. Ten cuidado con quién crea los workflows que inicias desde fuera: un workflow puede crear y modificar datos en nombre de su creador, y lo que hace depende de sus pasos.

Como no puedes hacer polling, termina el workflow avisando a tu sistema. Acábalo con un Paso de petición HTTP a un endpoint tuyo, que recibe el resultado y los datos propios de la ejecución. Añade una rama que haga lo mismo en las vías de fallo que te importen, y activa «Avisar si falla» para el resto. La guía Enviar cambios a tu propio sistema muestra el patrón.

• En la pantalla de consentimiento de un cliente OAuth, workflows:run empieza siempre sin marcar, aunque el cliente lo pida. El administrador debe marcarlo. Se muestra junto a los permisos de escritura, con una nota de que un workflow puede crear y cambiar datos en nombre del administrador, según los pasos que contenga.
• Cuando un token tiene workflows:run, las instrucciones del servidor al asistente mencionan que puede ejecutar workflows.
• Detalles de la conexión, scopes y uso seguro: Resumen de MCP y Escrituras seguras.

Un cambio hecho a través de la API REST o de MCP sigue el mismo camino que el mismo cambio en la app y dispara los mismos eventos. Un pedido que creas con la API inicia los workflows que escuchan el evento de pedido creado, con trigger_event.origin igual a API (o MCP). Eso vale cuando la acción que hay detrás del endpoint es uno de los eventos del catálogo; no se indica endpoint por endpoint cuáles lo son. Consulta Qué desencadena una escritura a través de la API.