ConnectCloud Developers

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 body
  • live (boolean): Send the writes for real (needs tenant:flows:admin) (default false)
  • 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); field names the first invalid field, details.fields every 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"}'

View as Markdown · Interactive reference · OpenAPI