ConnectCloud Developers

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); 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:

  • created (boolean, required): False when an Idempotency-Key returned an existing run
  • runId (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"}'

View as Markdown · Interactive reference · OpenAPI