> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livefaces.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a workflow run

> Launch a fixed published workflow revision with initial inputs.

First [build, test, and publish your workflow](https://docs.livefaces.ai/workflows/test-and-publish.md). Call `POST /v1/workflow-runs` with `workflows:run` and a new **Idempotency-Key** for the intended run.

```bash theme={null}
curl --request POST 'https://api.livefaces.ai/v1/workflow-runs' \
  --header "Authorization: Bearer $LIVEFACES_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $WORKFLOW_ATTEMPT_ID" \
  --data '{
    "workflow_revision_id": "44444444-4444-4444-8444-444444444444",
    "inputs": {},
    "participant_identity": "customer-123"
  }'
```

Replace the example UUID with your published revision UUID. An empty `inputs` object works only if the workflow has no required inputs. Populate it with the fields defined on **Start** when needed.

| Field | Use |
| - | - |
| `workflow_revision_id` | Required UUID of the published revision to run. |
| `inputs` | Initial values matching the workflow's declared input fields. |
| `participant_identity` | Optional participant identifier; defaults to `browser`. |
| `tags`, `metadata` | Optional application labels and context. |

The published revision supplies the voice, face, node instructions, tools, and subflows. Voice, face, prompt, greeting, and MCP overrides are not accepted by this endpoint.

The `201` response uses the same connection fields as a [voice session](https://docs.livefaces.ai/api/start-session.md#response), plus `workflow_run_id`. Use the response's **`id`** with the session status, end, and transcript endpoints. The workflow-run ID and session ID identify different resources.

To release changes, publish a new revision and update the selected UUID in your application. Keep the same idempotency key and request body when retrying the same intended run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.