Start a run of a flow by hand (tenant:flows:write for own personal flows, tenant:flows:admin for tenant flows, the owning module's manage for scoped flows)
POST /api/flows/v1/flows/{id}/runs
Module: Flows · operationId: startFlowRun · Tag: Runs · Auth: access token (Authorization: Bearer <accessToken>)
Runs the published version from a manual trigger (trigger, default the first one) with input as
trigger.data. The run acts with the flow owner's permissions (or the service account's), so who may change
the flow may start it – a scoped flow: who its module lets manage the scope (503 scope_unavailable when the
module cannot answer). An Idempotency-Key makes a repeated start the same run (created: false). A manual
trigger may carry a filter over trigger.data: a start it does not hold for is 422 not_applicable, one
whose filter cannot be evaluated for the input 422 filter_failed.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | (max length 200) | |
id |
path | string (uuid) | yes |
Request body
application/json
input(object): Start data of the run (trigger.data)trigger(string): The id of a manual trigger
Example:
{
"input": {
"amount": 120
},
"trigger": "von_hand"
}
Responses
- 202 Started (or, with a known Idempotency-Key, the existing run) (
application/json) - 400 Invalid input (
invalid);fieldnames the first invalid field,details.fieldsevery one. (application/json) - 401 Missing, invalid or expired token (no body).
- 403 The token lacks the permission or has no active tenant (
forbidden). Also:person_required(a service-account key on personal flows or the task inbox),live_test_forbidden,forbidden_grant,starter_excluded. (application/json) - 404 The record does not exist in the token's tenant – or it belongs to a scope the caller may not view (a scoped flow stays hidden). (
application/json) - 409 The state does not allow it: version_conflict (reload), no_changes, archived, key_taken, flow_disabled, flow_tripped, task_closed, run_finished. (
application/json) - 422 invalid_definition (details.diagnostics), permission_missing (details.groups), owner_inactive, owner_not_found, not_published, key_changed, not_webhook, filter_failed, unknown_trigger, no_manual_trigger. (
application/json) - 503 A dependency is not available:
scope_unavailable(the module that owns a flow's scope did not answer who may see and manage it – nothing of a scoped flow is shown or changed),identity_unavailable(HR),ai_unavailable,ai_failed. (application/json)
Fields of the 202 answer:
created(boolean, required): False when an Idempotency-Key returned an existing runrunId(string (uuid), required): The run
Example 202 answer:
{
"created": true,
"runId": "6c8e0a2b-4d6f-4a8c-9e1b-3d5f7a9c1e3b"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/runs' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"input":{"amount":120},"trigger":"von_hand"}'