ConnectCloud Developers

List the flows the caller may see (tenant:flows:read|write|admin; with scope the owning module's view)

GET /api/flows/v1/flows

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

Without scope the flows that belong to no scope: tenant flows for every flows permission; personal flows of the caller (admins see every personal flow). Scoped flows are never in that list. With scope exactly the flows of that scope, for whoever its module lets view it (404 otherwise, 503 scope_unavailable when the module cannot answer); canEdit then tells whether the module lets the caller manage the scope.

Parameters

Name In Type Required Description
archived query boolean true lists the archived flows (default false)
scope query string List the flows of this scope instead: desk:space:<id> or forge:project:<id> (the id a lower-case UUID); anything else is 400 invalid, field scope (max length 160)

Responses

  • 200 Flows (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)
  • 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 200 answer:

  • items (array of Flow, required): The flows
    • 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
  • total (integer): Number of items

Example 200 answer:

{
  "items": [
    {
      "archived": false,
      "canEdit": true,
      "createdAt": "2026-10-21T09:20:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Bei jedem neuen Ticket mit hoher oder kritischer Priorität fasst die KI die Meldung zusammen und die Systemadministration bekommt eine Nachricht.",
      "enabled": true,
      "id": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
      "key": "kritische-tickets-zusammenfassen",
      "name": "Kritische Tickets zusammenfassen",
      "owner": "personal",
      "ownerEmail": "sophie.huber@muster-it.example",
      "publishedNumber": 2,
      "updatedAt": "2026-11-12T14:03:27Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 5
    },
    {
      "archived": false,
      "canEdit": false,
      "createdAt": "2026-09-15T16:40:00Z",
      "createdBy": "thomas.pfeiffer@muster-it.example",
      "enabled": false,
      "id": "8b0d2f4a-6c8e-4a1b-9d3f-5a7c9e1b3d5f",
      "key": "tickets-nachts-pruefen",
      "name": "Offene Tickets nachts prüfen",
      "owner": "tenant",
      "ownerEmail": "thomas.pfeiffer@muster-it.example",
      "pausedReason": "permission_lost",
      "publishedNumber": 1,
      "serviceAccountId": "1c3e5a7b-9d2f-4b4a-8c6e-0a2b4c6d8e1f",
      "updatedAt": "2026-11-03T07:12:55Z",
      "updatedBy": "thomas.pfeiffer@muster-it.example",
      "version": 3
    }
  ],
  "total": 2
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/flows/v1/flows' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI