## 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:

```json
{
  "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

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