*Workflows › Run*

# Workflows from the API and MCP

> From your own code or an AI assistant you can list the workflows of an account and start a run of one. You cannot read its result, and you cannot edit or create workflows.

## What exists

| To | REST API | MCP tool | Scope |
| --- | --- | --- | --- |
| List the workflows and how each starts | `GET /api/v1/workflows` | `filmo_workflows_list` | `workflows:read` |
| Start a run of a workflow | `POST /api/v1/workflows/{workflowId}/runs` | `filmo_workflows_run` | `workflows:run` |

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

## List the workflows

*List active workflows*

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

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

## Start a run

*Run a workflow (fictitious data)*

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

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

### Don't start the same run twice

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

## Who the run acts as

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

## Learning the outcome

Because you cannot poll, finish the workflow by telling your system. End it with an [HTTP request step](https://docs.filmo.io/workflows/http-requests) 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](https://docs.filmo.io/workflows/guides/push-to-your-system) shows the pattern.

## The MCP tools

| Tool | Annotations |
| --- | --- |
| `filmo_workflows_list` | Read-only, idempotent. Administrators only. |
| `filmo_workflows_run` | Marked as destructive (it can change data in the account) and as requiring the user's interaction: a well-behaved client asks the person before calling it. It is not idempotent unless you pass the idempotency key. |

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

## A write through the API can start workflows

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

> **Loops with your own system:** You cannot ask a request not to start workflows. If you load or import data through the API, check which workflows are live first, and consider an event trigger filter on `origin` so that your own writes do not start the workflows that push the same data back to you (one condition cannot exclude both API and MCP, and a change made in the app has no origin).

---

Canonical URL: https://docs.filmo.io/workflows/api-and-mcp  
Last updated: 2026-10-09