*Workflows › Ejecutar*

# Workflows desde la API y MCP

> Desde tu propio código o un asistente de IA puedes listar los workflows de una cuenta e iniciar una ejecución de uno. No puedes leer su resultado ni editar o crear workflows.

## Qué existe

| Para | API REST | Herramienta MCP | Permiso (scope) |
| --- | --- | --- | --- |
| Listar los workflows y cómo se inicia cada uno | `GET /api/v1/workflows` | `filmo_workflows_list` | `workflows:read` |
| Iniciar una ejecución de un workflow | `POST /api/v1/workflows/{workflowId}/runs` | `filmo_workflows_run` | `workflows:run` |

- 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.

## Listar los workflows

*Listar workflows activos*

```bash
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.

## Iniciar una ejecución

*Ejecutar un workflow (datos ficticios)*

```bash
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"}}'
```

*201 Created*

```json
{
  "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-*`.

### No inicies dos veces la misma ejecución

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](https://docs.filmo.io/es/rest-api/guides/idempotency).

## Como quién actúa la ejecución

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](https://docs.filmo.io/es/workflows/permissions#run-actor), 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.

## Conocer el resultado

Como no puedes hacer polling, termina el workflow avisando a tu sistema. Acábalo con un [Paso de petición HTTP](https://docs.filmo.io/es/workflows/http-requests) 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](https://docs.filmo.io/es/workflows/guides/push-to-your-system) muestra el patrón.

## Las herramientas MCP

| Herramienta | Anotaciones |
| --- | --- |
| `filmo_workflows_list` | Solo lectura, idempotente. Solo administradores. |
| `filmo_workflows_run` | Marcada como destructiva (puede cambiar datos de la cuenta) y como que requiere la interacción del usuario: un cliente bien comportado pregunta a la persona antes de llamarla. No es idempotente a menos que pases la clave de idempotencia. |

- 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](https://docs.filmo.io/es/mcp/overview) y [Escrituras seguras](https://docs.filmo.io/es/mcp/guides/safe-writes).

## Una escritura por la API puede iniciar workflows

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](https://docs.filmo.io/es/workflows/overview#writes-set-off-workflows).

> **Bucles con tu propio sistema:** No puedes pedir a una petición que no inicie workflows. Si cargas o importas datos por la API, comprueba antes qué workflows están live, y considera un filtro de trigger de evento sobre `origin` para que tus propias escrituras no inicien los workflows que te devuelven los mismos datos (una sola condición no puede excluir a la vez API y MCP, y un cambio hecho en la app no tiene origin).

---

URL canónica: https://docs.filmo.io/es/workflows/api-and-mcp  
Última actualización: 2026-10-09