Start a run

POST/apps/{appId}/runs

Authenticate with an operator token or an app API key or a signed-in Foliot Console session.

With an idempotencyKey, a repeat returns the EXISTING run and created: false with a 200 rather than a 201 — so retrying a start is safe. Omitting version resolves to the highest registered version at this instant.

Path parameters

appId

string

REQUIRED

The app's name.

Request body

businessKey

string

OPTIONAL

Your own identifier, for signalling later without tracking run ids.

max length 200

idempotencyKey

string

OPTIONAL

max length 200

input

any

OPTIONAL

startAfter

Duration

OPTIONAL

Responses

200 object A run with this idempotency key already existed; it is returned unchanged.

201 object Created

400 Error Invalid request.

401 Error Missing, malformed or unknown bearer token.

403 Error The token is valid but not permitted on this route.

404 Error No such resource.

503 Error A dependency this route needs is unreachable.

curl -X POST "https://api.foliot.app/apps/{appId}/runs" \ -H "Authorization: Bearer $FOLIOT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"businessKey":"string","idempotencyKey":"string","input":null,"startAfter":"string","tags":["string"],"version":1,"workflow":"string"}'

{ "created": true, "run": { "appId": "string", "attempt": 1, "businessKey": null, "compacted": true, "createdAt": "2026-10-01T09:30:00Z", "currentStep": null, "error": { "message": "string" }, "finishedAt": null, "generation": 1, "id": "3f2b8c1e-5a44-4c7a-9d0e-1b6f2a7c9e10", "idempotencyKey": null, "input": null, "scheduledAt": null, "state": {}, "status": "running", "tags": [ "string" ], "updatedAt": "2026-10-01T09:30:00Z", "waitReason": null, "waitSignal": null, "workflowName": "string", "workflowVersion": 1 } }