# Start a run

Start a run on a workflow. Send a request in the body and the run opens its first turn on it at once; send none to create an empty run you trigger later.

`POST https://api.momor.ai/workflow/workflows/{workflowId}/runs`

Authenticate with an API key of your Workflow organization, `Authorization: Bearer <key>`, or a signed-in session. API keys are created in [Settings › API keys](/settings/workflow/api-keys). The run belongs to whoever starts it, and only they can read it, trigger it and answer its questions.

## Path

- `workflowId` (uuid, required): The workflow’s id, as its upload returned it.

## Query

- `name` (string): The trigger the request addresses. Needed only where the workflow accepts more than one.
- `persistence` (string, default `Permanent`): How long the run is kept. Ephemeral runs are deleted after 30 minutes without activity, and only where the organization allows them. Values: `Permanent`, `Ephemeral`.
- `referenceId` (string): Your own reference for what the run is about, kept with the run.

## Body

The request, checked against the trigger’s schema before anything is created. Leave the body empty to start a run with no turn.

- `Prompt` (string): What the run is given to work on: a question, an instruction or a task.
- `Files` (file[]): Files sent with the prompt.
  - `Kind` (string, required): How the file is sent. Values: `url`, `bytes`, `handle`.
  - `name` (string, required): The file’s name.
  - `value` (string | object, required): For url, the file’s address; for bytes, its content in base64; for handle, a file Momor already stores.
  - `contentType` (string, required): Its media type, such as application/pdf.
- `<field>` (any): Any other field the trigger’s schema declares, sent as it is.

## Responses

| Status | Body |
| --- | --- |
| `202` | A request was sent: { turn } with the turn it opened. The steps run after the response. |
| `201` | No request was sent: the empty run. |

With `Accept: text/event-stream`, the response follows the turn instead: an `opened` frame with `runId` and `turnId`, every event the turn records, then a `closed` frame with the turn’s state once its ending has reported.

## Errors

| Status | Code | What happened |
| --- | --- | --- |
| `400` | `—` | The workflow can only be called by other workflows (Standalone: false). |
| `401` | `—` | No API key or session. |
| `404` | `—` | No workflow you can see has this id, or the request names a trigger the workflow does not accept, or names none where it accepts several. |
| `422` | `—` | The request does not match the trigger’s schema. The message says which field. |

Errors answer `{ "message": "…" }`. A refused request creates no run.

```bash title="Request"
curl -X POST "https://api.momor.ai/workflow/workflows/$WORKFLOW_ID/runs?referenceId=INV-20931" \
  -H "Authorization: Bearer $MOMOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Prompt": "Customer asks for a refund of $4,000 on invoice INV-20931.",
    "Files": [
      { "Kind": "url", "name": "photos.pdf", "value": "https://files.example.com/photos.pdf", "contentType": "application/pdf" }
    ]
  }'
```

```python
import os, requests

response = requests.post(
    f"https://api.momor.ai/workflow/workflows/{os.environ['WORKFLOW_ID']}/runs",
    params={"referenceId": "INV-20931"},
    headers={"Authorization": f"Bearer {os.environ['MOMOR_API_KEY']}"},
    json={"Prompt": "Customer asks for a refund of $4,000 on invoice INV-20931."},
)
turn = response.json()["turn"]
```

```typescript
const response = await fetch(`https://api.momor.ai/workflow/workflows/${workflowId}/runs?referenceId=INV-20931`, {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.MOMOR_API_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ Prompt: 'Customer asks for a refund of $4,000 on invoice INV-20931.' }),
});
const { turn } = await response.json();
```

```csharp
using var http = new HttpClient { BaseAddress = new Uri("https://api.momor.ai") };
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("MOMOR_API_KEY"));

var response = await http.PostAsJsonAsync(
    $"/workflow/workflows/{workflowId}/runs?referenceId=INV-20931",
    new { Prompt = "Customer asks for a refund of $4,000 on invoice INV-20931." });
```

```json title="Response"
{
  "turn": {
    "id": "0b8f6a1c-3e27-4c59-a0d4-91f2c7e85b36",
    "runId": "6d2e4b90-7a1f-4c83-b5e2-0f9a3c1d7e45",
    "state": "Running",
    "resultRef": null,
    "workflowContentHash": "9b1c…",
    "triggerEventId": "c41a…",
    "finalEventId": null,
    "failureCount": 0,
    "attemptNo": 1,
    "finalizedEventId": null,
    "rowVersion": "AAAAAAAAB9E=",
    "updatedAt": "2026-10-22T09:12:04Z",
    "tenantId": "2a7c…"
  }
}
```