---
title: Run a workflow
description: POST /workflows/{workflowId}/runs creates the case, receives the packet and starts the run, in one call.
section: API
order: 4
---

```
POST /workflows/{workflowId}/runs
```

One call does what a person does in the app: start a case, drop the packet in, take the gate with a workflow attached. The call itself is the consent to spend on the run, and is recorded as such.

## Fields

Sent as `multipart/form-data`.

| Field | Required | Meaning |
| --- | --- | --- |
| `files` | yes, for a new case | One or more PDFs. Up to 25 files, 100 MB each. Repeat the field for several files. |
| `applicant` | yes, for a new case | The applicant's name. |
| `expectedDocList` | yes, for a new case | `expectedDocListId` for its active version, or `expectedDocListId/3` for a specific one. |
| `applicationId` | instead of the two above | Run on an existing case. Files are optional then. |
| `decidedBy` | no | Who consents to the run. Defaults to the key's name. |

## Versions

The workflow's **active** version runs. `?version=2` pins one. A missing version answers 404 and a draft answers 409, both before anything is written. Publishing a new version changes what callers get without changing what they call.

## The answer

`201` with the case. `run.state` is `previewing` or `running`, depending on whether the workflow begins with a preview. From here, [read the results](/docs/api/reading-results).

## An existing case

Send `applicationId` and the run covers whatever the case holds that no run has read. Add `files` to drop more in first. If there is nothing new to read, the answer is 409 and says so.

## Red flags

If pre-flight flags a file, such as a scan too coarse to read or a duplicated page, Sheaf does **not** override that on your behalf. The answer is:

```json
{
  "error": "The file set has 1 red flag(s) — use \"bypassed\" (Process anyway) to override them",
  "applicationId": "Xjs0t8SWt_",
  "flags": [ { "fileId": "sf-3kQ9", "page": 1, "code": "low_dpi", "note": "p.1 embedded image ~96 DPI — below 150" } ]
}
```

with status `409`. The case **exists** with its files and waits at the gate for a person. Do not send the packet again. This is the one error that carries more than a message.

## Other refusals

| Status | When |
| --- | --- |
| 400 | No files, a missing `applicant` or `expectedDocList`, a file that is not a PDF. |
| 404 | Unknown workflow, version, list or case. |
| 409 | A run is already in flight on the case, or there is nothing new to read. |
| 502 | The analyzer could not be reached. The case is put back at the gate with its files, and `applicationId` is in the answer. |