ConnectCloud Developers

Create a flow (tenant:flows:write; tenant flows tenant:flows:admin; scoped flows tenant:flows:write and the owning module's manage)

POST /api/flows/v1/flows

Module: Flows · operationId: createFlow · Tag: Flows · Auth: access token (Authorization: Bearer <accessToken>)

A personal flow belongs to the caller and acts with the caller's permissions; a tenant flow acts as the service account it names and needs tenant:flows:admin. The draft starts from yaml, from a template (filled with params) or a skeleton with a manual trigger. A template made for a kind of scope (scope in GET /api/flows/v1/templates) needs a scope of that kind (400 invalid, field scope); a tenant-wide template may be created into any scope. An inline template is an immediate automation of its module and never a flow (400 invalid, field template). With scope the flow belongs to a desk space or forge project: owner must be tenant and serviceAccountId is required (400 invalid), and instead of tenant:flows:admin the module that owns the scope must let the caller manage it – 404 when the caller may not view the scope, 403 forbidden when they view but may not manage it, 503 scope_unavailable when the module cannot answer. The scope of a flow never changes; keys stay unique per tenant.

Request body

application/json (required)

  • name (string, required): Display name (max length 200)
  • owner (string, required): personal or tenant (one of personal, tenant)
  • key (string): Lower case letters, digits and dashes; default derived from the name
  • params (object): The values of the template's parameters by key (only with template: 400 invalid, field params). A parameter left out takes its default; a wrong one is 400 invalid with the field params.<key> – see renderFlowTemplate.
  • scope (string): What the flow belongs to: desk:space:<id> or forge:project:<id> (the id a lower-case UUID). Only with owner: tenant; the owning module decides who sees and manages the flow. (max length 160)
  • serviceAccountId (string (uuid)): Tenant flows: the service account the flow acts as
  • template (string): The key of a durable template from GET /api/flows/v1/templates: the draft starts from its definition, filled with the new flow's key and name and the values of params. Not together with yaml, an unknown key and an inline template: 400 invalid, field template. (max length 63)
  • yaml (string): The first draft

Example:

{
  "name": "Kritische Tickets melden",
  "owner": "personal",
  "params": {
    "priorities": [
      "hoch",
      "kritisch"
    ],
    "recipients": [
      "creator"
    ]
  },
  "template": "kritische-tickets-melden"
}

Responses

  • 201 Created (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)
  • 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 201 answer:

  • flow (Flow)
    • archived (boolean): Whether the flow is archived
    • canEdit (boolean): Whether the caller may change the draft and publish (a scoped flow: the owning module lets the caller manage the scope and the token holds tenant:flows:write or admin)
    • createdAt (string (date-time)): When the flow was created
    • createdBy (string): E-mail of the creator
    • description (string): Description from the definition
    • enabled (boolean): Whether the published version's triggers start runs
    • id (string (uuid)): Flow id
    • key (string): Unique per tenant; sub-flows call a flow by it
    • name (string): Display name
    • owner (string): personal (acts as its creator) or tenant (acts as its service account) (one of personal, tenant)
    • ownerEmail (string): Personal flows: the owner; tenant flows: who created it
    • pausedReason (string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)
    • publishedNumber (integer): The live version
    • scope (string): What the flow belongs to – desk:space:<id> or forge:project:<id>; absent for a tenant or personal flow. The owning module decides who sees and manages a scoped flow ("Scoped flows").
    • serviceAccountId (string (uuid)): Tenant flows: the account it acts as
    • updatedAt (string (date-time)): When the flow was changed last
    • updatedBy (string): E-mail of who changed the flow last
    • version (integer): Send it with changes
  • validation (Validation)
    • diagnostics (array of Diagnostic, required): Findings of the validator
      • code (string, required): Stable code, e.g. unknown_port, invalid_assignee, mail_option_not_allowed (a mail node sets mandatory or mailChannel in a personal or scoped flow)
      • message (string, required): Human-readable explanation
      • severity (string, required): Errors block publishing (one of error, warning)
      • col (integer): Column in the YAML (1-based)
      • line (integer): Line in the YAML (1-based)
      • nodeId (string): The node the finding is about
      • params (object): mail_option_not_allowed: option (mandatory or mailChannel)
      • path (string): Dotted path in the definition
    • permissions (array of array of string, required): The any-of permission groups of the actions and events the flow uses
    • valid (boolean, required): False when a finding has severity error
    • ports (object): The output ports of every node that parsed, by node id (the builder's handles)

Example 201 answer:

{
  "flow": {
    "archived": false,
    "canEdit": true,
    "createdAt": "2026-11-18T09:02:11Z",
    "createdBy": "sophie.huber@muster-it.example",
    "enabled": false,
    "id": "5e7a9c1b-3d5f-4a7b-8c9d-1e3f5a7b9c0d",
    "key": "kritische-tickets-melden",
    "name": "Kritische Tickets melden",
    "owner": "personal",
    "ownerEmail": "sophie.huber@muster-it.example",
    "updatedAt": "2026-11-18T09:02:11Z",
    "updatedBy": "sophie.huber@muster-it.example",
    "version": 1
  },
  "validation": {
    "diagnostics": [],
    "permissions": [
      [
        "desk:read",
        "desk:write",
        "desk:admin"
      ]
    ],
    "valid": true
  }
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Kritische Tickets melden","owner":"personal","params":{"priorities":["hoch","kritisch"],"recipients":["creator"]},"template":"kritische-tickets-melden"}'

View as Markdown · Interactive reference · OpenAPI