---
title: "Flows - Run a flow"
method: POST
path: "/v1/ai/flows/{flow-id}/run"
tags: ["flows"]
---

# Flows - Run a flow

`POST /v1/ai/flows/{flow-id}/run`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/ai/flows/{flow-id}/run`
- Auth: API key in header `x-magnific-api-key`

Triggers the execution of a flow. Provide values for all required inputs
defined in the flow's definition (see the GET endpoint).

The `inputs` object maps each input's `api_key` (recommended) or its `id` (UUID, legacy) to its value:

| Input Type | Accepted Values |
|------------|----------------|
| `creation` | Image URL (`https://...`), base64-encoded image string, or existing creation identifier |
| `text` | Plain text string |
| `number` | Numeric value |
| `select` | Value from allowed options |

**This endpoint is asynchronous.** It returns immediately with `status: "running"` and a
`workflow_run_identifier`. Provide a `webhook` URL to receive notifications when the execution
completes. The webhook receives two events: `initialized` (run started) and `finished`/`failed` (run completed).

The webhook payload for a completed run includes a `result` object containing `images`, `videos`,
and `audios` arrays with download URLs for the generated assets.

## Path parameters

- `flow-id` string, required

## Request body

- RunRequest
  - `inputs` object, required: Map of input identifier to value. Use each input's `api_key` (recommended) or its `id` (UUID, legacy) as the key — both are accepted. Value types by input type: - `creation` (image/media): URL string, base64-encoded string, or existing creation sqid - `text`: Plain text string - `number`: Numeric value - `select`: Value from allowed options
  - `webhook` string, uri: Optional callback URL that receives status notifications during execution. The webhook receives POST requests with the event payload (see webhook event schema). Events are sent when the run starts (`initialized`) and when it finishes (`finished` or `failed`).

## Response `202`

Accepted - Flow execution started. Use the webhook to receive results.

- InlineObject8
  - `status` 'running', required: Current execution status.
  - `workflow_run_identifier` string, required: Unique identifier for this flow execution run. Matches the `run_id` in webhook events.

## Other responses

- `400`: Bad Request - The server could not understand the request due to invalid syntax.
- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `404`: Flow not found.
- `422`: Validation error on input values.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)