## The templates a new flow or immediate automation can start from (tenant:flows:read|write|admin)

`GET /api/flows/v1/templates`

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

Ready-made automations in display order (category, then registry order). Without parameters the list holds
the tenant-wide flows: pass a template's `key` as `template` (and the values of its `params`) to
`POST /api/flows/v1/flows`. `profile` and `scope` pick another list – what the settings of a forge project or
a desk space offer: `scope` is the *kind* of scope a template is made for (never one scope), `profile=inline`
the immediate automations of the module that owns that kind. An inline template never becomes a flow: render
it (`POST /api/flows/v1/templates/{key}/render`) and create the automation in its module. `available` is false
while a module the template uses is not offered by the catalogue (for an inline template: while its module
does not declare the template's actions as immediate); creating it would give a draft with validation errors.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `profile` | query | string |  | Where the templates run: `durable` (flows, the default) or `inline` (immediate automations of a module); anything else is `400 invalid`, field `profile` (one of `durable`, `inline`; default `"durable"`) |
| `scope` | query | string |  | The kind of scope the templates are made for: `desk:space` or `forge:project`; without it the tenant-wide templates. Anything else – also one scope with its id – is `400 invalid`, field `scope` (one of `desk:space`, `forge:project`) |

### Responses

- **200** The templates (`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`)

Fields of the 200 answer:

- `items` (array of FlowTemplate, required): The templates
  - `available` (boolean, required): False while a module the template uses is not offered by the catalogue
  - `category` (string, required): Category the template is listed under (one of `support`, `sales`, `people`, `operations`, `development`, `general`)
  - `description` (LocalizedText, required)
    - `de` (string, required): German text
    - `en` (string, required): English text
  - `key` (string, required): Template key; pass it as `template` to createFlow
  - `modules` (array of string, required): The modules whose actions and events the template uses
  - `name` (LocalizedText, required)
    - `de` (string, required): German text
    - `en` (string, required): English text
  - `params` (array of FlowTemplateParam, required): What the person fills in before creating it, in display order (empty: nothing)
    - `key` (string, required): Key of the value in `params`
    - `label` (LocalizedText, required)
    - `required` (boolean, required): The value must not be empty. Left out, a required parameter takes its `default`; one without a `default` must be sent. Every parameter is required or has a `default`.
    - `type` (string, required): The input and the JSON type of the value: `text` (string, at most 4000 characters), `number`, `bool`, `enum` (one `options[].value`), `email` (one address), `people` (always a list: `person:<email>`, `employee:<id>`, `group:<id>`, `role:<id>`, `manager:<email or id>` – the people references of a mail node with HR ids –, a plain address, or `creator` – the person creating it). The pickers hand over a key or name of the tenant's configuration as a string of at most 200 characters: `desk_space` (space key), `desk_priority` (priority key), `desk_type` (type key), `desk_team` (team key), `desk_status` (status key of a ticket workflow), `desk_label` (label name), `forge_project` (project key), `forge_label` (label name), `forge_type` (item type key), `forge_status` (status key). `duration` is a time span as a string: a whole number of hours or days, `4h` or `2d` (pattern `^[1-9][0-9]{0,3}[hd]$`, at most 360 days; a day is 24 hours) – nothing else is accepted, and it is always required. (one of `text`, `number`, `bool`, `enum`, `email`, `people`, `desk_space`, `desk_priority`, `desk_type`, `desk_team`, `desk_status`, `desk_label`, `forge_project`, `forge_label`, `forge_type`, `forge_status`, `duration`)
    - `default` (any): The value used when none is sent, of the parameter's type (a list for `multiple` and `people`)
    - `help` (object): What to enter (absent when the label says it)
    - `multiple` (boolean): The value is a list of values of the type, at most 50 (enum and the pickers; `people` always is a list)
    - `options` (array of object): The choices of an `enum`
      - `label` (LocalizedText, required)
      - `value` (string, required): The value to send
  - `profile` (string, required): `durable`: a flow, created with `POST /api/flows/v1/flows`. `inline`: an immediate automation of the module in `modules` – rendered here, created there. (one of `durable`, `inline`)
  - `triggers` (array of string, required): The kinds of the template's triggers
  - `hint` (object): What to adjust after creating the flow that no parameter covers (absent: nothing)
  - `scope` (string): The kind of scope the template is made for (absent: tenant-wide) (one of `desk:space`, `forge:project`)
- `total` (integer, required): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "available": true,
      "category": "support",
      "description": {
        "de": "Bei jedem neuen Ticket mit einer der gewählten Prioritäten fasst die KI die Meldung zusammen und Sie bekommen eine Mail.",
        "en": "For every new ticket with one of the chosen priorities the AI summarises it and you get an email."
      },
      "key": "kritische-tickets-melden",
      "modules": [
        "desk"
      ],
      "name": {
        "de": "Kritische Tickets melden",
        "en": "Report critical tickets"
      },
      "params": [
        {
          "default": [
            "hoch",
            "kritisch"
          ],
          "key": "priorities",
          "label": {
            "de": "Prioritäten",
            "en": "Priorities"
          },
          "multiple": true,
          "required": false,
          "type": "desk_priority"
        },
        {
          "default": [
            "creator"
          ],
          "key": "recipients",
          "label": {
            "de": "Empfänger",
            "en": "Recipients"
          },
          "multiple": true,
          "required": true,
          "type": "people"
        }
      ],
      "profile": "durable",
      "triggers": [
        "event"
      ]
    }
  ],
  "total": 1
}
```

### Example request

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