Start a workflow run
Start a workflow with your inputs and get a run id back.
POST {base_url}/workflow-runsRequires runs:write.
Request
POST {base_url}/workflow-runs
Authorization: Bearer mor_live_…
Content-Type: application/json
{
"org_id": "0192f3c1-7a44-7d10-9b22-1e5c8f0a3b61",
"project_id": "0192f3c2-4b18-7e93-8c07-9d2a6f4e1c58",
"workflow_id": "0192f3c3-9d21-7c44-b8e1-5a7f2c9d4e10",
"workflow_version_id": "0192f3c4-1a02-7bb3-9f40-2c6e8d1a5b77",
"idempotency_key": "story-48213-v2",
"inputs": {
"story_document": "https://cdn.example.com/stories/48213.pdf",
"character_sheets": [
"https://cdn.example.com/chars/48213-a.png",
"https://cdn.example.com/chars/48213-b.png"
],
"episode_count": 8,
"tone": "thriller"
}
}| Body field | Required | Meaning |
|---|---|---|
org_id | yes | your organization; must match the key's |
project_id | yes | the canvas the run and its assets land in — the id in its Studio URL, …/editor/<project_id>/canvas |
workflow_id | yes | the workflow to run |
inputs | yes | an object keyed by each input's key |
idempotency_key | recommended | makes a retry safe — see Conventions |
workflow_version_id | no | pins the version you read the inputs from |
webhook_id | no | sends this run's events to one registered endpoint — see Webhooks |
How to send each input
accepts | Send | With allow_multiple |
|---|---|---|
value | the string, number or boolean itself | an array of them |
url | one public HTTPS link, as a string | an array of links |
option | one options[].id, exactly as given | an array of ids |
Response
202 Accepted
{
"run": {
"id": "0192f3d0-6c31-7a52-b4e8-3f9d1a7c5e20",
"status": "queued",
"workflow_id": "0192f3c3-9d21-7c44-b8e1-5a7f2c9d4e10",
"workflow_version_id": "0192f3c4-1a02-7bb3-9f40-2c6e8d1a5b77",
"project_id": "0192f3c2-4b18-7e93-8c07-9d2a6f4e1c58",
"chat_id": "0192f3c6-2e75-7b14-9a63-7c4e2d8f1b09",
"ingested": [
{ "input": "story_document", "bytes": 184320, "mime_type": "application/pdf" },
{ "input": "character_sheets", "bytes": 962144, "mime_type": "image/png" },
{ "input": "character_sheets", "bytes": 883021, "mime_type": "image/png" }
],
"poll_after_seconds": 60,
"expires_at": "2026-09-23T04:10:00Z"
}
}| Response field | Meaning |
|---|---|
id | the run id. Poll it, and keep it against your own record |
status | queued on acceptance |
chat_id | the Studio session the run happens in. Open it to watch the run or answer a question it asks |
ingested | one entry per file fetched, in the order sent. Useful for confirming you sent what you meant to |
poll_after_seconds | how long to wait before the first poll |
expires_at | when an unfinished run is abandoned as expired |
Every link is fetched and verified before the 202. A run that comes back accepted has its files in hand, so a bad link is an immediate 400 rather than a failure ten minutes later.