## Create a workflow (desk:admin)

`POST /api/desk/v1/workflows`

Module: Desk · operationId: `createWorkflow` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `key` (string, required): Key of the workflow, unique in the tenant
- `name` (string, required): Name of the workflow
- `statuses` (array of Status, required): Statuses of the workflow
  - `key` (string, required): Key of the status, unique in the workflow
  - `label` (string, required): Display label
  - `phase` (Phase, required): (one of `new`, `active`, `waiting`, `done`)
  - `closed` (boolean): The item counts as closed in this status
  - `color` (string): Display color
  - `description` (string): Description of the status
  - `pausesSla` (boolean): SLA clocks pause in this status
- `archived` (boolean): Archived: the workflow is kept for existing data but no longer offered in pickers
- `description` (string): Description of the workflow
- `id` (string, read-only): Id of the workflow
- `scope` (string): Serves item types (item, default) or project types (project); fixed after creation (one of `item`, `project`)
- `transitions` (array of Transition): Empty = free workflow
  - `from` (array of string, required): Source statuses; "*" = any
  - `id` (string, required): Id of the transition
  - `to` (string, required): Target status
  - `allowedRoles` (array of string): Space roles allowed (at least one of them); empty: agent and above
  - `label` (string): Label of the action
  - `requireComment` (boolean): A comment is required
  - `requiredFields` (array of string): Fields that must be filled for the transition
- `version` (integer): Version of the workflow; send it back on change (409 version_conflict when it is outdated)
- `note` (string): Why the configuration changes (trimmed, at most 500 characters, line breaks allowed; empty = no note) (max length 500)

Example:

```json
{
  "description": "Änderungen mit Freigabe durch den Kunden",
  "key": "freigabe",
  "name": "Freigabe",
  "note": "Neuer Ablauf für Changes mit Kundenfreigabe",
  "scope": "item",
  "statuses": [
    {
      "color": "info",
      "key": "neu",
      "label": "Neu",
      "phase": "new"
    },
    {
      "color": "warning",
      "key": "wartet_freigabe",
      "label": "Wartet auf Freigabe",
      "pausesSla": true,
      "phase": "waiting"
    },
    {
      "color": "primary",
      "key": "umsetzung",
      "label": "In Umsetzung",
      "phase": "active"
    },
    {
      "closed": true,
      "color": "success",
      "key": "erledigt",
      "label": "Erledigt",
      "phase": "done"
    }
  ],
  "transitions": [
    {
      "from": [
        "neu"
      ],
      "id": "freigabe_anfordern",
      "label": "Freigabe anfordern",
      "to": "wartet_freigabe"
    },
    {
      "from": [
        "wartet_freigabe"
      ],
      "id": "freigegeben",
      "label": "Freigegeben",
      "requireComment": true,
      "to": "umsetzung"
    },
    {
      "from": [
        "umsetzung"
      ],
      "id": "abschliessen",
      "label": "Abschließen",
      "to": "erledigt"
    }
  ]
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)

Fields of the 201 answer:

- `key` (string, required): Key of the workflow, unique in the tenant
- `name` (string, required): Name of the workflow
- `statuses` (array of Status, required): Statuses of the workflow
  - `key` (string, required): Key of the status, unique in the workflow
  - `label` (string, required): Display label
  - `phase` (Phase, required): (one of `new`, `active`, `waiting`, `done`)
  - `closed` (boolean): The item counts as closed in this status
  - `color` (string): Display color
  - `description` (string): Description of the status
  - `pausesSla` (boolean): SLA clocks pause in this status
- `archived` (boolean): Archived: the workflow is kept for existing data but no longer offered in pickers
- `description` (string): Description of the workflow
- `id` (string, read-only): Id of the workflow
- `scope` (string): Serves item types (item, default) or project types (project); fixed after creation (one of `item`, `project`)
- `transitions` (array of Transition): Empty = free workflow
  - `from` (array of string, required): Source statuses; "*" = any
  - `id` (string, required): Id of the transition
  - `to` (string, required): Target status
  - `allowedRoles` (array of string): Space roles allowed (at least one of them); empty: agent and above
  - `label` (string): Label of the action
  - `requireComment` (boolean): A comment is required
  - `requiredFields` (array of string): Fields that must be filled for the transition
- `version` (integer): Version of the workflow; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "archived": false,
  "description": "Service-Desk-Ablauf mit Wartezuständen und Abschlussangaben",
  "id": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01",
  "key": "service",
  "name": "Service",
  "scope": "item",
  "statuses": [
    {
      "color": "info",
      "key": "neu",
      "label": "Neu",
      "phase": "new"
    },
    {
      "color": "info",
      "key": "in_bearbeitung",
      "label": "In Bearbeitung",
      "phase": "active"
    },
    {
      "color": "warning",
      "key": "wartet_kunde",
      "label": "Wartet auf Kunde",
      "pausesSla": true,
      "phase": "waiting"
    },
    {
      "color": "warning",
      "key": "wartet_dritte",
      "label": "Wartet auf Dritte",
      "pausesSla": true,
      "phase": "waiting"
    },
    {
      "closed": true,
      "color": "success",
      "key": "geloest",
      "label": "Gelöst",
      "phase": "done"
    },
    {
      "closed": true,
      "color": "neutral",
      "key": "geschlossen",
      "label": "Geschlossen",
      "phase": "done"
    }
  ],
  "transitions": [
    {
      "from": [
        "neu",
        "wartet_kunde",
        "wartet_dritte"
      ],
      "id": "bearbeiten",
      "label": "In Bearbeitung nehmen",
      "to": "in_bearbeitung"
    },
    {
      "from": [
        "geloest",
        "geschlossen"
      ],
      "id": "wieder_oeffnen",
      "label": "Wieder öffnen",
      "to": "in_bearbeitung"
    },
    {
      "from": [
        "neu",
        "in_bearbeitung",
        "wartet_dritte"
      ],
      "id": "warten_kunde",
      "label": "Auf Kunde warten",
      "to": "wartet_kunde"
    },
    {
      "from": [
        "neu",
        "in_bearbeitung",
        "wartet_kunde"
      ],
      "id": "warten_dritte",
      "label": "Auf Dritte warten",
      "to": "wartet_dritte"
    },
    {
      "from": [
        "neu",
        "in_bearbeitung",
        "wartet_kunde",
        "wartet_dritte"
      ],
      "id": "loesen",
      "label": "Lösen",
      "to": "geloest"
    },
    {
      "from": [
        "geloest"
      ],
      "id": "schliessen",
      "label": "Schließen",
      "to": "geschlossen"
    }
  ],
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/workflows' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Änderungen mit Freigabe durch den Kunden","key":"freigabe","name":"Freigabe","note":"Neuer Ablauf für Changes mit Kundenfreigabe","scope":"item","statuses":[{"color":"info","key":"neu","label":"Neu","phase":"new"},{"color":"warning","key":"wartet_freigabe","label":"Wartet auf Freigabe","pausesSla":true,"phase":"waiting"},{"color":"primary","key":"umsetzung","label":"In Umsetzung","phase":"active"},{"closed":true,"color":"success","key":"erledigt","label":"Erledigt","phase":"done"}],"transitions":[{"from":["neu"],"id":"freigabe_anfordern","label":"Freigabe anfordern","to":"wartet_freigabe"},{"from":["wartet_freigabe"],"id":"freigegeben","label":"Freigegeben","requireComment":true,"to":"umsetzung"},{"from":["umsetzung"],"id":"abschliessen","label":"Abschließen","to":"erledigt"}]}'
```
