Run the draft as a test – dry by default, live with tenant:flows:admin (tenant:flows:write for own flows; scoped flows the owning module's manage)
POST /api/flows/v1/flows/{id}/test-runs
Module: Flows · operationId: testFlowDraft · Tag: Runs · Auth: access token (Authorization: Bearer <accessToken>)
Who may change the flow may test it (a scoped flow: who its module lets manage the scope; a live test still
needs tenant:flows:admin). The draft must be valid (422 invalid_definition); HR confirms its permissions like a publish
(422 permission_missing; a token with a subset of the permissions must hold them itself, 403 forbidden_grant). The run is pinned to a snapshot of the draft and marked with testMode. A dry
test (default) simulates every write node (its output is a sample of the operation's answer, its input says
dryRun), resolves but sends no mail and asks only the tester in human tasks; reads and AI nodes run for real.
A live test (live: true, 403 live_test_forbidden without tenant:flows:admin) acts like a run. The flow
need not be published or enabled; dry tests are not billed. Sub-flows run in the same mode.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
input(object): trigger.data: an input, or a sample event or webhook bodylive(boolean): Send the writes for real (needs tenant:flows:admin) (defaultfalse)trigger(string): The trigger the test acts as (any kind); default the first manual one
Example:
{
"input": {
"itemId": "4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e",
"number": "SUP-214",
"priority": "hoch",
"title": "WLAN im Restaurant fällt aus"
},
"live": false,
"trigger": "neues_ticket"
}
Responses
- 202 Started (
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:
runId(string (uuid), required): The test run
Example 202 answer:
{
"runId": "2d4f6a8c-0e1b-4d3f-9a5c-7e9b1d3f5a7c"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/test-runs' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"input":{"itemId":"4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e","number":"SUP-214","priority":"hoch","title":"WLAN im Restaurant fällt aus"},"live":false,"trigger":"neues_ticket"}'