Start a workflow run

First build, test, and publish your workflow. Call POST /v1/workflow-runs with workflows:run and a new Idempotency-Key for the intended run.

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

Get started

Console

Workflows

Session API

API reference

Help

Start a workflow run