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);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) - 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 flowsarchived(boolean): Whether the flow is archivedcanEdit(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 createdcreatedBy(string): E-mail of the creatordescription(string): Description from the definitionenabled(boolean): Whether the published version's triggers start runsid(string (uuid)): Flow idkey(string): Unique per tenant; sub-flows call a flow by itname(string): Display nameowner(string):personal(acts as its creator) ortenant(acts as its service account) (one ofpersonal,tenant)ownerEmail(string): Personal flows: the owner; tenant flows: who created itpausedReason(string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)publishedNumber(integer): The live versionscope(string): What the flow belongs to –desk:space:<id>orforge: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 asupdatedAt(string (date-time)): When the flow was changed lastupdatedBy(string): E-mail of who changed the flow lastversion(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"