Workflows from the API and MCP

• There is no operation or tool that reads a run, cancels it, retries it, lists runs or calls you back when one ends. A run's progress is visible only in the Filmo app.
• There is no way to create, edit, publish or delete a workflow from the API or MCP, and no scope to write workflows. The read scope cannot run a workflow.
• Both operations are for administrators: an API key works only while its owner is an active administrator, and otherwise answers 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"

• It returns every workflow of the account that matches, including paused and archived ones and workflows with any trigger. Filter with isActive, triggerType or triggerTypes, and date ranges on createdAt and updatedAt. Sorting takes up to three fields (name, isActive, triggerType, createdAt, updatedAt); the default is by name. limit goes from 1 to 500 and defaults to 50.
• Each workflow has id, name, isActive, archivedAt, trigger and currentVersion (version and createdAt, or null if it was never published), createdAt and updatedAt. The definition, the integrations, the visibility, the creator and the run statistics are not returned.
• trigger is read from the published version: type (manual, schedule, webhook, event, signal, entity, or null if it was never published or its trigger is "from another workflow"), event and entity when they apply, and form.
• For a manual trigger, form lists the fields of the run form, each with a name, a label and a type. Every field in it is required in the payload of a run.

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"
  }
}

• The body is { "payload": { … } }, with one entry per field of the form. Unknown keys at the top level are rejected; unknown keys inside payload are ignored. A workflow without a form ignores payload.
• The request is asynchronous: it answers 201 with the id of the run and its state, queued, and does not wait for the run to finish.
• It does what the Run button does: it runs the published version, not the draft. A workflow that was never published answers 409.
• It does not check Live. A paused workflow can be run this way, like with the button.
• A missing or wrong field in the form answers 400 validation_error and queues nothing. (The app's own screen answers 422 for the same mistake.)
• A workflow of another account answers 404.
• The workflow whose trigger is "from another workflow" answers 409. The rest of the triggers are not rejected, but the endpoint is meant for the manual one. For a workflow started from a record, the payload needs entityId; the record must exist in the account.
• The limit is 120 requests a minute per key, with RateLimit-* headers.

Send an Idempotency-Key of 1 to 255 characters. The same key with the same body, within 24 hours, returns the stored response with Idempotent-Replay: true instead of queuing another run. The same key with a different body answers 422 idempotency_key_reused; a request still in flight answers 409. Without the header, two requests are two runs, exactly like two clicks on the button. The MCP tool generates a key for you if you do not give one. See Idempotency.

The run does not act as the owner of your API key. Every capability step runs with the permissions of the creator of the workflow, and the activity log records it as that workflow. The key only needs to be allowed to start it. Be careful with who creates the workflows you start from outside: a workflow can create and change data on its creator's behalf, and what it does depends on its steps.

Because you cannot poll, finish the workflow by telling your system. End it with an HTTP request step to an endpoint of yours, which receives the result and the run's own data. Add a branch that does the same on the failure paths you care about, and turn on «Notify me if it fails» for the rest. The guide Push changes to your own system shows the pattern.

• On the consent screen of an OAuth client, workflows:run always starts unchecked, even if the client asks for it. The administrator must tick it. It is shown with the write permissions, with a note that a workflow can create and change data on the administrator's behalf, depending on the steps it contains.
• When a token has workflows:run, the server's instructions to the assistant mention that it can run workflows.
• Details of the connection, scopes and safe use: MCP overview and Safe writes.

A change made through the REST API or MCP goes through the same path as the same change in the app, and fires the same events. An order you create with the API starts the workflows listening to the order-created event, with trigger_event.origin set to API (or MCP). That holds when the action behind the endpoint is one of the catalog events; which endpoints map to one is not listed per endpoint. See What a write through the API sets off.