# ConnectCloud Desk API (v1.0.0)

Tickets, issues and tasks with configurable spaces, types, workflows and fields; comments, mail, attachments, SLAs, automation rules, projects and their payment plans.

Base URLs:

- Production: `https://api.mbcom.cloud/api/desk/v1`
- Staging: `https://api.mbcom.cloud/api/desk/v1`
- Sandbox: `https://developers.mbcom.cloud/sandbox/desk`

The desk is one configurable work item system for the service desk (incidents, requests,
problems, changes, security incidents) and for internal and project work (phases, tasks, labels,
boards); software development is forge's (ADR 0027). What makes an item a ticket or an issue is configuration only: its **space**
and its **type**; every type follows a **workflow** whose statuses belong to one of four fixed
phases (`new`, `active`, `waiting`, `done`). Items can be moved between spaces and types at any
time; the item number never changes and no data is lost.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `desk:read` | read access to tenant-visible spaces (role *viewer*) |
| `desk:write` | work on items in tenant-visible spaces (role *agent*) |
| `desk:admin` | configuration (workflows, types, fields, …); *maintainer* in every space |
| `desk:confidential` | see confidential items (security incidents) |
| `hr:work:billing` | the payment plans of projects (HR's billing permission, ADR 0040) |

Spaces with visibility `members` are only visible to their members; member roles are
`viewer` < `reporter` (create and comment) < `agent` (edit, transition) < `maintainer`
(space settings, labels). Confidential items are additionally visible to their
creator and assignees.

## Conventions
- Item references in paths accept the id (UUID) or the number (`1234`, URL-encoded `%231234`).
- Updates use optimistic locking: send the `version` you read; a stale version returns `409`.
- `POST /items` honours the `Idempotency-Key` header (7 days) and the `dedupeKey` field;
  repeated requests return the existing item with `200`.
- Lists are paginated with `limit` (max. 500) and the opaque `cursor`; `updatedSince` returns
  changes since a point in time (delta sync).
- Errors have the shape `{error, code, field?, missingFields?}`.
- Rate limits: 20 requests per second per signed-in principal and route (per client IP for failed authentications) with bursts up to 100 (`429` when
  exceeded); bulk requests accept up to 200 items.

## Events
Changes are published through the transactional outbox:
`desk.item.created|updated|transitioned|moved|merged|merged_in|split|handed_off|handoff_received|handed_back|handback_received|converted|converted_from|linked|unlinked|checklist|commented|rated|entry_*`
and `desk.ticket.rated` (a requester rated a closed ticket in the customer portal;
`data`: `customerNo`, `tenantName`, `itemId`, `number`, `addressId` – the ticket's customer, a masterdata address id, empty
without one –, `rating` 1–5, `comment`, `requesterName`, `requesterEmail`, `ratedAt` RFC 3339; not the item fields below).

Every `desk.item.*` event carries this `data` (personal subscriptions in comms and their event texts use it):

| Field | Type | Notes |
|---|---|---|
| `itemId`, `spaceId`, `typeId` | string | ids |
| `number` | integer | item number |
| `status` | string | status key after the change |
| `actor` | string | user ref of the acting user |
| `changes` | `[{field, from, to}]` | changed fields of this event (empty list when none) |
| `title` | string | item title |
| `priority` | string | priority key; omitted when unset |
| `confidential` | boolean | confidential item (security incidents) |
| `createdBy` | string | user ref of the creator |
| `assignees` | string[] | user refs with role `assignee` (the `owner` is not included) |
| `watchers` | string[] | user refs with role `watcher` |
| `customerName` | string | name snapshot of the customer; omitted when unset |
| `spaceName`, `typeName` | string | current names from the tenant configuration; omitted when unknown |
| `dueAt` | string (RFC 3339, UTC) | omitted when unset |

List fields are always arrays, never `null`. Description and custom field values are never
part of an event; load the item for them. Fields may be added; consumers ignore unknown ones.

## Deprecation policy
Breaking changes get a new version prefix (`/api/desk/v2`); `v1` stays available for at least
six months after `v2` and deprecated fields are announced in the changelog first.

# Configuration

## Complete configuration visible to the caller (desk:read)

`GET /api/desk/v1/bootstrap`

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

Seeds the default configuration on first use. Supports `If-None-Match` with the returned weak ETag.

### Responses

- **200** Configuration (`application/json`)
- **304** Not modified
- **401** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `calendars` (array of ServiceCalendar): Service calendars
  - `key` (string, required): Key of the calendar, unique in the tenant
  - `name` (string, required): Name of the calendar
  - `archived` (boolean): Archived: the calendar is kept for existing data but no longer offered in pickers
  - `description` (string): Description of the calendar
  - `exceptions` (array of object): Days that differ from the week (holidays, special hours)
    - `closed` (boolean): Closed all day
    - `date` (string (date)): Day
    - `hours` (array of HourSpan): Service hours of the day (when not closed)
    - `note` (string): Note (e.g. the holiday)
  - `holidayRegion` (string): Empty = the tenant's federal state (HR), none, or a federal state code
  - `id` (string, read-only): Id of the calendar
  - `isDefault` (boolean): Calendar of policies that name none
  - `onCall` (object): On-call windows by weekday key
  - `timeZone` (string): IANA zone, default Europe/Berlin
  - `version` (integer): Version of the calendar; send it back on change (409 version_conflict when it is outdated)
  - `weekly` (object): Opening hours by weekday key (mon … sun)
- `categories` (array of Category): Categories
  - `name` (string, required): Name of the category
  - `archived` (boolean): Archived: the category is kept for existing data but no longer offered in pickers
  - `id` (string): Id of the category
  - `parentId` (string): Parent category (empty: top level)
  - `sortOrder` (integer): Position in lists (ascending)
- `enums` (object): Tenant value lists by kind (linkType, source, assigneeRole, callbackStatus, callbackReason)
- `fields` (array of FieldDef): Custom field definitions
  - `key` (string, required): Key of the field; item values are cf.<key>
  - `kind` (string, required): Value kind of the field (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
  - `label` (string, required): Display label
  - `aiFill` (boolean): The AI may fill the field of new tickets (triage); only select and short text (`text`) fields. Text is only ever proposed, never applied without a person
  - `archived` (boolean): Archived: kept on items, no longer offered
  - `description` (string): Help text of the field
  - `id` (string, read-only): Id of the custom field
  - `kbRole` (string): Field holds the cause (one of ``, `cause`, `solution`, `workaround`)
  - `options` (array of object): Choices of a select or multiselect field
    - `color` (string): Display color of the choice
    - `label` (string): Display label of the choice
    - `value` (string): Stored value of the choice
- `forgeEnabled` (boolean): Tickets can be handed over or converted to forge (FORGE_INTERNAL_URL set); without it forge targets are hidden and answer 503 forge_unavailable
- `labels` (array of Label): Labels
  - `name` (string, required): Name of the label
  - `archived` (boolean): Archived: the label is kept for existing data but no longer offered in pickers
  - `color` (string): Display color of the label
  - `description` (string): Description of the label
  - `id` (string): Id of the label
  - `spaceId` (string): Space of the label (empty: tenant-wide)
- `portalUrl` (string): Address of the tenant's customer portal while it is on (links to help articles: <portalUrl>/help/<space>/<path>)
- `priorities` (array of Priority): Priorities
  - `key` (string, required): Key of the priority, unique in the tenant
  - `label` (string, required): Display label of the priority
  - `archived` (boolean): Archived: the priority is kept for existing data but no longer offered in pickers
  - `color` (string): Display color of the priority
  - `id` (string): Id of the priority
  - `isDefault` (boolean): Priority of new items without one
  - `rank` (integer): Sort order of the priorities (ascending)
- `projectTemplates` (array of ProjectTemplate): Project templates
  - `key` (string, required): Key of the template, unique in the tenant
  - `name` (string, required): Name of the template (max length 200)
  - `typeId` (string, required): Project type (id or key on input); fixed
  - `archived` (boolean): Archived: the template is kept for existing data but no longer offered in pickers
  - `blueprint` (object): What a project made from the template gets
    - `dependencies` (array of object): Finish-to-start between tasks (keys); no cycles
      - `from` (string, required): Key of the task that has to end first
      - `to` (string, required): Key of the task that starts after it
      - `lagDays` (integer): Days between the end of from and the start of to (max 365)
    - `fields` (object): Custom field values of new projects
    - `milestones` (array of object): Milestones of the new project
      - `key` (string, required): Key of the milestone in the template
      - `title` (string, required): Title of the milestone
      - `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
      - `offsetDays` (integer): Due this many days after the project start (max 3650)
    - `payments` (array of object): The payment plan of new projects (one final payment)
      - `amount` (number, required): Net amount or percentage (amountKind)
      - `role` (string, required): interim payment or the final payment (one of `interim`, `final`)
      - `title` (string, required): Title of the payment
      - `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
      - `milestoneKey` (string): A milestone of the template that makes it due
      - `taxRate` (number): VAT rate in percent
    - `tasks` (array of BlueprintTask): Tasks: items of the new project
  - `description` (string): Description of the template
  - `id` (string, read-only): Id of the template
  - `version` (integer): Version of the template; send it back on change (409 version_conflict when it is outdated)
- `projectTypes` (array of ProjectType): Project types
  - `key` (string, required): Lower-case letters, digits, - or _; fixed
  - `name` (string, required): Name of the project type (max length 200)
  - `workflowId` (string, required): A workflow of scope project
  - `archived` (boolean): Archived: the project type is kept for existing data but no longer offered in pickers
  - `color` (string): Display color of the project type
  - `description` (string): Description of the project type
  - `icon` (string): Icon of the project type
  - `id` (string, read-only): Id of the project type
  - `layout` (array of LayoutField): Custom fields ("cf.<key>") of the project record; sections facts, main, aside
    - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
    - `required` (boolean): The field must be filled
    - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
  - `settings` (object): Settings of the project type
    - `billing` (object): Project billing
      - `autoDraft` (boolean): Request a payment (hand its draft to trade) as soon as it is due; default off
      - `hourUnit` (string): No longer used: hourly billing is HR's (ADR 0040); ignored on write and no longer returned (max length 20)
      - `taxRate` (number): VAT rate of new payments (default 19) (max 100)
      - `unit` (string): Unit of the payment invoice lines (default Pauschal) (max length 20)
    - `taskSpaceId` (string): Space template tasks are created in (id or key on input)
    - `taskTypeId` (string): Item type of template tasks that name none (id or key on input)
  - `sortOrder` (integer): Position in lists (ascending)
  - `version` (integer): Version of the project type; send it back on change (409 version_conflict when it is outdated)
- `revision` (integer): Revision of the configuration; changes with every configuration change
- `settings` (Settings)
  - `ai` (object): AI features of the desk (triage, subject, summary, draftReply). Triage with `autoApply` applies each proposed value that reaches `threshold` and leaves the rest pending; text fields read from the ticket are always suggestions. Draft replies never apply or run automatically; meeting summaries are never applied automatically. An applied summary fills the ticket's summary field (undo restores the previous one); with `autoApply` it fills it on its own unless a person wrote the summary (the suggestion then waits).
    - `features` (object): Settings per feature key (enabled, auto, autoApply, threshold)
  - `callbacks` (object): Callback settings: the custom fields of the form (in order), the rules for the note and the mails to customers. `mailTexts` and `statusMail`: absent = the defaults (a manual mail text for the status `not_reached`, while that status exists), `[]` = none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the mode `auto`.
    - `fields` (array of object): Custom fields of the callback form in order
      - `key` (string, required): Key of a custom field (without cf.)
      - `required` (boolean): The field must be filled
    - `mailTexts` (array of object): Mail texts for customers. Placeholders: {{name}}, {{nummer}}, {{telefon}}, {{kunde}}, {{grund}}, {{gewuenscht}}, {{status}}, {{mitarbeiter}}; unknown ones are refused.
      - `body` (string, required): Text (placeholders allowed) (max length 8000)
      - `key` (string, required): Lower-case letters, digits, - and _; unique
      - `name` (string, required): Name of the mail text (max length 120)
      - `subject` (string, required): Subject (placeholders allowed) (max length 200)
    - `note` (object): Rules for the note of a callback (on create and when it changes); checked in the order required, minLength, pattern, aiCheck. Existing notes are not checked again.
      - `aiCheck` (boolean): The AI judges whether the note gives an understandable reason (422 `note_rejected` with a hint); an unavailable AI accepts the note
      - `minLength` (integer): Minimum characters of a non-empty note; 0 = off (max 2000)
      - `pattern` (string): Go (RE2) regular expression the note must contain a match of; anchor with ^ and $ for a full match (max length 500)
      - `patternMessage` (string): Shown instead of the pattern; required with a pattern (max length 200)
      - `required` (boolean): The note must not be empty
    - `statusMail` (array of object): Ties a mail text to a callbackStatus; a status without an entry sends nothing. Archived statuses may stay (they just stop firing).
      - `mode` (string, required): manual: the person decides when the status is set; auto: the mail is sent with the move into the status (one of `manual`, `auto`)
      - `status` (string, required): Key of a callbackStatus entry, once
      - `text` (string, required): Key of a mail text
  - `mail` (object): Mail rules of the tenant; empty fields use the defaults.
    - `aiClassify` (boolean): The AI decides about unclear mail at or above aiThreshold
    - `aiThreshold` (number): Confidence the AI needs to decide about unclear mail (max 1)
    - `aiTrim` (boolean): The AI finds the main text of a long received mail (over 1500 characters) the rules could not trim (default false)
    - `blockedExtensions` (array of string): Default: executables and scripts
    - `bulkPolicy` (string): Newsletters and bulk mail: drop (default) or make a ticket (one of `drop`, `ticket`)
    - `foreignSubjectMatch` (boolean): A [#N] subject token appends mail of senders who are no participant
    - `fromName` (string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one of `agentWithMailbox`, `agent`, `mailbox`)
    - `maxAttachmentBytes` (integer): Per file, default 20 MB, max. 40 MB
    - `maxTotalBytes` (integer): Per mail, default 35 MB, max. 40 MB
    - `perSender10min` (integer): Above: appended quietly (default 10)
    - `perSenderHour` (integer): Above: held in the mail log (default 30)
  - `priorityMatrix` (object): Priority from impact and urgency
    - `cells` (object): "<impact>|<urgency>" → priority key
    - `impacts` (array of object): Impact levels
      - `key` (string): Key of the level
      - `label` (string): Label of the level
    - `urgencies` (array of object): Urgency levels
      - `key` (string): Key of the level
      - `label` (string): Label of the level
  - `time` (object): No longer used: rules for time entries and hourly billing (self approval, hour unit, tax rate, traffic light) are HR's work settings (ADR 0040); ignored on write and no longer returned
- `setup` (object): needed is true until the tenant applied a template (the UI forces the picker)
  - `applied` (array of object): Templates applied so far
    - `appliedAt` (string (date-time)): When it was applied
    - `appliedBy` (string): Login (e-mail) of who applied it
    - `id` (string): Id of the application
    - `name` (string): Name of the applied template
    - `prefix` (string): Key prefix used for keys that already existed
    - `template` (string): Key of the applied template
  - `needed` (boolean): The tenant has not applied a configuration template yet
- `spaces` (array of Space): Spaces the caller sees
  - `key` (string, required): 2–10 upper-case letters or digits
  - `name` (string, required): Name of the space
  - `archived` (boolean): Archived: the space is kept for existing data but no longer offered in pickers
  - `color` (string): Display color of the space
  - `defaultTypeId` (string): Type of new items without one
  - `description` (string): Description of the space
  - `icon` (string): Icon of the space
  - `id` (string, read-only): Id of the space
  - `members` (array of object): Members and their space roles
    - `role` (string): Space role (one of `viewer`, `reporter`, `agent`, `maintainer`)
    - `userRef` (string): Login (e-mail) of the member
  - `settings` (object): Space settings; `mail` (reply mailbox, reopen policies) and `handoff` (what happens when a handoff comes back; ADR 0027). A space whose types all have the work focus is work-only: mail sources, routes, AI routing, portal forms and platform feedback cannot target it (400 `invalid`; leaving only work types in a space that mail or a portal form still delivers into is refused with field `typeIds`). Code settings are forge's (a sent `scm` is dropped).
    - `dueOnReceipt` (object): Due date on receipt: a new ticket of this space without `dueAt` gets one after the offset of its channel (`dueHasTime` true); work-focus types never. The channel comes from the ticket's `source`: `email` → mail; `portal`, `form`, `platform` → portal; `phone`, `nfon` → phone; `api` → api; `manual`, none, `teamviewer`, `teams` → manual; other sources (automation, handoff, …) get none. API clients send `source: api`, otherwise their tickets count as manual. `businessHours` counts the offset in the tenant's default service calendar (wall-clock time when it cannot be used) and takes no day unit. A channel left out sets nothing; `null` removes the setting. Invalid values are 400 with field `settings.dueOnReceipt.<channel>[.in]`.
      - `api` (DueOffset)
      - `mail` (DueOffset)
      - `manual` (DueOffset)
      - `phone` (DueOffset)
      - `portal` (DueOffset)
    - `handoff` (object): Hand back (design §3). `receiverOnReturn`: a ticket of this space that is handed back closes (`close`, default: `status` – a done status of the space's workflows – when its workflow has it, else its closed status) or stays (`keep`). `originOnReturn`: a ticket of this space whose handoff comes back does nothing (`none`, default) or moves to `status` / the first status of `stage` (new, active, waiting) unless it is in that phase already. Moves ignore transitions and required fields. Invalid values are 400 with field `settings.handoff…`.
      - `originOnReturn` (object): What happens to a ticket of this space when its handoff comes back
        - `action` (string): none (default) or move it to a status (one of `none`, `status`)
        - `stage` (string): Stage whose first status it moves to (status) (one of `new`, `active`, `waiting`)
        - `status` (string): Status it moves to (status)
      - `receiverOnReturn` (object): What happens to a ticket of this space that is handed back
        - `action` (string): close (default) or keep it open (one of `close`, `keep`)
        - `status` (string): Status to close with (close)
    - `projectTypeIds` (array of string): The project types the projects of this space may have (ids; keys are accepted on input), like the space lists its ticket types. Without it every project type is allowed. A project whose type the space does not list is refused with 422 field `typeId`; a project that keeps its type and space is not asked again. An unknown project type is 400 with field `settings.projectTypeIds`. Bundles do not carry it.
  - `typeIds` (array of string): Allowed types; empty = all
  - `version` (integer): Version of the space; send it back on change (409 version_conflict when it is outdated)
  - `visibility` (string): tenant: everyone with desk access sees it; members: only its members (one of `tenant`, `members`)
- `teams` (array of Team): Teams
  - `key` (string, required): Key of the team, unique in the tenant
  - `name` (string, required): Name of the team
  - `archived` (boolean): Archived: the team is kept for existing data but no longer offered in pickers
  - `description` (string): Description of the team
  - `id` (string): Id of the team
  - `members` (array of object): Members of the team
    - `role` (string): member or lead (one of `member`, `lead`)
    - `userRef` (string): Login (e-mail) of the member
- `types` (array of ItemType): Item types
  - `key` (string, required): Key of the type, unique in the tenant
  - `name` (string, required): Name of the item type
  - `workflowId` (string, required): Workflow of the type
  - `archived` (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
  - `closeRequired` (array of string): Fields that must be filled before the item can be closed
  - `color` (string): Display color of the item type
  - `confidential` (boolean): Items of the type are confidential
  - `description` (string): Description of the item type
  - `focus` (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, `conversation`, `work`)
  - `icon` (string): Icon of the item type
  - `id` (string, read-only): Id of the item type
  - `layout` (array of LayoutField): Custom fields of the record and their sections
    - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
    - `required` (boolean): The field must be filled
    - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
  - `level` (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
  - `sortOrder` (integer): Position in lists (ascending)
  - `version` (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)
- `workflows` (array of Workflow): Workflows
  - `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)
    - `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 200 answer:

```json
{
  "calendars": [
    {
      "id": "2e9f0a1b-3c4d-4e5f-8a7b-9c0d1e2f3a01",
      "isDefault": true,
      "key": "geschaeftszeiten",
      "name": "Geschäftszeiten",
      "timeZone": "Europe/Berlin",
      "version": 2,
      "weekly": {
        "mon": [
          {
            "from": "08:00",
            "to": "17:00"
          }
        ]
      }
    }
  ],
  "categories": [
    {
      "id": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01",
      "name": "Netzwerk",
      "sortOrder": 2
    },
    {
      "id": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
      "name": "WLAN",
      "parentId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01",
      "sortOrder": 2
    }
  ],
  "enums": {
    "assigneeRole": [
      {
        "flags": [
          "primary"
        ],
        "key": "owner",
        "label": "Verantwortlich",
        "system": true
      },
      {
        "flags": [
          "default"
        ],
        "key": "assignee",
        "label": "Bearbeitung",
        "system": true
      },
      {
        "flags": [
          "observer"
        ],
        "key": "watcher",
        "label": "Beobachtung",
        "system": true
      }
    ]
  },
  "fields": [
    {
      "aiFill": true,
      "id": "7f4a5b6c-8d9e-4f0a-9b2c-4d5e6f7a8b01",
      "key": "betroffenes_system",
      "kind": "text",
      "label": "Betroffenes System"
    }
  ],
  "forgeEnabled": true,
  "labels": [
    {
      "color": "warning",
      "description": "Einsatz beim Kunden nötig",
      "id": "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
      "name": "vor-ort"
    }
  ],
  "portalUrl": "https://muster-it.connectcloud.example",
  "priorities": [
    {
      "color": "info",
      "id": "8a5b6c7d-9e0f-4a1b-8c3d-5e6f7a8b9c02",
      "isDefault": true,
      "key": "normal",
      "label": "Normal",
      "rank": 2
    },
    {
      "color": "warning",
      "id": "8a5b6c7d-9e0f-4a1b-8c3d-5e6f7a8b9c03",
      "key": "hoch",
      "label": "Hoch",
      "rank": 3
    }
  ],
  "projectTemplates": [],
  "projectTypes": [],
  "revision": 184,
  "settings": {
    "priorityMatrix": {
      "cells": {
        "hoch|hoch": "kritisch",
        "mittel|hoch": "hoch"
      },
      "impacts": [
        {
          "key": "gering",
          "label": "Gering"
        },
        {
          "key": "mittel",
          "label": "Mittel"
        },
        {
          "key": "hoch",
          "label": "Hoch"
        }
      ],
      "urgencies": [
        {
          "key": "niedrig",
          "label": "Niedrig"
        },
        {
          "key": "mittel",
          "label": "Mittel"
        },
        {
          "key": "hoch",
          "label": "Hoch"
        }
      ]
    }
  },
  "setup": {
    "applied": [
      {
        "appliedAt": "2026-09-01T07:00:00Z",
        "appliedBy": "elias.gruber@muster-it.example",
        "id": "0f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
        "name": "Service Desk",
        "prefix": "",
        "template": "service-desk"
      }
    ],
    "needed": false
  },
  "spaces": [
    {
      "color": "info",
      "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "icon": "i-lucide-headset",
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "key": "SUP",
      "name": "Support",
      "typeIds": [
        "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
      ],
      "version": 4,
      "visibility": "tenant"
    }
  ],
  "teams": [
    {
      "id": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f01",
      "key": "first-level",
      "members": [
        {
          "role": "member",
          "userRef": "sophie.huber@muster-it.example"
        }
      ],
      "name": "Service Desk"
    }
  ],
  "types": [
    {
      "closeRequired": [
        "cf.ursache",
        "cf.loesung",
        "cf.abschlussgrund"
      ],
      "color": "error",
      "focus": "conversation",
      "icon": "i-lucide-flame",
      "id": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "key": "stoerung",
      "level": 1,
      "name": "Störung",
      "sortOrder": 1,
      "version": 2,
      "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
    }
  ],
  "workflows": [
    {
      "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"
        },
        {
          "closed": true,
          "color": "success",
          "key": "geloest",
          "label": "Gelöst",
          "phase": "done"
        }
      ],
      "transitions": [
        {
          "from": [
            "neu",
            "in_bearbeitung",
            "wartet_kunde"
          ],
          "id": "loesen",
          "label": "Lösen",
          "to": "geloest"
        }
      ],
      "version": 3
    }
  ]
}
```

### Example request

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

## Change notices for open desk pages (desk:read)

`GET /api/desk/v1/live`

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

Answers `text/event-stream` (`X-Accel-Buffering: no`, a `: ping` comment every 15 seconds). First a
`ready` event (`{}`), then one `change` event per item, project or configuration change the caller may see,
about one to two seconds after the commit; a new stream starts with the changes of the last 10
seconds. A notice only names what changed – the client reloads it through the API. `kind` is
`item` (with `action`, `itemId`, `number`, `spaceId` – empty when the item moved to a space the
caller cannot see –, `projectId`, `fromProjectId` when it left a project, `actor`; also for its SLA
warnings), `project` (`projectId`, `number`, `actor`), `callback` (`action`, `callbackId`, `number`, `actor`; only for
callers with desk:write), `config` (reload the bootstrap)
or `resync` (notices were dropped: reload everything shown). When the token expires, and after 15
minutes at the latest, the stream ends with a `reconnect` event (`{}`): reconnecting within 10 seconds
loses nothing. Any other end means notices may be missing; the client reloads what it shows. At most
10 open streams per person and 500 per tenant and server instance.

### Responses

- **200** Event stream (`text/event-stream`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)
- **429** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `kind` (string, required): What changed: item, project, configuration; resync: notices were lost, reload everything (one of `item`, `project`, `config`, `resync`)
- `action` (string): Action of the item event: created, updated, transitioned, commented, …, sla.warning, sla.breached, …
- `actor` (string): Login of who made the change (not on config notices)
- `fromProjectId` (string): The project the item left
- `itemId` (string): Changed item
- `number` (integer (int64)): Number of the changed item or project
- `projectId` (string): The item's project, or the changed project
- `spaceId` (string): Space of the changed item

### Example request

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

## Save tenant-wide settings (desk:admin)

`PUT /api/desk/v1/settings`

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

### Request body

`application/json` (required)

- `ai` (object): AI features of the desk (triage, subject, summary, draftReply). Triage with `autoApply` applies each proposed value that reaches `threshold` and leaves the rest pending; text fields read from the ticket are always suggestions. Draft replies never apply or run automatically; meeting summaries are never applied automatically. An applied summary fills the ticket's summary field (undo restores the previous one); with `autoApply` it fills it on its own unless a person wrote the summary (the suggestion then waits).
  - `features` (object): Settings per feature key (enabled, auto, autoApply, threshold)
- `callbacks` (object): Callback settings: the custom fields of the form (in order), the rules for the note and the mails to customers. `mailTexts` and `statusMail`: absent = the defaults (a manual mail text for the status `not_reached`, while that status exists), `[]` = none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the mode `auto`.
  - `fields` (array of object): Custom fields of the callback form in order
    - `key` (string, required): Key of a custom field (without cf.)
    - `required` (boolean): The field must be filled
  - `mailTexts` (array of object): Mail texts for customers. Placeholders: {{name}}, {{nummer}}, {{telefon}}, {{kunde}}, {{grund}}, {{gewuenscht}}, {{status}}, {{mitarbeiter}}; unknown ones are refused.
    - `body` (string, required): Text (placeholders allowed) (max length 8000)
    - `key` (string, required): Lower-case letters, digits, - and _; unique
    - `name` (string, required): Name of the mail text (max length 120)
    - `subject` (string, required): Subject (placeholders allowed) (max length 200)
  - `note` (object): Rules for the note of a callback (on create and when it changes); checked in the order required, minLength, pattern, aiCheck. Existing notes are not checked again.
    - `aiCheck` (boolean): The AI judges whether the note gives an understandable reason (422 `note_rejected` with a hint); an unavailable AI accepts the note
    - `minLength` (integer): Minimum characters of a non-empty note; 0 = off (max 2000)
    - `pattern` (string): Go (RE2) regular expression the note must contain a match of; anchor with ^ and $ for a full match (max length 500)
    - `patternMessage` (string): Shown instead of the pattern; required with a pattern (max length 200)
    - `required` (boolean): The note must not be empty
  - `statusMail` (array of object): Ties a mail text to a callbackStatus; a status without an entry sends nothing. Archived statuses may stay (they just stop firing).
    - `mode` (string, required): manual: the person decides when the status is set; auto: the mail is sent with the move into the status (one of `manual`, `auto`)
    - `status` (string, required): Key of a callbackStatus entry, once
    - `text` (string, required): Key of a mail text
- `mail` (object): Mail rules of the tenant; empty fields use the defaults.
  - `aiClassify` (boolean): The AI decides about unclear mail at or above aiThreshold
  - `aiThreshold` (number): Confidence the AI needs to decide about unclear mail (max 1)
  - `aiTrim` (boolean): The AI finds the main text of a long received mail (over 1500 characters) the rules could not trim (default false)
  - `blockedExtensions` (array of string): Default: executables and scripts
  - `bulkPolicy` (string): Newsletters and bulk mail: drop (default) or make a ticket (one of `drop`, `ticket`)
  - `foreignSubjectMatch` (boolean): A [#N] subject token appends mail of senders who are no participant
  - `fromName` (string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one of `agentWithMailbox`, `agent`, `mailbox`)
  - `maxAttachmentBytes` (integer): Per file, default 20 MB, max. 40 MB
  - `maxTotalBytes` (integer): Per mail, default 35 MB, max. 40 MB
  - `perSender10min` (integer): Above: appended quietly (default 10)
  - `perSenderHour` (integer): Above: held in the mail log (default 30)
- `priorityMatrix` (object): Priority from impact and urgency
  - `cells` (object): "<impact>|<urgency>" → priority key
  - `impacts` (array of object): Impact levels
    - `key` (string): Key of the level
    - `label` (string): Label of the level
  - `urgencies` (array of object): Urgency levels
    - `key` (string): Key of the level
    - `label` (string): Label of the level
- `time` (object): No longer used: rules for time entries and hourly billing (self approval, hour unit, tax rate, traffic light) are HR's work settings (ADR 0040); ignored on write and no longer returned

Example:

```json
{
  "callbacks": {
    "note": {
      "aiCheck": false,
      "minLength": 10,
      "required": true
    }
  },
  "mail": {
    "aiClassify": true,
    "aiThreshold": 0.8,
    "aiTrim": true,
    "blockedExtensions": [
      "exe",
      "bat",
      "js"
    ],
    "bulkPolicy": "drop",
    "fromName": "agentWithMailbox",
    "maxAttachmentBytes": 20971520,
    "maxTotalBytes": 31457280,
    "perSender10min": 10,
    "perSenderHour": 30
  }
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `ai` (object): AI features of the desk (triage, subject, summary, draftReply). Triage with `autoApply` applies each proposed value that reaches `threshold` and leaves the rest pending; text fields read from the ticket are always suggestions. Draft replies never apply or run automatically; meeting summaries are never applied automatically. An applied summary fills the ticket's summary field (undo restores the previous one); with `autoApply` it fills it on its own unless a person wrote the summary (the suggestion then waits).
  - `features` (object): Settings per feature key (enabled, auto, autoApply, threshold)
- `callbacks` (object): Callback settings: the custom fields of the form (in order), the rules for the note and the mails to customers. `mailTexts` and `statusMail`: absent = the defaults (a manual mail text for the status `not_reached`, while that status exists), `[]` = none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the mode `auto`.
  - `fields` (array of object): Custom fields of the callback form in order
    - `key` (string, required): Key of a custom field (without cf.)
    - `required` (boolean): The field must be filled
  - `mailTexts` (array of object): Mail texts for customers. Placeholders: {{name}}, {{nummer}}, {{telefon}}, {{kunde}}, {{grund}}, {{gewuenscht}}, {{status}}, {{mitarbeiter}}; unknown ones are refused.
    - `body` (string, required): Text (placeholders allowed) (max length 8000)
    - `key` (string, required): Lower-case letters, digits, - and _; unique
    - `name` (string, required): Name of the mail text (max length 120)
    - `subject` (string, required): Subject (placeholders allowed) (max length 200)
  - `note` (object): Rules for the note of a callback (on create and when it changes); checked in the order required, minLength, pattern, aiCheck. Existing notes are not checked again.
    - `aiCheck` (boolean): The AI judges whether the note gives an understandable reason (422 `note_rejected` with a hint); an unavailable AI accepts the note
    - `minLength` (integer): Minimum characters of a non-empty note; 0 = off (max 2000)
    - `pattern` (string): Go (RE2) regular expression the note must contain a match of; anchor with ^ and $ for a full match (max length 500)
    - `patternMessage` (string): Shown instead of the pattern; required with a pattern (max length 200)
    - `required` (boolean): The note must not be empty
  - `statusMail` (array of object): Ties a mail text to a callbackStatus; a status without an entry sends nothing. Archived statuses may stay (they just stop firing).
    - `mode` (string, required): manual: the person decides when the status is set; auto: the mail is sent with the move into the status (one of `manual`, `auto`)
    - `status` (string, required): Key of a callbackStatus entry, once
    - `text` (string, required): Key of a mail text
- `mail` (object): Mail rules of the tenant; empty fields use the defaults.
  - `aiClassify` (boolean): The AI decides about unclear mail at or above aiThreshold
  - `aiThreshold` (number): Confidence the AI needs to decide about unclear mail (max 1)
  - `aiTrim` (boolean): The AI finds the main text of a long received mail (over 1500 characters) the rules could not trim (default false)
  - `blockedExtensions` (array of string): Default: executables and scripts
  - `bulkPolicy` (string): Newsletters and bulk mail: drop (default) or make a ticket (one of `drop`, `ticket`)
  - `foreignSubjectMatch` (boolean): A [#N] subject token appends mail of senders who are no participant
  - `fromName` (string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one of `agentWithMailbox`, `agent`, `mailbox`)
  - `maxAttachmentBytes` (integer): Per file, default 20 MB, max. 40 MB
  - `maxTotalBytes` (integer): Per mail, default 35 MB, max. 40 MB
  - `perSender10min` (integer): Above: appended quietly (default 10)
  - `perSenderHour` (integer): Above: held in the mail log (default 30)
- `priorityMatrix` (object): Priority from impact and urgency
  - `cells` (object): "<impact>|<urgency>" → priority key
  - `impacts` (array of object): Impact levels
    - `key` (string): Key of the level
    - `label` (string): Label of the level
  - `urgencies` (array of object): Urgency levels
    - `key` (string): Key of the level
    - `label` (string): Label of the level
- `time` (object): No longer used: rules for time entries and hourly billing (self approval, hour unit, tax rate, traffic light) are HR's work settings (ADR 0040); ignored on write and no longer returned

Example 200 answer:

```json
{
  "ai": {
    "features": {
      "summary": {
        "auto": true,
        "autoApply": true,
        "enabled": true,
        "threshold": 0.8
      },
      "triage": {
        "auto": true,
        "autoApply": false,
        "enabled": true,
        "threshold": 0.85
      }
    }
  },
  "callbacks": {
    "fields": [],
    "note": {
      "aiCheck": false,
      "minLength": 10,
      "required": true
    },
    "statusMail": [
      {
        "mode": "manual",
        "status": "not_reached",
        "text": "nicht-erreicht"
      }
    ]
  },
  "mail": {
    "aiClassify": true,
    "aiThreshold": 0.8,
    "aiTrim": true,
    "blockedExtensions": [
      "exe",
      "bat",
      "js"
    ],
    "bulkPolicy": "drop",
    "foreignSubjectMatch": false,
    "fromName": "agentWithMailbox",
    "maxAttachmentBytes": 20971520,
    "maxTotalBytes": 31457280,
    "perSender10min": 10,
    "perSenderHour": 30
  },
  "priorityMatrix": {
    "cells": {
      "gering|hoch": "normal",
      "gering|mittel": "niedrig",
      "gering|niedrig": "niedrig",
      "hoch|hoch": "kritisch",
      "hoch|mittel": "hoch",
      "hoch|niedrig": "hoch",
      "mittel|hoch": "hoch",
      "mittel|mittel": "normal",
      "mittel|niedrig": "normal"
    },
    "impacts": [
      {
        "key": "gering",
        "label": "Gering"
      },
      {
        "key": "mittel",
        "label": "Mittel"
      },
      {
        "key": "hoch",
        "label": "Hoch"
      }
    ],
    "urgencies": [
      {
        "key": "niedrig",
        "label": "Niedrig"
      },
      {
        "key": "mittel",
        "label": "Mittel"
      },
      {
        "key": "hoch",
        "label": "Hoch"
      }
    ]
  }
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"callbacks":{"note":{"aiCheck":false,"minLength":10,"required":true}},"mail":{"aiClassify":true,"aiThreshold":0.8,"aiTrim":true,"blockedExtensions":["exe","bat","js"],"bulkPolicy":"drop","fromName":"agentWithMailbox","maxAttachmentBytes":20971520,"maxTotalBytes":31457280,"perSender10min":10,"perSenderHour":30}}'
```

## 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"}]}'
```

## Update a workflow, or check its impact first with dryRun (desk:admin)

`PUT /api/desk/v1/workflows/{id}`

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

Statuses used by items cannot be removed (`409 in_use`). The key cannot change.
With `dryRun=true` nothing is saved: the answer is the change's impact (`WorkflowImpact`) – statuses added,
removed, renamed and moved to another phase, transitions added and removed, how many items and projects sit
in each removed or phase-changed status, whether saving would be refused (`blocked`) and the automations of
the tenant and its spaces whose definitions mention those statuses (a hint: a key built at run time is not
found). The workflow is validated as for saving.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `dryRun` | query | boolean |  | Answer the impact, save nothing |

### 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
{
  "id": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01",
  "key": "service",
  "name": "Service",
  "note": "Status „Wartet auf Dritte“ pausiert jetzt die SLA-Uhr",
  "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": [
        "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
}
```

### Responses

- **200** Saved (the workflow), or with dryRun the impact (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 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)
- `automations` (array of object, required): Automations whose definitions mention a removed or phase-changed status
  - `id` (string)
  - `key` (string)
  - `name` (string)
  - `scope` (string)
  - `statuses` (array of string)
- `blocked` (boolean, required): A removed status is still in use – saving would answer 409 in_use
- `customerNames` (array of object, required): The customer portal's names (what requesters read) of removed or phase-changed statuses that change; `after` empty = the status is gone. Empty for project workflows and tenants without portal settings.
  - `after` (string)
  - `before` (string)
  - `key` (string)
- `diff` (object, required)
  - `added` (array of string): Status keys
  - `phaseChanged` (array of object)
    - `from` (string)
    - `key` (string)
    - `to` (string)
  - `removed` (array of string): Status keys
  - `renamed` (array of object)
    - `from` (string)
    - `key` (string)
    - `to` (string)
  - `transitionsAdded` (array of object)
    - `from` (string): A status key or `*`
    - `to` (string)
  - `transitionsRemoved` (array of object)
    - `from` (string)
    - `to` (string)
- `dryRun` (boolean, required): Always true – tells the impact from a saved workflow
- `statuses` (array of object, required): Removed and phase-changed statuses with what sits in them
  - `items` (integer)
  - `key` (string)
  - `projects` (integer)

Example 200 answer:

```json
{
  "automations": [],
  "blocked": true,
  "customerNames": [],
  "diff": {
    "added": [],
    "phaseChanged": [],
    "removed": [
      "wartet_dritte"
    ],
    "renamed": [],
    "transitionsAdded": [],
    "transitionsRemoved": [
      {
        "from": "neu",
        "to": "wartet_dritte"
      },
      {
        "from": "in_bearbeitung",
        "to": "wartet_dritte"
      }
    ]
  },
  "dryRun": true,
  "statuses": [
    {
      "items": 3,
      "key": "wartet_dritte",
      "projects": 0
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/workflows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"id":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01","key":"service","name":"Service","note":"Status „Wartet auf Dritte“ pausiert jetzt die SLA-Uhr","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":["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}'
```

## Latest changes of a workflow, SLA policy or space, with the notes sent with them (desk:admin; a space also its maintainers)

`GET /api/desk/v1/config-changes`

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

Every save of a workflow, an SLA policy or a space is recorded with who saved it, when and the optional `note`
of the save request (`ChangeNote`). Newest first. Workflows and SLA policies need `desk:admin`; a space also
its maintainers (`403` for other members, `404` for a space the caller does not see).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | query | string | yes | (one of `workflow`, `sla_policy`, `space`) |
| `objectId` | query | string (uuid) | yes | The workflow, policy or space |
| `limit` | query | integer |  | (default `5`; max 50) |

### Responses

- **200** Changes (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ConfigChange, required)
  - `action` (string, required): (one of `created`, `updated`)
  - `actorName` (string, required): Their name in histories; the platform team acting in a customer tenant reads „Plattformbetrieb (MBCOM) · <Name>“
  - `actorRef` (string, required): Who saved it (e-mail or login)
  - `at` (string (date-time), required)
  - `id` (string (uuid), required)
  - `kind` (string, required): (one of `workflow`, `sla_policy`, `space`)
  - `note` (string, required): The note sent with the save (empty = none)
  - `objectId` (string (uuid), required): The workflow, policy or space

Example 200 answer:

```json
{
  "items": [
    {
      "action": "updated",
      "actorName": "Marie Wagner",
      "actorRef": "marie.wagner@muster-it.example",
      "at": "2026-11-10T09:12:00Z",
      "id": "0e7f8a9b-1c2d-4e3f-8a5b-7c8d9e0f1a01",
      "kind": "workflow",
      "note": "Status „Wartet auf Dritte“ pausiert jetzt die SLA-Uhr",
      "objectId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
    },
    {
      "action": "created",
      "actorName": "Elias Gruber",
      "actorRef": "elias.gruber@muster-it.example",
      "at": "2026-09-01T07:00:00Z",
      "id": "0e7f8a9b-1c2d-4e3f-8a5b-7c8d9e0f1a02",
      "kind": "workflow",
      "note": "",
      "objectId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/config-changes?kind=workflow&objectId=3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an item type (desk:admin)

`POST /api/desk/v1/types`

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

### Request body

`application/json` (required)

- `key` (string, required): Key of the type, unique in the tenant
- `name` (string, required): Name of the item type
- `workflowId` (string, required): Workflow of the type
- `archived` (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
- `closeRequired` (array of string): Fields that must be filled before the item can be closed
- `color` (string): Display color of the item type
- `confidential` (boolean): Items of the type are confidential
- `description` (string): Description of the item type
- `focus` (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, `conversation`, `work`)
- `icon` (string): Icon of the item type
- `id` (string, read-only): Id of the item type
- `layout` (array of LayoutField): Custom fields of the record and their sections
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `level` (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)

Example:

```json
{
  "color": "neutral",
  "description": "Geplante Wartungsarbeiten beim Kunden",
  "focus": "work",
  "icon": "i-lucide-wrench",
  "key": "wartung",
  "layout": [
    {
      "key": "description",
      "section": "main"
    },
    {
      "key": "customer",
      "section": "aside"
    }
  ],
  "level": 1,
  "name": "Wartung",
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the type, unique in the tenant
- `name` (string, required): Name of the item type
- `workflowId` (string, required): Workflow of the type
- `archived` (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
- `closeRequired` (array of string): Fields that must be filled before the item can be closed
- `color` (string): Display color of the item type
- `confidential` (boolean): Items of the type are confidential
- `description` (string): Description of the item type
- `focus` (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, `conversation`, `work`)
- `icon` (string): Icon of the item type
- `id` (string, read-only): Id of the item type
- `layout` (array of LayoutField): Custom fields of the record and their sections
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `level` (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "archived": false,
  "closeRequired": [
    "cf.ursache",
    "cf.loesung",
    "cf.abschlussgrund"
  ],
  "color": "error",
  "confidential": false,
  "description": "Etwas funktioniert nicht und muss wiederhergestellt werden.",
  "focus": "conversation",
  "icon": "i-lucide-flame",
  "id": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "key": "stoerung",
  "layout": [
    {
      "key": "description",
      "section": "main"
    },
    {
      "key": "customer",
      "section": "aside"
    },
    {
      "key": "priority",
      "section": "aside"
    },
    {
      "key": "cf.betroffenes_system",
      "section": "aside"
    },
    {
      "key": "cf.ursache",
      "section": "closure"
    },
    {
      "key": "cf.loesung",
      "section": "closure"
    },
    {
      "key": "cf.abschlussgrund",
      "section": "closure"
    }
  ],
  "level": 1,
  "name": "Störung",
  "sortOrder": 1,
  "version": 2,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/types' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"color":"neutral","description":"Geplante Wartungsarbeiten beim Kunden","focus":"work","icon":"i-lucide-wrench","key":"wartung","layout":[{"key":"description","section":"main"},{"key":"customer","section":"aside"}],"level":1,"name":"Wartung","workflowId":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"}'
```

## Update an item type and its field layout (desk:admin)

`PUT /api/desk/v1/types/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the type, unique in the tenant
- `name` (string, required): Name of the item type
- `workflowId` (string, required): Workflow of the type
- `archived` (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
- `closeRequired` (array of string): Fields that must be filled before the item can be closed
- `color` (string): Display color of the item type
- `confidential` (boolean): Items of the type are confidential
- `description` (string): Description of the item type
- `focus` (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, `conversation`, `work`)
- `icon` (string): Icon of the item type
- `id` (string, read-only): Id of the item type
- `layout` (array of LayoutField): Custom fields of the record and their sections
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `level` (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)

Example:

```json
{
  "archived": false,
  "closeRequired": [
    "cf.ursache",
    "cf.loesung",
    "cf.abschlussgrund"
  ],
  "color": "error",
  "confidential": false,
  "description": "Etwas funktioniert nicht und muss wiederhergestellt werden.",
  "focus": "conversation",
  "icon": "i-lucide-flame",
  "id": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "key": "stoerung",
  "layout": [
    {
      "key": "description",
      "section": "main"
    },
    {
      "key": "customer",
      "section": "aside"
    },
    {
      "key": "priority",
      "section": "aside"
    },
    {
      "key": "cf.betroffenes_system",
      "section": "aside"
    },
    {
      "key": "cf.ursache",
      "section": "closure"
    },
    {
      "key": "cf.loesung",
      "section": "closure"
    },
    {
      "key": "cf.abschlussgrund",
      "section": "closure"
    }
  ],
  "level": 1,
  "name": "Störung",
  "sortOrder": 1,
  "version": 2,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
}
```

### Responses

- **200** Saved (`application/json`)
- **409** `in_use`: the new focus `work` would make a mail source, route, AI candidate, portal form or platform feedback kind deliver into a work type or a space with only work types (the message names them); `version_conflict` (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Key of the type, unique in the tenant
- `name` (string, required): Name of the item type
- `workflowId` (string, required): Workflow of the type
- `archived` (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
- `closeRequired` (array of string): Fields that must be filled before the item can be closed
- `color` (string): Display color of the item type
- `confidential` (boolean): Items of the type are confidential
- `description` (string): Description of the item type
- `focus` (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, `conversation`, `work`)
- `icon` (string): Icon of the item type
- `id` (string, read-only): Id of the item type
- `layout` (array of LayoutField): Custom fields of the record and their sections
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `level` (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "archived": false,
  "closeRequired": [
    "cf.ursache",
    "cf.loesung",
    "cf.abschlussgrund"
  ],
  "color": "error",
  "confidential": false,
  "description": "Etwas funktioniert nicht und muss wiederhergestellt werden.",
  "focus": "conversation",
  "icon": "i-lucide-flame",
  "id": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "key": "stoerung",
  "layout": [
    {
      "key": "description",
      "section": "main"
    },
    {
      "key": "customer",
      "section": "aside"
    },
    {
      "key": "priority",
      "section": "aside"
    },
    {
      "key": "cf.betroffenes_system",
      "section": "aside"
    },
    {
      "key": "cf.ursache",
      "section": "closure"
    },
    {
      "key": "cf.loesung",
      "section": "closure"
    },
    {
      "key": "cf.abschlussgrund",
      "section": "closure"
    }
  ],
  "level": 1,
  "name": "Störung",
  "sortOrder": 1,
  "version": 2,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/types/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"closeRequired":["cf.ursache","cf.loesung","cf.abschlussgrund"],"color":"error","confidential":false,"description":"Etwas funktioniert nicht und muss wiederhergestellt werden.","focus":"conversation","icon":"i-lucide-flame","id":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01","key":"stoerung","layout":[{"key":"description","section":"main"},{"key":"customer","section":"aside"},{"key":"priority","section":"aside"},{"key":"cf.betroffenes_system","section":"aside"},{"key":"cf.ursache","section":"closure"},{"key":"cf.loesung","section":"closure"},{"key":"cf.abschlussgrund","section":"closure"}],"level":1,"name":"Störung","sortOrder":1,"version":2,"workflowId":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"}'
```

## Create a space (desk:admin)

`POST /api/desk/v1/spaces`

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

### Request body

`application/json` (required)

- `key` (string, required): 2–10 upper-case letters or digits
- `name` (string, required): Name of the space
- `archived` (boolean): Archived: the space is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the space
- `defaultTypeId` (string): Type of new items without one
- `description` (string): Description of the space
- `icon` (string): Icon of the space
- `id` (string, read-only): Id of the space
- `members` (array of object): Members and their space roles
  - `role` (string): Space role (one of `viewer`, `reporter`, `agent`, `maintainer`)
  - `userRef` (string): Login (e-mail) of the member
- `settings` (object): Space settings; `mail` (reply mailbox, reopen policies) and `handoff` (what happens when a handoff comes back; ADR 0027). A space whose types all have the work focus is work-only: mail sources, routes, AI routing, portal forms and platform feedback cannot target it (400 `invalid`; leaving only work types in a space that mail or a portal form still delivers into is refused with field `typeIds`). Code settings are forge's (a sent `scm` is dropped).
  - `dueOnReceipt` (object): Due date on receipt: a new ticket of this space without `dueAt` gets one after the offset of its channel (`dueHasTime` true); work-focus types never. The channel comes from the ticket's `source`: `email` → mail; `portal`, `form`, `platform` → portal; `phone`, `nfon` → phone; `api` → api; `manual`, none, `teamviewer`, `teams` → manual; other sources (automation, handoff, …) get none. API clients send `source: api`, otherwise their tickets count as manual. `businessHours` counts the offset in the tenant's default service calendar (wall-clock time when it cannot be used) and takes no day unit. A channel left out sets nothing; `null` removes the setting. Invalid values are 400 with field `settings.dueOnReceipt.<channel>[.in]`.
    - `api` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `mail` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `manual` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `phone` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `portal` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
  - `handoff` (object): Hand back (design §3). `receiverOnReturn`: a ticket of this space that is handed back closes (`close`, default: `status` – a done status of the space's workflows – when its workflow has it, else its closed status) or stays (`keep`). `originOnReturn`: a ticket of this space whose handoff comes back does nothing (`none`, default) or moves to `status` / the first status of `stage` (new, active, waiting) unless it is in that phase already. Moves ignore transitions and required fields. Invalid values are 400 with field `settings.handoff…`.
    - `originOnReturn` (object): What happens to a ticket of this space when its handoff comes back
      - `action` (string): none (default) or move it to a status (one of `none`, `status`)
      - `stage` (string): Stage whose first status it moves to (status) (one of `new`, `active`, `waiting`)
      - `status` (string): Status it moves to (status)
    - `receiverOnReturn` (object): What happens to a ticket of this space that is handed back
      - `action` (string): close (default) or keep it open (one of `close`, `keep`)
      - `status` (string): Status to close with (close)
  - `projectTypeIds` (array of string): The project types the projects of this space may have (ids; keys are accepted on input), like the space lists its ticket types. Without it every project type is allowed. A project whose type the space does not list is refused with 422 field `typeId`; a project that keeps its type and space is not asked again. An unknown project type is 400 with field `settings.projectTypeIds`. Bundles do not carry it.
- `typeIds` (array of string): Allowed types; empty = all
- `version` (integer): Version of the space; send it back on change (409 version_conflict when it is outdated)
- `visibility` (string): tenant: everyone with desk access sees it; members: only its members (one of `tenant`, `members`)
- `note` (string): Why the configuration changes (trimmed, at most 500 characters, line breaks allowed; empty = no note) (max length 500)

Example:

```json
{
  "color": "warning",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "description": "Meldungen aus dem Monitoring der Kundennetze",
  "icon": "i-lucide-activity",
  "key": "NOC",
  "members": [
    {
      "role": "maintainer",
      "userRef": "lukas.wimmer@muster-it.example"
    }
  ],
  "name": "Netzwerkbetrieb",
  "note": "Eigener Bereich für Monitoring-Meldungen",
  "typeIds": [
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
  ],
  "visibility": "members"
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): 2–10 upper-case letters or digits
- `name` (string, required): Name of the space
- `archived` (boolean): Archived: the space is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the space
- `defaultTypeId` (string): Type of new items without one
- `description` (string): Description of the space
- `icon` (string): Icon of the space
- `id` (string, read-only): Id of the space
- `members` (array of object): Members and their space roles
  - `role` (string): Space role (one of `viewer`, `reporter`, `agent`, `maintainer`)
  - `userRef` (string): Login (e-mail) of the member
- `settings` (object): Space settings; `mail` (reply mailbox, reopen policies) and `handoff` (what happens when a handoff comes back; ADR 0027). A space whose types all have the work focus is work-only: mail sources, routes, AI routing, portal forms and platform feedback cannot target it (400 `invalid`; leaving only work types in a space that mail or a portal form still delivers into is refused with field `typeIds`). Code settings are forge's (a sent `scm` is dropped).
  - `dueOnReceipt` (object): Due date on receipt: a new ticket of this space without `dueAt` gets one after the offset of its channel (`dueHasTime` true); work-focus types never. The channel comes from the ticket's `source`: `email` → mail; `portal`, `form`, `platform` → portal; `phone`, `nfon` → phone; `api` → api; `manual`, none, `teamviewer`, `teams` → manual; other sources (automation, handoff, …) get none. API clients send `source: api`, otherwise their tickets count as manual. `businessHours` counts the offset in the tenant's default service calendar (wall-clock time when it cannot be used) and takes no day unit. A channel left out sets nothing; `null` removes the setting. Invalid values are 400 with field `settings.dueOnReceipt.<channel>[.in]`.
    - `api` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `mail` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `manual` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `phone` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `portal` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
  - `handoff` (object): Hand back (design §3). `receiverOnReturn`: a ticket of this space that is handed back closes (`close`, default: `status` – a done status of the space's workflows – when its workflow has it, else its closed status) or stays (`keep`). `originOnReturn`: a ticket of this space whose handoff comes back does nothing (`none`, default) or moves to `status` / the first status of `stage` (new, active, waiting) unless it is in that phase already. Moves ignore transitions and required fields. Invalid values are 400 with field `settings.handoff…`.
    - `originOnReturn` (object): What happens to a ticket of this space when its handoff comes back
      - `action` (string): none (default) or move it to a status (one of `none`, `status`)
      - `stage` (string): Stage whose first status it moves to (status) (one of `new`, `active`, `waiting`)
      - `status` (string): Status it moves to (status)
    - `receiverOnReturn` (object): What happens to a ticket of this space that is handed back
      - `action` (string): close (default) or keep it open (one of `close`, `keep`)
      - `status` (string): Status to close with (close)
  - `projectTypeIds` (array of string): The project types the projects of this space may have (ids; keys are accepted on input), like the space lists its ticket types. Without it every project type is allowed. A project whose type the space does not list is refused with 422 field `typeId`; a project that keeps its type and space is not asked again. An unknown project type is 400 with field `settings.projectTypeIds`. Bundles do not carry it.
- `typeIds` (array of string): Allowed types; empty = all
- `version` (integer): Version of the space; send it back on change (409 version_conflict when it is outdated)
- `visibility` (string): tenant: everyone with desk access sees it; members: only its members (one of `tenant`, `members`)

Example 201 answer:

```json
{
  "archived": false,
  "color": "info",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "description": "Service Desk für Kundenanfragen und Störungen",
  "icon": "i-lucide-headset",
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "key": "SUP",
  "members": [
    {
      "role": "agent",
      "userRef": "sophie.huber@muster-it.example"
    },
    {
      "role": "agent",
      "userRef": "elias.gruber@muster-it.example"
    }
  ],
  "name": "Support",
  "settings": {
    "dueOnReceipt": {
      "mail": {
        "businessHours": true,
        "in": "8h"
      },
      "phone": {
        "businessHours": true,
        "in": "4h"
      },
      "portal": {
        "in": "1d"
      }
    },
    "handoff": {
      "originOnReturn": {
        "action": "status",
        "stage": "active",
        "status": "in_bearbeitung"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "geloest"
      }
    }
  },
  "typeIds": [
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f04",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f05"
  ],
  "version": 4,
  "visibility": "tenant"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/spaces' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"color":"warning","defaultTypeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01","description":"Meldungen aus dem Monitoring der Kundennetze","icon":"i-lucide-activity","key":"NOC","members":[{"role":"maintainer","userRef":"lukas.wimmer@muster-it.example"}],"name":"Netzwerkbetrieb","note":"Eigener Bereich für Monitoring-Meldungen","typeIds":["5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"],"visibility":"members"}'
```

## Update a space and its members (desk:admin or space maintainer)

`PUT /api/desk/v1/spaces/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): 2–10 upper-case letters or digits
- `name` (string, required): Name of the space
- `archived` (boolean): Archived: the space is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the space
- `defaultTypeId` (string): Type of new items without one
- `description` (string): Description of the space
- `icon` (string): Icon of the space
- `id` (string, read-only): Id of the space
- `members` (array of object): Members and their space roles
  - `role` (string): Space role (one of `viewer`, `reporter`, `agent`, `maintainer`)
  - `userRef` (string): Login (e-mail) of the member
- `settings` (object): Space settings; `mail` (reply mailbox, reopen policies) and `handoff` (what happens when a handoff comes back; ADR 0027). A space whose types all have the work focus is work-only: mail sources, routes, AI routing, portal forms and platform feedback cannot target it (400 `invalid`; leaving only work types in a space that mail or a portal form still delivers into is refused with field `typeIds`). Code settings are forge's (a sent `scm` is dropped).
  - `dueOnReceipt` (object): Due date on receipt: a new ticket of this space without `dueAt` gets one after the offset of its channel (`dueHasTime` true); work-focus types never. The channel comes from the ticket's `source`: `email` → mail; `portal`, `form`, `platform` → portal; `phone`, `nfon` → phone; `api` → api; `manual`, none, `teamviewer`, `teams` → manual; other sources (automation, handoff, …) get none. API clients send `source: api`, otherwise their tickets count as manual. `businessHours` counts the offset in the tenant's default service calendar (wall-clock time when it cannot be used) and takes no day unit. A channel left out sets nothing; `null` removes the setting. Invalid values are 400 with field `settings.dueOnReceipt.<channel>[.in]`.
    - `api` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `mail` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `manual` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `phone` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `portal` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
  - `handoff` (object): Hand back (design §3). `receiverOnReturn`: a ticket of this space that is handed back closes (`close`, default: `status` – a done status of the space's workflows – when its workflow has it, else its closed status) or stays (`keep`). `originOnReturn`: a ticket of this space whose handoff comes back does nothing (`none`, default) or moves to `status` / the first status of `stage` (new, active, waiting) unless it is in that phase already. Moves ignore transitions and required fields. Invalid values are 400 with field `settings.handoff…`.
    - `originOnReturn` (object): What happens to a ticket of this space when its handoff comes back
      - `action` (string): none (default) or move it to a status (one of `none`, `status`)
      - `stage` (string): Stage whose first status it moves to (status) (one of `new`, `active`, `waiting`)
      - `status` (string): Status it moves to (status)
    - `receiverOnReturn` (object): What happens to a ticket of this space that is handed back
      - `action` (string): close (default) or keep it open (one of `close`, `keep`)
      - `status` (string): Status to close with (close)
  - `projectTypeIds` (array of string): The project types the projects of this space may have (ids; keys are accepted on input), like the space lists its ticket types. Without it every project type is allowed. A project whose type the space does not list is refused with 422 field `typeId`; a project that keeps its type and space is not asked again. An unknown project type is 400 with field `settings.projectTypeIds`. Bundles do not carry it.
- `typeIds` (array of string): Allowed types; empty = all
- `version` (integer): Version of the space; send it back on change (409 version_conflict when it is outdated)
- `visibility` (string): tenant: everyone with desk access sees it; members: only its members (one of `tenant`, `members`)
- `note` (string): Why the configuration changes (trimmed, at most 500 characters, line breaks allowed; empty = no note) (max length 500)

Example:

```json
{
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "description": "Service Desk für Kundenanfragen und Störungen",
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "key": "SUP",
  "name": "Support",
  "note": "Fälligkeit bei Eingang für Mail und Telefon",
  "settings": {
    "dueOnReceipt": {
      "mail": {
        "businessHours": true,
        "in": "8h"
      },
      "phone": {
        "businessHours": true,
        "in": "4h"
      }
    }
  },
  "typeIds": [
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02"
  ],
  "version": 4,
  "visibility": "tenant"
}
```

### Responses

- **200** Saved (`application/json`)

Fields of the 200 answer:

- `key` (string, required): 2–10 upper-case letters or digits
- `name` (string, required): Name of the space
- `archived` (boolean): Archived: the space is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the space
- `defaultTypeId` (string): Type of new items without one
- `description` (string): Description of the space
- `icon` (string): Icon of the space
- `id` (string, read-only): Id of the space
- `members` (array of object): Members and their space roles
  - `role` (string): Space role (one of `viewer`, `reporter`, `agent`, `maintainer`)
  - `userRef` (string): Login (e-mail) of the member
- `settings` (object): Space settings; `mail` (reply mailbox, reopen policies) and `handoff` (what happens when a handoff comes back; ADR 0027). A space whose types all have the work focus is work-only: mail sources, routes, AI routing, portal forms and platform feedback cannot target it (400 `invalid`; leaving only work types in a space that mail or a portal form still delivers into is refused with field `typeIds`). Code settings are forge's (a sent `scm` is dropped).
  - `dueOnReceipt` (object): Due date on receipt: a new ticket of this space without `dueAt` gets one after the offset of its channel (`dueHasTime` true); work-focus types never. The channel comes from the ticket's `source`: `email` → mail; `portal`, `form`, `platform` → portal; `phone`, `nfon` → phone; `api` → api; `manual`, none, `teamviewer`, `teams` → manual; other sources (automation, handoff, …) get none. API clients send `source: api`, otherwise their tickets count as manual. `businessHours` counts the offset in the tenant's default service calendar (wall-clock time when it cannot be used) and takes no day unit. A channel left out sets nothing; `null` removes the setting. Invalid values are 400 with field `settings.dueOnReceipt.<channel>[.in]`.
    - `api` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `mail` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `manual` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `phone` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
    - `portal` (DueOffset)
      - `in` (string, required): Offset from receipt like rule durations: `90m`, `4h`, `2d`; 1 minute to 365 days
      - `businessHours` (boolean): Count in the default service calendar's hours (minutes or hours only)
  - `handoff` (object): Hand back (design §3). `receiverOnReturn`: a ticket of this space that is handed back closes (`close`, default: `status` – a done status of the space's workflows – when its workflow has it, else its closed status) or stays (`keep`). `originOnReturn`: a ticket of this space whose handoff comes back does nothing (`none`, default) or moves to `status` / the first status of `stage` (new, active, waiting) unless it is in that phase already. Moves ignore transitions and required fields. Invalid values are 400 with field `settings.handoff…`.
    - `originOnReturn` (object): What happens to a ticket of this space when its handoff comes back
      - `action` (string): none (default) or move it to a status (one of `none`, `status`)
      - `stage` (string): Stage whose first status it moves to (status) (one of `new`, `active`, `waiting`)
      - `status` (string): Status it moves to (status)
    - `receiverOnReturn` (object): What happens to a ticket of this space that is handed back
      - `action` (string): close (default) or keep it open (one of `close`, `keep`)
      - `status` (string): Status to close with (close)
  - `projectTypeIds` (array of string): The project types the projects of this space may have (ids; keys are accepted on input), like the space lists its ticket types. Without it every project type is allowed. A project whose type the space does not list is refused with 422 field `typeId`; a project that keeps its type and space is not asked again. An unknown project type is 400 with field `settings.projectTypeIds`. Bundles do not carry it.
- `typeIds` (array of string): Allowed types; empty = all
- `version` (integer): Version of the space; send it back on change (409 version_conflict when it is outdated)
- `visibility` (string): tenant: everyone with desk access sees it; members: only its members (one of `tenant`, `members`)

Example 200 answer:

```json
{
  "archived": false,
  "color": "info",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "description": "Service Desk für Kundenanfragen und Störungen",
  "icon": "i-lucide-headset",
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "key": "SUP",
  "members": [
    {
      "role": "agent",
      "userRef": "sophie.huber@muster-it.example"
    },
    {
      "role": "agent",
      "userRef": "elias.gruber@muster-it.example"
    }
  ],
  "name": "Support",
  "settings": {
    "dueOnReceipt": {
      "mail": {
        "businessHours": true,
        "in": "8h"
      },
      "phone": {
        "businessHours": true,
        "in": "4h"
      },
      "portal": {
        "in": "1d"
      }
    },
    "handoff": {
      "originOnReturn": {
        "action": "status",
        "stage": "active",
        "status": "in_bearbeitung"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "geloest"
      }
    }
  },
  "typeIds": [
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f04",
    "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f05"
  ],
  "version": 4,
  "visibility": "tenant"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/spaces/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"defaultTypeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02","description":"Service Desk für Kundenanfragen und Störungen","id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00","key":"SUP","name":"Support","note":"Fälligkeit bei Eingang für Mail und Telefon","settings":{"dueOnReceipt":{"mail":{"businessHours":true,"in":"8h"},"phone":{"businessHours":true,"in":"4h"}}},"typeIds":["5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01","5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02"],"version":4,"visibility":"tenant"}'
```

## Create a custom field (desk:admin)

`POST /api/desk/v1/fields`

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

### Request body

`application/json` (required)

- `key` (string, required): Key of the field; item values are cf.<key>
- `kind` (string, required): Value kind of the field (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string, required): Display label
- `aiFill` (boolean): The AI may fill the field of new tickets (triage); only select and short text (`text`) fields. Text is only ever proposed, never applied without a person
- `archived` (boolean): Archived: kept on items, no longer offered
- `description` (string): Help text of the field
- `id` (string, read-only): Id of the custom field
- `kbRole` (string): Field holds the cause (one of ``, `cause`, `solution`, `workaround`)
- `options` (array of object): Choices of a select or multiselect field
  - `color` (string): Display color of the choice
  - `label` (string): Display label of the choice
  - `value` (string): Stored value of the choice

Example:

```json
{
  "aiFill": true,
  "description": "Seriennummer des betroffenen Geräts",
  "key": "seriennummer",
  "kind": "text",
  "label": "Seriennummer"
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the field; item values are cf.<key>
- `kind` (string, required): Value kind of the field (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string, required): Display label
- `aiFill` (boolean): The AI may fill the field of new tickets (triage); only select and short text (`text`) fields. Text is only ever proposed, never applied without a person
- `archived` (boolean): Archived: kept on items, no longer offered
- `description` (string): Help text of the field
- `id` (string, read-only): Id of the custom field
- `kbRole` (string): Field holds the cause (one of ``, `cause`, `solution`, `workaround`)
- `options` (array of object): Choices of a select or multiselect field
  - `color` (string): Display color of the choice
  - `label` (string): Display label of the choice
  - `value` (string): Stored value of the choice

Example 201 answer:

```json
{
  "aiFill": false,
  "archived": false,
  "description": "Warum das Ticket geschlossen wurde",
  "id": "7f4a5b6c-8d9e-4f0a-9b2c-4d5e6f7a8b04",
  "kbRole": "",
  "key": "abschlussgrund",
  "kind": "select",
  "label": "Abschlussgrund",
  "options": [
    {
      "label": "Behoben",
      "value": "behoben"
    },
    {
      "label": "Workaround",
      "value": "workaround"
    },
    {
      "label": "Kein Fehler",
      "value": "kein_fehler"
    },
    {
      "label": "Duplikat",
      "value": "duplikat"
    },
    {
      "label": "Vom Kunden zurückgezogen",
      "value": "zurueckgezogen"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/fields' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aiFill":true,"description":"Seriennummer des betroffenen Geräts","key":"seriennummer","kind":"text","label":"Seriennummer"}'
```

## Update a custom field (key and kind are fixed) (desk:admin)

`PUT /api/desk/v1/fields/{id}`

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

Archiving a field the callback form still places (`settings.callbacks.fields`) is 409 `in_use` with
`details.usedBy: [callbacks]`; remove it from the form first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the field; item values are cf.<key>
- `kind` (string, required): Value kind of the field (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string, required): Display label
- `aiFill` (boolean): The AI may fill the field of new tickets (triage); only select and short text (`text`) fields. Text is only ever proposed, never applied without a person
- `archived` (boolean): Archived: kept on items, no longer offered
- `description` (string): Help text of the field
- `id` (string, read-only): Id of the custom field
- `kbRole` (string): Field holds the cause (one of ``, `cause`, `solution`, `workaround`)
- `options` (array of object): Choices of a select or multiselect field
  - `color` (string): Display color of the choice
  - `label` (string): Display label of the choice
  - `value` (string): Stored value of the choice

Example:

```json
{
  "aiFill": false,
  "archived": false,
  "description": "Warum das Ticket geschlossen wurde",
  "id": "7f4a5b6c-8d9e-4f0a-9b2c-4d5e6f7a8b04",
  "kbRole": "",
  "key": "abschlussgrund",
  "kind": "select",
  "label": "Abschlussgrund",
  "options": [
    {
      "label": "Behoben",
      "value": "behoben"
    },
    {
      "label": "Workaround",
      "value": "workaround"
    },
    {
      "label": "Kein Fehler",
      "value": "kein_fehler"
    },
    {
      "label": "Duplikat",
      "value": "duplikat"
    },
    {
      "label": "Vom Kunden zurückgezogen",
      "value": "zurueckgezogen"
    }
  ]
}
```

### Responses

- **200** Saved (`application/json`)
- **409** in_use: the callback form places the field (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Key of the field; item values are cf.<key>
- `kind` (string, required): Value kind of the field (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string, required): Display label
- `aiFill` (boolean): The AI may fill the field of new tickets (triage); only select and short text (`text`) fields. Text is only ever proposed, never applied without a person
- `archived` (boolean): Archived: kept on items, no longer offered
- `description` (string): Help text of the field
- `id` (string, read-only): Id of the custom field
- `kbRole` (string): Field holds the cause (one of ``, `cause`, `solution`, `workaround`)
- `options` (array of object): Choices of a select or multiselect field
  - `color` (string): Display color of the choice
  - `label` (string): Display label of the choice
  - `value` (string): Stored value of the choice

Example 200 answer:

```json
{
  "aiFill": false,
  "archived": false,
  "description": "Warum das Ticket geschlossen wurde",
  "id": "7f4a5b6c-8d9e-4f0a-9b2c-4d5e6f7a8b04",
  "kbRole": "",
  "key": "abschlussgrund",
  "kind": "select",
  "label": "Abschlussgrund",
  "options": [
    {
      "label": "Behoben",
      "value": "behoben"
    },
    {
      "label": "Workaround",
      "value": "workaround"
    },
    {
      "label": "Kein Fehler",
      "value": "kein_fehler"
    },
    {
      "label": "Duplikat",
      "value": "duplikat"
    },
    {
      "label": "Vom Kunden zurückgezogen",
      "value": "zurueckgezogen"
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/fields/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aiFill":false,"archived":false,"description":"Warum das Ticket geschlossen wurde","id":"7f4a5b6c-8d9e-4f0a-9b2c-4d5e6f7a8b04","kbRole":"","key":"abschlussgrund","kind":"select","label":"Abschlussgrund","options":[{"label":"Behoben","value":"behoben"},{"label":"Workaround","value":"workaround"},{"label":"Kein Fehler","value":"kein_fehler"},{"label":"Duplikat","value":"duplikat"},{"label":"Vom Kunden zurückgezogen","value":"zurueckgezogen"}]}'
```

## Create a priority (desk:admin)

`POST /api/desk/v1/priorities`

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

### Request body

`application/json` (required)

- `key` (string, required): Key of the priority, unique in the tenant
- `label` (string, required): Display label of the priority
- `archived` (boolean): Archived: the priority is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the priority
- `id` (string): Id of the priority
- `isDefault` (boolean): Priority of new items without one
- `rank` (integer): Sort order of the priorities (ascending)

Example:

```json
{
  "color": "neutral",
  "key": "geplant",
  "label": "Geplant",
  "rank": 0
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the priority, unique in the tenant
- `label` (string, required): Display label of the priority
- `archived` (boolean): Archived: the priority is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the priority
- `id` (string): Id of the priority
- `isDefault` (boolean): Priority of new items without one
- `rank` (integer): Sort order of the priorities (ascending)

Example 201 answer:

```json
{
  "archived": false,
  "color": "warning",
  "id": "8a5b6c7d-9e0f-4a1b-8c3d-5e6f7a8b9c03",
  "isDefault": false,
  "key": "hoch",
  "label": "Hoch",
  "rank": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/priorities' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"color":"neutral","key":"geplant","label":"Geplant","rank":0}'
```

## Update a priority (desk:admin)

`PUT /api/desk/v1/priorities/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the priority, unique in the tenant
- `label` (string, required): Display label of the priority
- `archived` (boolean): Archived: the priority is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the priority
- `id` (string): Id of the priority
- `isDefault` (boolean): Priority of new items without one
- `rank` (integer): Sort order of the priorities (ascending)

Example:

```json
{
  "archived": false,
  "color": "warning",
  "id": "8a5b6c7d-9e0f-4a1b-8c3d-5e6f7a8b9c03",
  "isDefault": false,
  "key": "hoch",
  "label": "Hoch",
  "rank": 3
}
```

### Responses

- **200** Saved (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Key of the priority, unique in the tenant
- `label` (string, required): Display label of the priority
- `archived` (boolean): Archived: the priority is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the priority
- `id` (string): Id of the priority
- `isDefault` (boolean): Priority of new items without one
- `rank` (integer): Sort order of the priorities (ascending)

Example 200 answer:

```json
{
  "archived": false,
  "color": "warning",
  "id": "8a5b6c7d-9e0f-4a1b-8c3d-5e6f7a8b9c03",
  "isDefault": false,
  "key": "hoch",
  "label": "Hoch",
  "rank": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/priorities/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"color":"warning","id":"8a5b6c7d-9e0f-4a1b-8c3d-5e6f7a8b9c03","isDefault":false,"key":"hoch","label":"Hoch","rank":3}'
```

## Add an entry to a value list (desk:admin)

`POST /api/desk/v1/enums/{kind}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | path | string | yes | (one of `linkType`, `source`, `assigneeRole`, `callbackStatus`, `callbackReason`) |

### Request body

`application/json` (required)

- `key` (string, required): Key of the entry, unique in its list
- `label` (string, required): Display label
- `archived` (boolean): Archived: kept for existing data, no longer offered
- `color` (string): Display color
- `description` (string): Description of the entry
- `flags` (array of string): Flags of the entry (e.g. default)
- `props` (object): linkType: inverseLabel
- `sortOrder` (integer): Position in lists (ascending)
- `system` (boolean, read-only): Built-in entry desk relies on

Example:

```json
{
  "description": "Ein Teil der Störung besteht weiter",
  "key": "teilweise_behoben",
  "label": "Teilweise behoben",
  "sortOrder": 5
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the entry, unique in its list
- `label` (string, required): Display label
- `archived` (boolean): Archived: kept for existing data, no longer offered
- `color` (string): Display color
- `description` (string): Description of the entry
- `flags` (array of string): Flags of the entry (e.g. default)
- `props` (object): linkType: inverseLabel
- `sortOrder` (integer): Position in lists (ascending)
- `system` (boolean, read-only): Built-in entry desk relies on

Example 201 answer:

```json
{
  "archived": false,
  "description": "Dieses Ticket wurde durch das verknüpfte verursacht",
  "flags": [],
  "key": "caused_by",
  "label": "Verursacht durch",
  "props": {
    "inverse": "Verursacht"
  },
  "sortOrder": 4,
  "system": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/enums/linkType' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Ein Teil der Störung besteht weiter","key":"teilweise_behoben","label":"Teilweise behoben","sortOrder":5}'
```

## Update an entry of a value list; setting a unique flag such as default moves it here (desk:admin)

`PUT /api/desk/v1/enums/{kind}/{key}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | path | string | yes | (one of `linkType`, `source`, `assigneeRole`, `callbackStatus`, `callbackReason`) |
| `key` | path | string | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the entry, unique in its list
- `label` (string, required): Display label
- `archived` (boolean): Archived: kept for existing data, no longer offered
- `color` (string): Display color
- `description` (string): Description of the entry
- `flags` (array of string): Flags of the entry (e.g. default)
- `props` (object): linkType: inverseLabel
- `sortOrder` (integer): Position in lists (ascending)
- `system` (boolean, read-only): Built-in entry desk relies on

Example:

```json
{
  "archived": false,
  "description": "Dieses Ticket wurde durch das verknüpfte verursacht",
  "flags": [],
  "key": "caused_by",
  "label": "Verursacht durch",
  "props": {
    "inverse": "Verursacht"
  },
  "sortOrder": 4,
  "system": true
}
```

### Responses

- **200** Saved (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Key of the entry, unique in its list
- `label` (string, required): Display label
- `archived` (boolean): Archived: kept for existing data, no longer offered
- `color` (string): Display color
- `description` (string): Description of the entry
- `flags` (array of string): Flags of the entry (e.g. default)
- `props` (object): linkType: inverseLabel
- `sortOrder` (integer): Position in lists (ascending)
- `system` (boolean, read-only): Built-in entry desk relies on

Example 200 answer:

```json
{
  "archived": false,
  "description": "Dieses Ticket wurde durch das verknüpfte verursacht",
  "flags": [],
  "key": "caused_by",
  "label": "Verursacht durch",
  "props": {
    "inverse": "Verursacht"
  },
  "sortOrder": 4,
  "system": true
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/enums/linkType/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"description":"Dieses Ticket wurde durch das verknüpfte verursacht","flags":[],"key":"caused_by","label":"Verursacht durch","props":{"inverse":"Verursacht"},"sortOrder":4,"system":true}'
```

## Create a service calendar (desk:admin)

`POST /api/desk/v1/calendars`

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

### Request body

`application/json` (required)

- `key` (string, required): Key of the calendar, unique in the tenant
- `name` (string, required): Name of the calendar
- `archived` (boolean): Archived: the calendar is kept for existing data but no longer offered in pickers
- `description` (string): Description of the calendar
- `exceptions` (array of object): Days that differ from the week (holidays, special hours)
  - `closed` (boolean): Closed all day
  - `date` (string (date)): Day
  - `hours` (array of HourSpan): Service hours of the day (when not closed)
    - `from` (string): Start time (HH:MM)
    - `to` (string): End time (HH:MM)
  - `note` (string): Note (e.g. the holiday)
- `holidayRegion` (string): Empty = the tenant's federal state (HR), none, or a federal state code
- `id` (string, read-only): Id of the calendar
- `isDefault` (boolean): Calendar of policies that name none
- `onCall` (object): On-call windows by weekday key
- `timeZone` (string): IANA zone, default Europe/Berlin
- `version` (integer): Version of the calendar; send it back on change (409 version_conflict when it is outdated)
- `weekly` (object): Opening hours by weekday key (mon … sun)

Example:

```json
{
  "description": "Erweiterte Zeiten mit Rufbereitschaft am Wochenende",
  "key": "bereitschaft",
  "name": "Bereitschaft",
  "onCall": {
    "sat": [
      {
        "from": "09:00",
        "to": "13:00"
      }
    ]
  },
  "timeZone": "Europe/Berlin",
  "weekly": {
    "fri": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "mon": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "thu": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "tue": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "wed": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ]
  }
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the calendar, unique in the tenant
- `name` (string, required): Name of the calendar
- `archived` (boolean): Archived: the calendar is kept for existing data but no longer offered in pickers
- `description` (string): Description of the calendar
- `exceptions` (array of object): Days that differ from the week (holidays, special hours)
  - `closed` (boolean): Closed all day
  - `date` (string (date)): Day
  - `hours` (array of HourSpan): Service hours of the day (when not closed)
    - `from` (string): Start time (HH:MM)
    - `to` (string): End time (HH:MM)
  - `note` (string): Note (e.g. the holiday)
- `holidayRegion` (string): Empty = the tenant's federal state (HR), none, or a federal state code
- `id` (string, read-only): Id of the calendar
- `isDefault` (boolean): Calendar of policies that name none
- `onCall` (object): On-call windows by weekday key
- `timeZone` (string): IANA zone, default Europe/Berlin
- `version` (integer): Version of the calendar; send it back on change (409 version_conflict when it is outdated)
- `weekly` (object): Opening hours by weekday key (mon … sun)

Example 201 answer:

```json
{
  "archived": false,
  "description": "Montag bis Freitag, 8 bis 17 Uhr",
  "exceptions": [
    {
      "closed": true,
      "date": "2026-12-24",
      "hours": [],
      "note": "Heiligabend"
    },
    {
      "closed": false,
      "date": "2026-12-31",
      "hours": [
        {
          "from": "08:00",
          "to": "12:00"
        }
      ],
      "note": "Silvester nur vormittags"
    }
  ],
  "holidayRegion": "",
  "id": "2e9f0a1b-3c4d-4e5f-8a7b-9c0d1e2f3a01",
  "isDefault": true,
  "key": "geschaeftszeiten",
  "name": "Geschäftszeiten",
  "onCall": {},
  "timeZone": "Europe/Berlin",
  "version": 2,
  "weekly": {
    "fri": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "mon": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "thu": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "tue": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "wed": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/calendars' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Erweiterte Zeiten mit Rufbereitschaft am Wochenende","key":"bereitschaft","name":"Bereitschaft","onCall":{"sat":[{"from":"09:00","to":"13:00"}]},"timeZone":"Europe/Berlin","weekly":{"fri":[{"from":"07:00","to":"19:00"}],"mon":[{"from":"07:00","to":"19:00"}],"thu":[{"from":"07:00","to":"19:00"}],"tue":[{"from":"07:00","to":"19:00"}],"wed":[{"from":"07:00","to":"19:00"}]}}'
```

## Update a service calendar; needs the current version (desk:admin)

`PUT /api/desk/v1/calendars/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the calendar, unique in the tenant
- `name` (string, required): Name of the calendar
- `archived` (boolean): Archived: the calendar is kept for existing data but no longer offered in pickers
- `description` (string): Description of the calendar
- `exceptions` (array of object): Days that differ from the week (holidays, special hours)
  - `closed` (boolean): Closed all day
  - `date` (string (date)): Day
  - `hours` (array of HourSpan): Service hours of the day (when not closed)
    - `from` (string): Start time (HH:MM)
    - `to` (string): End time (HH:MM)
  - `note` (string): Note (e.g. the holiday)
- `holidayRegion` (string): Empty = the tenant's federal state (HR), none, or a federal state code
- `id` (string, read-only): Id of the calendar
- `isDefault` (boolean): Calendar of policies that name none
- `onCall` (object): On-call windows by weekday key
- `timeZone` (string): IANA zone, default Europe/Berlin
- `version` (integer): Version of the calendar; send it back on change (409 version_conflict when it is outdated)
- `weekly` (object): Opening hours by weekday key (mon … sun)

Example:

```json
{
  "archived": false,
  "description": "Montag bis Freitag, 8 bis 17 Uhr",
  "exceptions": [
    {
      "closed": true,
      "date": "2026-12-24",
      "hours": [],
      "note": "Heiligabend"
    },
    {
      "closed": false,
      "date": "2026-12-31",
      "hours": [
        {
          "from": "08:00",
          "to": "12:00"
        }
      ],
      "note": "Silvester nur vormittags"
    }
  ],
  "holidayRegion": "",
  "id": "2e9f0a1b-3c4d-4e5f-8a7b-9c0d1e2f3a01",
  "isDefault": true,
  "key": "geschaeftszeiten",
  "name": "Geschäftszeiten",
  "onCall": {},
  "timeZone": "Europe/Berlin",
  "version": 2,
  "weekly": {
    "fri": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "mon": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "thu": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "tue": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "wed": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ]
  }
}
```

### Responses

- **200** Saved (`application/json`)
- **409** Version conflict

Fields of the 200 answer:

- `key` (string, required): Key of the calendar, unique in the tenant
- `name` (string, required): Name of the calendar
- `archived` (boolean): Archived: the calendar is kept for existing data but no longer offered in pickers
- `description` (string): Description of the calendar
- `exceptions` (array of object): Days that differ from the week (holidays, special hours)
  - `closed` (boolean): Closed all day
  - `date` (string (date)): Day
  - `hours` (array of HourSpan): Service hours of the day (when not closed)
    - `from` (string): Start time (HH:MM)
    - `to` (string): End time (HH:MM)
  - `note` (string): Note (e.g. the holiday)
- `holidayRegion` (string): Empty = the tenant's federal state (HR), none, or a federal state code
- `id` (string, read-only): Id of the calendar
- `isDefault` (boolean): Calendar of policies that name none
- `onCall` (object): On-call windows by weekday key
- `timeZone` (string): IANA zone, default Europe/Berlin
- `version` (integer): Version of the calendar; send it back on change (409 version_conflict when it is outdated)
- `weekly` (object): Opening hours by weekday key (mon … sun)

Example 200 answer:

```json
{
  "archived": false,
  "description": "Montag bis Freitag, 8 bis 17 Uhr",
  "exceptions": [
    {
      "closed": true,
      "date": "2026-12-24",
      "hours": [],
      "note": "Heiligabend"
    },
    {
      "closed": false,
      "date": "2026-12-31",
      "hours": [
        {
          "from": "08:00",
          "to": "12:00"
        }
      ],
      "note": "Silvester nur vormittags"
    }
  ],
  "holidayRegion": "",
  "id": "2e9f0a1b-3c4d-4e5f-8a7b-9c0d1e2f3a01",
  "isDefault": true,
  "key": "geschaeftszeiten",
  "name": "Geschäftszeiten",
  "onCall": {},
  "timeZone": "Europe/Berlin",
  "version": 2,
  "weekly": {
    "fri": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "mon": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "thu": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "tue": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "wed": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ]
  }
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/calendars/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"description":"Montag bis Freitag, 8 bis 17 Uhr","exceptions":[{"closed":true,"date":"2026-12-24","hours":[],"note":"Heiligabend"},{"closed":false,"date":"2026-12-31","hours":[{"from":"08:00","to":"12:00"}],"note":"Silvester nur vormittags"}],"holidayRegion":"","id":"2e9f0a1b-3c4d-4e5f-8a7b-9c0d1e2f3a01","isDefault":true,"key":"geschaeftszeiten","name":"Geschäftszeiten","onCall":{},"timeZone":"Europe/Berlin","version":2,"weekly":{"fri":[{"from":"08:00","to":"17:00"}],"mon":[{"from":"08:00","to":"17:00"}],"thu":[{"from":"08:00","to":"17:00"}],"tue":[{"from":"08:00","to":"17:00"}],"wed":[{"from":"08:00","to":"17:00"}]}}'
```

## When do N minutes of service hours from a time end (desk:admin)

`GET /api/desk/v1/calendars/{id}/preview`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `from` | query | string (date-time) |  | Default now |
| `minutes` | query | integer |  |  |

### Responses

- **200** Preview (`application/json`)

Fields of the 200 answer:

- `dueAt` (string (date-time))
- `from` (string (date-time))
- `isOpen` (boolean)
- `openAt` (string (date-time)): Next opening time (from when open)

Example 200 answer:

```json
{
  "dueAt": "2026-11-19T10:30:00Z",
  "from": "2026-11-18T15:30:00Z",
  "isOpen": true,
  "openAt": "2026-11-18T15:30:00Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/calendars/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Configuration templates a tenant can apply (desk:admin)

`GET /api/desk/v1/templates`

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

### Responses

- **200** Templates (`application/json`)

Fields of the 200 answer:

- `items` (array of TemplateInfo, required)
  - `description` (string): What the template sets up
  - `key` (string): Key of the template
  - `name` (string): Name of the template
  - `summary` (object): Counts of spaces

Example 200 answer:

```json
{
  "items": [
    {
      "description": "Kundenanfragen und Störungen mit ITSM-Ticketarten, Warte-Status und Abschlussangaben",
      "key": "service-desk",
      "name": "Service Desk",
      "summary": {
        "fields": 8,
        "projectTemplates": 0,
        "projectTypes": 0,
        "spaces": 1,
        "teams": 2,
        "types": 5,
        "workflows": 1
      }
    },
    {
      "Projektbereich und der Vorlage „ERP-Einführung“": "",
      "description": "Projektart „Kundenprojekt“ mit Projektablauf",
      "key": "projects",
      "name": "Kundenprojekte",
      "summary": {
        "fields": 2,
        "projectTemplates": 1,
        "projectTypes": 1,
        "spaces": 1,
        "teams": 0,
        "types": 2,
        "workflows": 2
      }
    },
    {
      "description": "Nur Prioritäten und Wertelisten – Bereiche, Ticketarten und Abläufe legen Sie selbst an",
      "key": "empty",
      "name": "Leer",
      "summary": {
        "fields": 0,
        "projectTemplates": 0,
        "projectTypes": 0,
        "spaces": 0,
        "teams": 0,
        "types": 0,
        "workflows": 0
      }
    }
  ]
}
```

### Example request

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

## Apply a template; with dryRun only the plan is returned (desk:admin)

`POST /api/desk/v1/templates/{key}/apply`

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

Entries whose key is free are created, identical ones reused, and entries whose key exists with other content are created under the prefix. Value lists and priorities are only added.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes |  |

### Request body

`application/json`

- `bundle` (Bundle): Portable configuration (format desk.config/v1). All references use keys: types name their workflow key, spaces their type keys, labels their space key, categories their path of names, layouts "cf.<field key>".
  - `format` (string, required): Format of the bundle (one of `desk.config/v1`)
  - `categories` (array of object): Categories
  - `description` (string): Description of the bundle
  - `enums` (object): Value lists by kind
  - `fields` (array of object): Custom fields
  - `key` (string): Key of the bundle (templates)
  - `labels` (array of object): Labels
  - `matrix` (object): Priority matrix (impact × urgency)
  - `name` (string): Name of the bundle
  - `prefix` (string): Suggested prefix for conflicting keys
  - `priorities` (array of object): Priorities
  - `projectTemplates` (array of object): Project templates: type is the project type key; blueprint tasks name their typeId by type key, blueprint fields are keyed by field key
  - `projectTypes` (array of object): Project types: workflow, taskSpace and taskType are keys, layout "cf.<field key>", billing as in the project type settings
  - `spaces` (array of object): Spaces
  - `teams` (array of object): Teams
  - `types` (array of object): Item types
  - `workflows` (array of object): Workflows
- `dryRun` (boolean): Only return the plan, change nothing
- `prefix` (string): Up to 8 lower-case letters/digits for conflicting keys; default: the bundle suggestion

Example:

```json
{
  "dryRun": true,
  "prefix": ""
}
```

### Responses

- **200** Result or plan (`application/json`)

Fields of the 200 answer:

- `changes` (array of object): What the import does (or did) per entry
  - `action` (string): created: new; reused: an equal entry exists; renamed: created under another key (as) (one of `created`, `reused`, `renamed`)
  - `as` (string): Key the entry was created under (renamed)
  - `key` (string): Key of the entry in the bundle
  - `kind` (string): Kind of configuration entry (workflow, type, field, space, …)
  - `name` (string): The name or label of the entry, when it has one
- `dryRun` (boolean): Only the plan: nothing was changed

Example 200 answer:

```json
{
  "changes": [
    {
      "action": "reused",
      "key": "service",
      "kind": "workflow",
      "name": "Service"
    },
    {
      "action": "reused",
      "key": "stoerung",
      "kind": "type",
      "name": "Störung"
    },
    {
      "action": "reused",
      "key": "SUP",
      "kind": "space",
      "name": "Support"
    },
    {
      "action": "created",
      "key": "projekt",
      "kind": "workflow",
      "name": "Projekt"
    },
    {
      "action": "created",
      "key": "PRJ",
      "kind": "space",
      "name": "Kundenprojekte"
    },
    {
      "action": "created",
      "key": "kundenprojekt",
      "kind": "projectType",
      "name": "Kundenprojekt"
    },
    {
      "action": "created",
      "key": "erp-einfuehrung",
      "kind": "projectTemplate",
      "name": "ERP-Einführung"
    }
  ],
  "dryRun": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/templates/string/apply' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"dryRun":true,"prefix":""}'
```

## Export the configuration as a portable bundle (desk:admin)

`GET /api/desk/v1/bundle`

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

### Responses

- **200** Bundle (`application/json`)

Fields of the 200 answer:

- `format` (string, required): Format of the bundle (one of `desk.config/v1`)
- `categories` (array of object): Categories
- `description` (string): Description of the bundle
- `enums` (object): Value lists by kind
- `fields` (array of object): Custom fields
- `key` (string): Key of the bundle (templates)
- `labels` (array of object): Labels
- `matrix` (object): Priority matrix (impact × urgency)
- `name` (string): Name of the bundle
- `prefix` (string): Suggested prefix for conflicting keys
- `priorities` (array of object): Priorities
- `projectTemplates` (array of object): Project templates: type is the project type key; blueprint tasks name their typeId by type key, blueprint fields are keyed by field key
- `projectTypes` (array of object): Project types: workflow, taskSpace and taskType are keys, layout "cf.<field key>", billing as in the project type settings
- `spaces` (array of object): Spaces
- `teams` (array of object): Teams
- `types` (array of object): Item types
- `workflows` (array of object): Workflows

Example 200 answer:

```json
{
  "categories": [
    {
      "path": [
        "Netzwerk",
        "WLAN"
      ]
    }
  ],
  "description": "Export der Desk-Konfiguration",
  "fields": [
    {
      "key": "betroffenes_system",
      "kind": "text",
      "label": "Betroffenes System"
    }
  ],
  "format": "desk.config/v1",
  "key": "muster-it",
  "labels": [
    {
      "color": "warning",
      "name": "vor-ort"
    }
  ],
  "name": "Konfiguration Muster IT",
  "prefix": "",
  "priorities": [
    {
      "color": "neutral",
      "key": "niedrig",
      "label": "Niedrig",
      "rank": 1
    },
    {
      "color": "info",
      "isDefault": true,
      "key": "normal",
      "label": "Normal",
      "rank": 2
    },
    {
      "color": "warning",
      "key": "hoch",
      "label": "Hoch",
      "rank": 3
    },
    {
      "color": "error",
      "key": "kritisch",
      "label": "Kritisch",
      "rank": 4
    }
  ],
  "projectTemplates": [],
  "projectTypes": [],
  "spaces": [
    {
      "defaultType": "serviceanfrage",
      "key": "SUP",
      "name": "Support",
      "types": [
        "stoerung",
        "serviceanfrage"
      ]
    }
  ],
  "teams": [
    {
      "key": "first-level",
      "name": "Service Desk"
    }
  ],
  "types": [
    {
      "focus": "conversation",
      "key": "stoerung",
      "level": 1,
      "name": "Störung",
      "workflow": "service"
    }
  ],
  "workflows": [
    {
      "key": "service",
      "name": "Service",
      "statuses": [
        {
          "color": "info",
          "key": "neu",
          "label": "Neu",
          "phase": "new"
        },
        {
          "closed": true,
          "color": "success",
          "key": "geloest",
          "label": "Gelöst",
          "phase": "done"
        }
      ]
    }
  ]
}
```

### Example request

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

## Import a bundle; with dryRun only the plan is returned (desk:admin)

`POST /api/desk/v1/bundle`

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

### Request body

`application/json` (required)

- `bundle` (Bundle): Portable configuration (format desk.config/v1). All references use keys: types name their workflow key, spaces their type keys, labels their space key, categories their path of names, layouts "cf.<field key>".
  - `format` (string, required): Format of the bundle (one of `desk.config/v1`)
  - `categories` (array of object): Categories
  - `description` (string): Description of the bundle
  - `enums` (object): Value lists by kind
  - `fields` (array of object): Custom fields
  - `key` (string): Key of the bundle (templates)
  - `labels` (array of object): Labels
  - `matrix` (object): Priority matrix (impact × urgency)
  - `name` (string): Name of the bundle
  - `prefix` (string): Suggested prefix for conflicting keys
  - `priorities` (array of object): Priorities
  - `projectTemplates` (array of object): Project templates: type is the project type key; blueprint tasks name their typeId by type key, blueprint fields are keyed by field key
  - `projectTypes` (array of object): Project types: workflow, taskSpace and taskType are keys, layout "cf.<field key>", billing as in the project type settings
  - `spaces` (array of object): Spaces
  - `teams` (array of object): Teams
  - `types` (array of object): Item types
  - `workflows` (array of object): Workflows
- `dryRun` (boolean): Only return the plan, change nothing
- `prefix` (string): Up to 8 lower-case letters/digits for conflicting keys; default: the bundle suggestion

Example:

```json
{
  "bundle": {
    "categories": [
      {
        "path": [
          "Netzwerk",
          "WLAN"
        ]
      }
    ],
    "format": "desk.config/v1",
    "key": "muster-it",
    "labels": [
      {
        "color": "warning",
        "name": "vor-ort"
      }
    ],
    "name": "Konfiguration Muster IT"
  },
  "dryRun": true,
  "prefix": "imp"
}
```

### Responses

- **200** Result or plan (`application/json`)
- **409** `in_use`: the imported configuration would make a mail source, route, AI candidate, portal form or platform feedback kind deliver into a work type or a space with only work types (`application/json`)

Fields of the 200 answer:

- `changes` (array of object): What the import does (or did) per entry
  - `action` (string): created: new; reused: an equal entry exists; renamed: created under another key (as) (one of `created`, `reused`, `renamed`)
  - `as` (string): Key the entry was created under (renamed)
  - `key` (string): Key of the entry in the bundle
  - `kind` (string): Kind of configuration entry (workflow, type, field, space, …)
  - `name` (string): The name or label of the entry, when it has one
- `dryRun` (boolean): Only the plan: nothing was changed

Example 200 answer:

```json
{
  "changes": [
    {
      "action": "reused",
      "key": "service",
      "kind": "workflow",
      "name": "Service"
    },
    {
      "action": "reused",
      "key": "stoerung",
      "kind": "type",
      "name": "Störung"
    },
    {
      "action": "reused",
      "key": "SUP",
      "kind": "space",
      "name": "Support"
    },
    {
      "action": "created",
      "key": "projekt",
      "kind": "workflow",
      "name": "Projekt"
    },
    {
      "action": "created",
      "key": "PRJ",
      "kind": "space",
      "name": "Kundenprojekte"
    },
    {
      "action": "created",
      "key": "kundenprojekt",
      "kind": "projectType",
      "name": "Kundenprojekt"
    },
    {
      "action": "created",
      "key": "erp-einfuehrung",
      "kind": "projectTemplate",
      "name": "ERP-Einführung"
    }
  ],
  "dryRun": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/bundle' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"bundle":{"categories":[{"path":["Netzwerk","WLAN"]}],"format":"desk.config/v1","key":"muster-it","labels":[{"color":"warning","name":"vor-ort"}],"name":"Konfiguration Muster IT"},"dryRun":true,"prefix":"imp"}'
```

## Create a label (tenant labels: desk:admin; space labels: space maintainer)

`POST /api/desk/v1/labels`

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

### Request body

`application/json` (required)

- `name` (string, required): Name of the label
- `archived` (boolean): Archived: the label is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the label
- `description` (string): Description of the label
- `id` (string): Id of the label
- `spaceId` (string): Space of the label (empty: tenant-wide)

Example:

```json
{
  "color": "info",
  "description": "Fragen zur Rechnung",
  "name": "rechnung"
}
```

### Responses

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

Fields of the 201 answer:

- `name` (string, required): Name of the label
- `archived` (boolean): Archived: the label is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the label
- `description` (string): Description of the label
- `id` (string): Id of the label
- `spaceId` (string): Space of the label (empty: tenant-wide)

Example 201 answer:

```json
{
  "archived": false,
  "color": "warning",
  "description": "Einsatz beim Kunden nötig",
  "id": "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
  "name": "vor-ort",
  "spaceId": ""
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/labels' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"color":"info","description":"Fragen zur Rechnung","name":"rechnung"}'
```

## Update a label (desk:write)

`PUT /api/desk/v1/labels/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): Name of the label
- `archived` (boolean): Archived: the label is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the label
- `description` (string): Description of the label
- `id` (string): Id of the label
- `spaceId` (string): Space of the label (empty: tenant-wide)

Example:

```json
{
  "archived": false,
  "color": "warning",
  "description": "Einsatz beim Kunden nötig",
  "id": "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
  "name": "vor-ort",
  "spaceId": ""
}
```

### Responses

- **200** Saved (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the label
- `archived` (boolean): Archived: the label is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the label
- `description` (string): Description of the label
- `id` (string): Id of the label
- `spaceId` (string): Space of the label (empty: tenant-wide)

Example 200 answer:

```json
{
  "archived": false,
  "color": "warning",
  "description": "Einsatz beim Kunden nötig",
  "id": "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
  "name": "vor-ort",
  "spaceId": ""
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/labels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"color":"warning","description":"Einsatz beim Kunden nötig","id":"9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01","name":"vor-ort","spaceId":""}'
```

## Delete a label (removes it from all items) (desk:write)

`DELETE /api/desk/v1/labels/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/labels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a category (desk:admin)

`POST /api/desk/v1/categories`

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

### Request body

`application/json` (required)

- `name` (string, required): Name of the category
- `archived` (boolean): Archived: the category is kept for existing data but no longer offered in pickers
- `id` (string): Id of the category
- `parentId` (string): Parent category (empty: top level)
- `sortOrder` (integer): Position in lists (ascending)

Example:

```json
{
  "name": "Firewall",
  "parentId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01",
  "sortOrder": 3
}
```

### Responses

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

Fields of the 201 answer:

- `name` (string, required): Name of the category
- `archived` (boolean): Archived: the category is kept for existing data but no longer offered in pickers
- `id` (string): Id of the category
- `parentId` (string): Parent category (empty: top level)
- `sortOrder` (integer): Position in lists (ascending)

Example 201 answer:

```json
{
  "archived": false,
  "id": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "name": "WLAN",
  "parentId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01",
  "sortOrder": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/categories' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Firewall","parentId":"0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01","sortOrder":3}'
```

## Update a category (desk:admin)

`PUT /api/desk/v1/categories/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): Name of the category
- `archived` (boolean): Archived: the category is kept for existing data but no longer offered in pickers
- `id` (string): Id of the category
- `parentId` (string): Parent category (empty: top level)
- `sortOrder` (integer): Position in lists (ascending)

Example:

```json
{
  "archived": false,
  "id": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "name": "WLAN",
  "parentId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01",
  "sortOrder": 2
}
```

### Responses

- **200** Saved (`application/json`)

Fields of the 200 answer:

- `name` (string, required): Name of the category
- `archived` (boolean): Archived: the category is kept for existing data but no longer offered in pickers
- `id` (string): Id of the category
- `parentId` (string): Parent category (empty: top level)
- `sortOrder` (integer): Position in lists (ascending)

Example 200 answer:

```json
{
  "archived": false,
  "id": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "name": "WLAN",
  "parentId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01",
  "sortOrder": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/categories/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"id":"0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02","name":"WLAN","parentId":"0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e01","sortOrder":2}'
```

## Create a team (desk:admin)

`POST /api/desk/v1/teams`

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

### Request body

`application/json` (required)

- `key` (string, required): Key of the team, unique in the tenant
- `name` (string, required): Name of the team
- `archived` (boolean): Archived: the team is kept for existing data but no longer offered in pickers
- `description` (string): Description of the team
- `id` (string): Id of the team
- `members` (array of object): Members of the team
  - `role` (string): member or lead (one of `member`, `lead`)
  - `userRef` (string): Login (e-mail) of the member

Example:

```json
{
  "Exchange Online und Teams": "",
  "description": "Lizenzen",
  "key": "m365",
  "members": [
    {
      "role": "lead",
      "userRef": "marie.wagner@muster-it.example"
    }
  ],
  "name": "Microsoft 365"
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the team, unique in the tenant
- `name` (string, required): Name of the team
- `archived` (boolean): Archived: the team is kept for existing data but no longer offered in pickers
- `description` (string): Description of the team
- `id` (string): Id of the team
- `members` (array of object): Members of the team
  - `role` (string): member or lead (one of `member`, `lead`)
  - `userRef` (string): Login (e-mail) of the member

Example 201 answer:

```json
{
  "archived": false,
  "description": "Netzwerk, Server, Firewall und Projekte vor Ort.",
  "id": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02",
  "key": "second-level",
  "members": [
    {
      "role": "lead",
      "userRef": "jonas.bauer@muster-it.example"
    },
    {
      "role": "member",
      "userRef": "lukas.wimmer@muster-it.example"
    }
  ],
  "name": "Technik"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/teams' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"Exchange Online und Teams":"","description":"Lizenzen","key":"m365","members":[{"role":"lead","userRef":"marie.wagner@muster-it.example"}],"name":"Microsoft 365"}'
```

## Update a team and its members (desk:admin)

`PUT /api/desk/v1/teams/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the team, unique in the tenant
- `name` (string, required): Name of the team
- `archived` (boolean): Archived: the team is kept for existing data but no longer offered in pickers
- `description` (string): Description of the team
- `id` (string): Id of the team
- `members` (array of object): Members of the team
  - `role` (string): member or lead (one of `member`, `lead`)
  - `userRef` (string): Login (e-mail) of the member

Example:

```json
{
  "archived": false,
  "description": "Netzwerk, Server, Firewall und Projekte vor Ort.",
  "id": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02",
  "key": "second-level",
  "members": [
    {
      "role": "lead",
      "userRef": "jonas.bauer@muster-it.example"
    },
    {
      "role": "member",
      "userRef": "lukas.wimmer@muster-it.example"
    }
  ],
  "name": "Technik"
}
```

### Responses

- **200** Saved (`application/json`)

Fields of the 200 answer:

- `key` (string, required): Key of the team, unique in the tenant
- `name` (string, required): Name of the team
- `archived` (boolean): Archived: the team is kept for existing data but no longer offered in pickers
- `description` (string): Description of the team
- `id` (string): Id of the team
- `members` (array of object): Members of the team
  - `role` (string): member or lead (one of `member`, `lead`)
  - `userRef` (string): Login (e-mail) of the member

Example 200 answer:

```json
{
  "archived": false,
  "description": "Netzwerk, Server, Firewall und Projekte vor Ort.",
  "id": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02",
  "key": "second-level",
  "members": [
    {
      "role": "lead",
      "userRef": "jonas.bauer@muster-it.example"
    },
    {
      "role": "member",
      "userRef": "lukas.wimmer@muster-it.example"
    }
  ],
  "name": "Technik"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/teams/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"description":"Netzwerk, Server, Firewall und Projekte vor Ort.","id":"1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02","key":"second-level","members":[{"role":"lead","userRef":"jonas.bauer@muster-it.example"},{"role":"member","userRef":"lukas.wimmer@muster-it.example"}],"name":"Technik"}'
```

## Users known to the desk (for pickers) (desk:read)

`GET /api/desk/v1/people`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |

### Responses

- **200** People (`application/json`)

Fields of the 200 answer:

- `items` (array of Person, required)
  - `active` (boolean): Whether the person is active in the people directory
  - `lastSeenAt` (string (date-time)): When the person last used desk
  - `name` (string): Name
  - `userRef` (string): Login (e-mail)

Example 200 answer:

```json
{
  "items": [
    {
      "active": true,
      "lastSeenAt": "2026-11-18T08:40:00Z",
      "name": "Elias Gruber",
      "userRef": "elias.gruber@muster-it.example"
    },
    {
      "active": true,
      "lastSeenAt": "2026-11-18T07:55:00Z",
      "name": "Lukas Wimmer",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "active": true,
      "lastSeenAt": "2026-11-18T08:58:00Z",
      "name": "Sophie Huber",
      "userRef": "sophie.huber@muster-it.example"
    }
  ]
}
```

### Example request

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

## Customers of the tenant for the customer picker (desk:write, desk:admin or hr:work:billing)

`GET /api/desk/v1/directory/customers`

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

Masterdata addresses with the role customer, matching `q` by name, number or city (at most 20). The `id` is what a ticket's, project's or work entry's `customer.id` stores.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |

### Responses

- **200** Customers (`application/json`)
- **403** Error (`application/json`)
- **503** Masterdata is not configured or not reachable (`application/json`)

Fields of the 200 answer:

- `items` (array of CustomerOption, required)
  - `id` (string (uuid), required): Masterdata address id – the customer ref of tickets
  - `name` (string, required): Name of the customer
  - `adrNr` (string): Address number in masterdata
  - `blockReason` (string): Why the customer is blocked
  - `blocked` (boolean): The customer is blocked in masterdata
  - `city` (string): City of the customer
  - `customerNumber` (string): Customer number

Example 200 answer:

```json
{
  "items": [
    {
      "adrNr": "10005",
      "blockReason": "",
      "blocked": false,
      "city": "Neutraubling",
      "customerNumber": "10005",
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
      "name": "Donau Maschinenbau AG"
    }
  ]
}
```

### Example request

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

## Active articles for the flat-rate article picker (desk:write, desk:admin or hr:work:billing)

`GET /api/desk/v1/directory/articles`

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

Active masterdata articles matching `q` by number or name (at most 20) for the booking form of HR's work entries; the `id` is what a flat-rate work entry's `article.id` stores.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |

### Responses

- **200** Articles (`application/json`)
- **403** Error (`application/json`)
- **503** Masterdata is not configured or not reachable (`application/json`)

Fields of the 200 answer:

- `items` (array of ArticleOption, required)
  - `articleNumber` (string, required): Article number in masterdata
  - `id` (string (uuid), required): Masterdata article id – the `article.id` of flat-rate work entries in HR
  - `name` (string, required): Article name
  - `unit` (string): Sales unit of the article

Example 200 answer:

```json
{
  "items": [
    {
      "articleNumber": "WA-9104",
      "id": "4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c01",
      "name": "Wartungspauschale Server monatlich",
      "unit": "Monat"
    }
  ]
}
```

### Example request

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

## Active contact persons of a customer for the contact picker (desk:write, desk:admin or hr:work:billing, as searchCustomers)

`GET /api/desk/v1/directory/customers/{id}/contacts`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Contacts (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **503** Masterdata is not configured or not reachable (`application/json`)

Fields of the 200 answer:

- `items` (array of ContactOption, required)
  - `id` (string (uuid), required): Masterdata contact person id – the contact ref of tickets
  - `name` (string, required): Name of the contact person
  - `email` (string): E-mail address of the contact person
  - `position` (string): Position of the contact person

Example 200 answer:

```json
{
  "items": [
    {
      "email": "stefan.eder@donau-maschinenbau.example",
      "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d51",
      "name": "Stefan Eder",
      "position": "IT-Leiter"
    },
    {
      "email": "sabine.wolf@donau-maschinenbau.example",
      "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d52",
      "name": "Sabine Wolf",
      "position": "Einkauf"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/directory/customers/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/contacts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Module settings: mailboxes, sender, AI (tenant:settings:read)

`GET /api/desk/v1/config`

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

### Responses

- **200** Settings

### Example request

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

## Save module settings (tenant:settings:write)

`PUT /api/desk/v1/config`

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

### Responses

- **200** Saved

### Example request

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

## Module status (tenant:settings:read)

`GET /api/desk/v1/config/status`

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

### Responses

- **200** Status

### Example request

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

# Items

## List items (desk:read)

`GET /api/desk/v1/items`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `space` | query | string |  | Space ids or keys (comma separated) |
| `type` | query | string |  | Type ids or keys |
| `status` | query | string |  |  |
| `phase` | query | string |  | new, active, waiting, done |
| `assignee` | query | string |  | User ref, `me` or `none` |
| `team` | query | string |  | Team ids or keys (comma separated); `mine` stands for the teams the caller is a member of. Items of any of these teams; an unknown team, or `mine` for a caller in no team, gives an empty list |
| `label` | query | string |  | All of these labels |
| `priority` | query | string |  |  |
| `project` | query | string |  | Project id or `none` |
| `projects` | query | string |  | Project ids (comma separated) |
| `projectTickets` | query | string |  | How tickets of projects show: `view` (ticket lists: tickets without project, of projects displaying tickets, and those assigned to the caller), `none` (without project), `only` (with project); omitted filters nothing (one of `view`, `none`, `only`) |
| `customer` | query | string |  | Customer ids (comma separated); items of any of these customers |
| `parent` | query | string |  | Parent id or `none` |
| `category` | query | string |  | Category ids (comma separated); items of these categories or of any category below them |
| `notSpace` | query | string |  | Space ids or keys (comma separated); items of none of these spaces. An unknown space excludes nothing |
| `notType` | query | string |  | Type ids or keys (comma separated); items of none of these types. An unknown type excludes nothing |
| `notStatus` | query | string |  | Status keys (comma separated); items in none of these statuses |
| `notTeam` | query | string |  | Team ids or keys (comma separated), `mine` for the teams the caller is a member of; items of none of these teams (an item in several teams is left out when any of them is listed). An unknown team, or `mine` for a caller in no team, excludes nothing |
| `notPriority` | query | string |  | Priority keys (comma separated); items with none of these priorities, items without priority stay |
| `notLabel` | query | string |  | Label ids (comma separated); items that have none of these labels. An unknown label excludes nothing |
| `notCustomer` | query | string |  | Customer ids (comma separated); items of none of these customers, items without customer stay |
| `notCategory` | query | string |  | Category ids (comma separated); items of none of these categories nor of any category below them, items without category stay. An unknown category excludes nothing |
| `notAssignee` | query | string |  | User ref or `me`; items this person does not work on (watchers do not count as working on it) |
| `q` | query | string |  | Full-text search |
| `number` | query | integer |  |  |
| `dueBefore` | query | string (date-time) |  |  |
| `slaState` | query | string |  | Comma-separated: none, running, warning, breached, paused, met |
| `slaDueBefore` | query | string (date-time) |  | Earliest running SLA deadline before |
| `createdAfter` | query | string (date-time) |  |  |
| `createdBefore` | query | string (date-time) |  | Created before (RFC 3339 or a date) |
| `closedAfter` | query | string (date-time) |  | Closed at or after (RFC 3339 or a date); items that are not closed are left out |
| `closedBefore` | query | string (date-time) |  | Closed before (RFC 3339 or a date); items that are not closed are left out |
| `updatedSince` | query | string (date-time) |  |  |
| `includeMerged` | query | boolean |  |  |
| `cf.{key}` | query | string |  | Custom field value (JSON or plain string) |
| `sort` | query | string |  | (one of `updated`, `created`, `number`, `due`, `priority`, `rank`, `title`, `sla`) |
| `order` | query | string |  | (one of `asc`, `desc`) |
| `limit` | query | integer |  | 1–500; another value is a 400 invalid. (default `100`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page (keyset: sort value and id of its last item). Valid only with the same `sort` and `order`, else 400 invalid with `field: cursor`. |

### Responses

- **200** A page of items (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required): Items of the page
- `total` (integer, required): Number of items matching the filter
- `nextCursor` (string): Cursor of the next page (keyset, bound to `sort` and `order`); missing on the last page.

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "lukas.wimmer@muster-it.example"
        },
        {
          "role": "assignee",
          "userRef": "sophie.huber@muster-it.example"
        }
      ],
      "createdAt": "2026-11-17T07:12:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "labelIds": [
        "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
        "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
      ],
      "number": 1,
      "phase": "active",
      "priority": "hoch",
      "slaDueAt": "2026-11-17T15:12:00Z",
      "slaState": "running",
      "source": "phone",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "spentMinutes": 45,
      "status": "in_bearbeitung",
      "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "updatedAt": "2026-11-17T08:55:00Z",
      "version": 6
    },
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "sophie.huber@muster-it.example"
        }
      ],
      "createdAt": "2026-11-13T08:20:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
      "labelIds": [],
      "number": 37,
      "phase": "waiting",
      "priority": "normal",
      "slaDueAt": null,
      "slaState": "paused",
      "source": "portal",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "spentMinutes": 20,
      "status": "wartet_dritte",
      "title": "App zeigt gelöste Tickets weiterhin als offen",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "updatedAt": "2026-11-13T09:10:00Z",
      "version": 4
    }
  ],
  "nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTExLTEzVDA5OjEwOjAwWiJ9",
  "total": 14
}
```

### Example request

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

## Create an item (desk:write)

`POST /api/desk/v1/items`

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

The body has the item's JSON shape. `spaceId` and `typeId` accept ids or keys; without
`typeId` the space's default type is used, without `status` the workflow's first "new" status.
Required fields of the type layout must be filled (`422 missing_fields`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string |  |  |

### Request body

`application/json` (required)

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item

Example:

```json
{
  "customFields": {
    "betroffenes_system": "FortiClient 7.2"
  },
  "customer": {
    "id": "K-10023",
    "name": "Muster GmbH"
  },
  "description": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "impact": "mittel",
  "spaceId": "SUP",
  "title": "VPN-Verbindung bricht ab",
  "typeId": "stoerung",
  "urgency": "hoch"
}
```

### Responses

- **200** Existing item (idempotency or dedupe key) (`application/json`)
- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 201 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "assignees": [],
  "createdAt": "2026-11-18T09:14:00Z",
  "createdBy": "api:ticket-import",
  "customFields": {
    "betroffenes_system": "FortiClient 7.2"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12",
    "name": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"
  },
  "description": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c4e",
  "impact": "mittel",
  "labelIds": [],
  "number": 78,
  "phase": "new",
  "priority": "hoch",
  "slaDueAt": "2026-11-18T13:14:00Z",
  "slaState": "running",
  "source": "api",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "status": "neu",
  "statusChangedAt": "2026-11-18T09:14:00Z",
  "summary": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "summarySource": "auto",
  "teams": [],
  "title": "VPN-Verbindung bricht ab",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-18T09:14:00Z",
  "updatedBy": "api:ticket-import",
  "urgency": "hoch",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customFields":{"betroffenes_system":"FortiClient 7.2"},"customer":{"id":"K-10023","name":"Muster GmbH"},"description":"Seit heute morgen trennt der VPN-Client alle 5 Minuten.","impact":"mittel","spaceId":"SUP","title":"VPN-Verbindung bricht ab","typeId":"stoerung","urgency":"hoch"}'
```

## Check a new item without creating it (desk:write)

`POST /api/desk/v1/items/check`

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

Runs every check of `POST /items` (space, type, status, field values, required fields of the type
layout) except the parent, without storing anything. Answers the same errors as `POST /items`.
With `preview=true` the answer also says what creating the item would do (the portal's create form,
„Beim Anlegen passiert“): the due date on receipt of its space and source, the SLA policy with the due
time of each target (none while the start status pauses the clock) and the enabled automations of
`desk.item.created` in the tenant and the space whose filter holds for the new item. Nothing runs and
nothing is recorded; the server decides again when the item is created.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `preview` | query | boolean |  | Also answer `preview`: what creating the item would do |

### Request body

`application/json` (required)

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item

Example:

```json
{
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "impact": "mittel",
  "source": "api",
  "spaceId": "SUP",
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "stoerung",
  "urgency": "hoch"
}
```

### Responses

- **200** Valid (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `preview` (ItemPreview): What creating an item would do (`POST /items/check?preview=true`); nothing is stored.
  - `automations` (array of object): Enabled automations of `desk.item.created` (tenant first, then the space) whose filter holds
    - `id` (string)
    - `key` (string)
    - `name` (string)
    - `scope` (string): `tenant` or `space:<id>`
  - `dueAt` (string (date-time), nullable): The due date on receipt (`space.settings.dueOnReceipt`), else null
  - `sla` (object, nullable): The SLA policy the item would get; null when none applies (no policy matches, a work type)
    - `policyKey` (string)
    - `policyName` (string)
    - `targets` (array of object)
      - `dueAt` (string (date-time), nullable): Null while the start status pauses the clock
      - `target` (string): (one of `first_response`, `resolution`)
- `valid` (boolean)

Example 200 answer:

```json
{
  "preview": {
    "automations": [],
    "dueAt": "2026-11-18T13:14:00Z",
    "sla": {
      "policyKey": "standard",
      "policyName": "Standard",
      "targets": [
        {
          "dueAt": "2026-11-18T13:14:00Z",
          "target": "first_response"
        },
        {
          "dueAt": "2026-11-19T09:14:00Z",
          "target": "resolution"
        }
      ]
    }
  },
  "valid": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/check' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contact":{"id":"6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11","name":"Katrin Stadler"},"customFields":{"betroffenes_system":"Access Points 2. OG (AP-201, AP-207)"},"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11","name":"Alpenhotel Seeblick GmbH \u0026 Co. KG"},"description":"Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.","impact":"mittel","source":"api","spaceId":"SUP","title":"WLAN in den Gästezimmern 2. OG fällt immer wieder aus","typeId":"stoerung","urgency":"hoch"}'
```

## Change status, fields and labels of many items, or check first with dryRun (desk:write)

`POST /api/desk/v1/items/bulk`

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

### Request body

`application/json` (required)

- `ids` (array of string, required): Ids of the items to change
- `addLabelIds` (array of string): Labels to add (ids)
- `dryRun` (boolean): Change nothing: `updated` lists the items the change would apply to, `failed` and `missingFields` why the others would stay as they are (agent role, writable item, the transition with its required fields and comment). An item already in the status would not change. No automation, mail or live notice follows.
- `patch` (ItemInput)
  - `assignees` (array of object): People working on the item (the whole list)
    - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
    - `userRef` (string): Login (e-mail) of the person
  - `categoryId` (string, nullable): Category of the item
  - `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
  - `contact` (Ref | null): Masterdata contact person of the item (null clears)
  - `customFields` (object): Merged; null removes a value
  - `customer` (Ref | null): Masterdata customer of the item (null clears)
  - `dedupeKey` (string): Create only; repeated deliveries return the existing item
  - `description` (string): Markdown
  - `dueAt` (string (date-time), nullable): Due date
  - `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
  - `estimateMinutes` (integer, nullable): Estimate in minutes
  - `followUpAt` (string (date-time), nullable): When to follow up
  - `impact` (string, nullable): Impact key of the priority matrix
  - `kbWorthy` (boolean): Candidate for the knowledge base once resolved
  - `labelIds` (array of string): Labels of the item (ids; the whole list)
  - `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
  - `priority` (string, nullable): Priority key
  - `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
  - `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
  - `rank` (string): Board order (base-36 fraction)
  - `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
  - `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
  - `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
  - `spaceId` (string): Create only
  - `startOn` (string (date), nullable): Start date
  - `status` (string): Create only
  - `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
  - `teams` (array of object): Teams of the item (the whole list)
    - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
    - `teamId` (string): Id of the team
  - `title` (string): Title of the item (max length 500)
  - `typeId` (string): Create only
  - `urgency` (string, nullable): Urgency key of the priority matrix
  - `weight` (integer, nullable): Weight of the item
- `removeLabelIds` (array of string): Labels to remove (ids)
- `status` (string): Status key to move every item to

Example:

```json
{
  "addLabelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "dryRun": false,
  "ids": [
    "#37",
    "#41"
  ],
  "patch": {
    "priority": "hoch"
  }
}
```

### Responses

- **200** Per-item result (`application/json`)

Fields of the 200 answer:

- `dryRun` (boolean): True when the request was a dry run (nothing changed).
- `failed` (object): Why an item was not changed, in German, per item id
- `missingFields` (object): Required fields the status change needs, per failed item id; retry that item with a transition that sends them
- `updated` (array of string): The items changed – with dryRun the items the change would apply to

Example 200 answer:

```json
{
  "dryRun": false,
  "failed": {
    "#41": "Der Status „Gelöst“ verlangt die Felder Ursache, Lösung und Abschlussgrund"
  },
  "missingFields": {
    "#41": [
      "cf.ursache",
      "cf.loesung",
      "cf.abschlussgrund"
    ]
  },
  "updated": [
    "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37"
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/bulk' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addLabelIds":["9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"],"dryRun":false,"ids":["#37","#41"],"patch":{"priority":"hoch"}}'
```

## Merge several items into one, all or none (desk:write)

`POST /api/desk/v1/items/merge`

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

Merges every source into the target like `POST /items/{ref}/merge` (entries, time, checklist, links,
children and people in copy move; each source is closed, marked as merged and linked as duplicate).
References are ids or numbers (`#123`); duplicates are ignored. All tickets are locked in ascending id
order. Every source is checked first – not the target itself, not merged already, not converted or being
converted, the agent role in its space, the target not below it – and one refused source refuses the whole
merge: 422 `merge_refused` with `details.refused` naming the reason (German) per source (`#123`); nothing
changes. The target needs the agent role and must be writable (403, 409 `converted`, 422 `merge`). Public
entries of a source become internal when the target has other requesters, unless `exposeToParticipants`.

### Request body

`application/json` (required)

- `sourceIds` (array of string, required): Ids or numbers of the tickets merged into the target
- `targetId` (string, required): Id or number of the ticket that receives the others
- `exposeToParticipants` (boolean): Keep moved public entries public although the target has other requesters

Example:

```json
{
  "exposeToParticipants": false,
  "sourceIds": [
    "#121",
    "#124"
  ],
  "targetId": "#120"
}
```

### Responses

- **200** The target item (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** merge_refused (details.refused: reason per source) or merge (the target is merged already) (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/merge' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"exposeToParticipants":false,"sourceIds":["#121","#124"],"targetId":"#120"}'
```

## Full-text search over items and comments (desk:read)

`GET /api/desk/v1/search`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string | yes |  |
| `limit` | query | integer |  | (max 50) |

### Responses

- **200** Hits (`application/json`)

Fields of the 200 answer:

- `items` (array of SearchHit, required)
  - `item` (ItemSummary)
    - `id` (string): Id of the item
    - `number` (integer): Number of the item
    - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
    - `spaceId` (string): Space of the item
    - `status` (string): Status key
    - `title` (string): Title
    - `typeId` (string): Type of the item
  - `rank` (number): Relevance (higher is better)
  - `snippet` (string): Matching text with the hits marked

Example 200 answer:

```json
{
  "items": [
    {
      "item": {
        "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
        "number": 1,
        "phase": "active",
        "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
        "status": "in_bearbeitung",
        "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
      },
      "rank": 0.82,
      "snippet": "\u003cb\u003eWLAN\u003c/b\u003e in den Gästezimmern 2. OG fällt immer wieder aus"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/search?q=string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get an item (desk:read)

`GET /api/desk/v1/items/{ref}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Item (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

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

## Partially update an item (desk:write)

`PATCH /api/desk/v1/items/{ref}`

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

Present keys are applied, `null` clears. `version` (or `If-Match`) is the version the caller read: a ticket that changed since is 409 `version_conflict`. It is required unless the caller is an automation (a flow or a desk automation); a missing version is 400 `invalid` (`field: version`) – people, API keys, OAuth clients and the assistant always send it, so nobody overwrites a change they did not see. An automation that sends none changes the ticket as it is; one that sends a version is checked like everyone else. Status changes use `/transition`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `version` (integer): The version the caller read; required unless the caller is an automation (a flow or a desk automation); a missing version is 400 `invalid`.

Example:

```json
{
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d03"
  ],
  "priority": "kritisch",
  "version": 6
}
```

### Responses

- **200** Updated (`application/json`)
- **400** `invalid` with `field: version`: the caller is not an automation and sent no version (also: an invalid body) (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/items/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"labelIds":["9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01","9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02","9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d03"],"priority":"kritisch","version":6}'
```

## Change the status along the workflow (desk:write)

`POST /api/desk/v1/items/{ref}/transition`

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

`version` is the version the caller read: a ticket that changed since is 409 `version_conflict`. It is required unless the caller is an automation (a flow or a desk automation); a missing version is 400 `invalid` (`field: version`) – people, API keys, OAuth clients and the assistant always send it. An automation that sends none moves the ticket as it is; one that sends a version is checked like everyone else.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `status` (string, required): Target status key
- `comment` (string): Comment written with the change
- `commentVisibility` (string): Visibility of the comment (default internal) (one of `internal`, `public`)
- `fields` (ItemInput)
  - `assignees` (array of object): People working on the item (the whole list)
    - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
    - `userRef` (string): Login (e-mail) of the person
  - `categoryId` (string, nullable): Category of the item
  - `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
  - `contact` (Ref | null): Masterdata contact person of the item (null clears)
  - `customFields` (object): Merged; null removes a value
  - `customer` (Ref | null): Masterdata customer of the item (null clears)
  - `dedupeKey` (string): Create only; repeated deliveries return the existing item
  - `description` (string): Markdown
  - `dueAt` (string (date-time), nullable): Due date
  - `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
  - `estimateMinutes` (integer, nullable): Estimate in minutes
  - `followUpAt` (string (date-time), nullable): When to follow up
  - `impact` (string, nullable): Impact key of the priority matrix
  - `kbWorthy` (boolean): Candidate for the knowledge base once resolved
  - `labelIds` (array of string): Labels of the item (ids; the whole list)
  - `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
  - `priority` (string, nullable): Priority key
  - `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
  - `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
  - `rank` (string): Board order (base-36 fraction)
  - `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
  - `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
  - `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
  - `spaceId` (string): Create only
  - `startOn` (string (date), nullable): Start date
  - `status` (string): Create only
  - `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
  - `teams` (array of object): Teams of the item (the whole list)
    - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
    - `teamId` (string): Id of the team
  - `title` (string): Title of the item (max length 500)
  - `typeId` (string): Create only
  - `urgency` (string, nullable): Urgency key of the priority matrix
  - `weight` (integer, nullable): Weight of the item
- `version` (integer): The version the caller read (a ticket changed since is 409 `version_conflict`); required unless the caller is an automation (a flow or a desk automation); a missing version is 400 `invalid`.

Example:

```json
{
  "comment": "Können Sie bitte kurz prüfen, ob die Gäste in den Zimmern 201 bis 212 wieder stabil verbunden sind?",
  "commentVisibility": "public",
  "status": "wartet_kunde",
  "version": 6
}
```

### Responses

- **200** Updated (`application/json`)
- **400** `invalid` with `field: version`: the caller is not an automation and sent no version (also: no `status`, an invalid body) (`application/json`)
- **409** Error (`application/json`)
- **422** transition_denied, same_status, comment_required or missing_fields (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/transition' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Können Sie bitte kurz prüfen, ob die Gäste in den Zimmern 201 bis 212 wieder stabil verbunden sind?","commentVisibility":"public","status":"wartet_kunde","version":6}'
```

## Preview moving an item to another space and/or type (desk:read)

`GET /api/desk/v1/items/{ref}/move-preview`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `spaceId` | query | string |  |  |
| `typeId` | query | string |  |  |
| `status` | query | string |  |  |
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Plan (`application/json`)

Fields of the 200 answer:

- `confidential` (boolean): The item is confidential after the move
- `droppedLabels` (array of string): Labels the item loses with the move
- `fromStatus` (string): Current status
- `hiddenFields` (array of string): Kept but not shown by the target type
- `missingFields` (array of string): Required fields of the target type that are empty
- `spaceId` (string): Target space
- `statusMapped` (boolean): The status was mapped to another one of the target workflow
- `toStatus` (string): Status in the target workflow
- `typeId` (string): Target type

Example 200 answer:

```json
{
  "confidential": false,
  "droppedLabels": [],
  "fromStatus": "in_bearbeitung",
  "hiddenFields": [
    "cf.abschlussgrund"
  ],
  "missingFields": [],
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "statusMapped": false,
  "toStatus": "in_bearbeitung",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f03"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/items/string/move-preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Move an item to another space and/or type (service desk ↔ development) (desk:write)

`POST /api/desk/v1/items/{ref}/move`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `version` (integer, required): Current version of the item
- `fields` (ItemInput)
  - `assignees` (array of object): People working on the item (the whole list)
    - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
    - `userRef` (string): Login (e-mail) of the person
  - `categoryId` (string, nullable): Category of the item
  - `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
  - `contact` (Ref | null): Masterdata contact person of the item (null clears)
  - `customFields` (object): Merged; null removes a value
  - `customer` (Ref | null): Masterdata customer of the item (null clears)
  - `dedupeKey` (string): Create only; repeated deliveries return the existing item
  - `description` (string): Markdown
  - `dueAt` (string (date-time), nullable): Due date
  - `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
  - `estimateMinutes` (integer, nullable): Estimate in minutes
  - `followUpAt` (string (date-time), nullable): When to follow up
  - `impact` (string, nullable): Impact key of the priority matrix
  - `kbWorthy` (boolean): Candidate for the knowledge base once resolved
  - `labelIds` (array of string): Labels of the item (ids; the whole list)
  - `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
  - `priority` (string, nullable): Priority key
  - `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
  - `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
  - `rank` (string): Board order (base-36 fraction)
  - `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
  - `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
  - `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
  - `spaceId` (string): Create only
  - `startOn` (string (date), nullable): Start date
  - `status` (string): Create only
  - `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
  - `teams` (array of object): Teams of the item (the whole list)
    - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
    - `teamId` (string): Id of the team
  - `title` (string): Title of the item (max length 500)
  - `typeId` (string): Create only
  - `urgency` (string, nullable): Urgency key of the priority matrix
  - `weight` (integer, nullable): Weight of the item
- `spaceId` (string): Target space (empty: keep)
- `status` (string): Overrides the phase-based mapping
- `typeId` (string): Target type (empty: keep)

Example:

```json
{
  "spaceId": "SUP",
  "status": "in_bearbeitung",
  "typeId": "problem",
  "version": 6
}
```

### Responses

- **200** Moved (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"spaceId":"SUP","status":"in_bearbeitung","typeId":"problem","version":6}'
```

## Merge this item into another one (desk:write)

`POST /api/desk/v1/items/{ref}/merge`

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

The agent role on both is needed; a merged or converted ticket is refused (422 `merge`, 409 `converted`), and so is a target below this item (422 `hierarchy`). Several tickets at once: `POST /items/merge`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `targetId` (string, required)
- `version` (integer, required)

Example:

```json
{
  "targetId": "#1",
  "version": 2
}
```

### Responses

- **200** The target item (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/merge' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"targetId":"#1","version":2}'
```

## Create a new item from this one and move selected entries to it (desk:write)

`POST /api/desk/v1/items/{ref}/split`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `title` (string, required)
- `entryIds` (array of string)
- `link` (boolean)
- `typeId` (string)

Example:

```json
{
  "entryIds": [
    "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d05"
  ],
  "link": true,
  "title": "Gäste-WLAN im Restaurant langsam",
  "typeId": "stoerung"
}
```

### Responses

- **201** The new item (`application/json`)

Fields of the 201 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/split' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entryIds":["1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d05"],"link":true,"title":"Gäste-WLAN im Restaurant langsam","typeId":"stoerung"}'
```

## List the handoffs and conversions of a ticket (desk:read; who sees the ticket)

`GET /api/desk/v1/items/{ref}/handoffs`

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

Both directions (`role` origin: this ticket was handed over or converted; receiver: it was received), newest first, with the cached state of the counterpart (`counterpartRef`, `counterpartStage`, `counterpartStatusName`), the delivery state (`syncState` pending/confirmed/failed, `lastError`) and the hand-back note. The counterpart's title is read from its own module (404 there: only the cached ref and state).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Handoffs (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Handoff, required)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row

Example 200 answer:

```json
{
  "items": [
    {
      "attempts": 1,
      "counterpartCheckedAt": "2026-11-16T10:02:00Z",
      "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "counterpartContainerKey": "APP",
      "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
      "counterpartModule": "forge",
      "counterpartRef": "APP-24",
      "counterpartStage": "active",
      "counterpartStatusKey": "in_arbeit",
      "counterpartStatusName": "In Arbeit",
      "createdAt": "2026-11-13T09:10:00Z",
      "createdByName": "Sophie Huber",
      "createdByRef": "sophie.huber@muster-it.example",
      "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
      "itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
      "kind": "handoff",
      "role": "origin",
      "state": "open",
      "syncState": "confirmed",
      "updatedAt": "2026-11-16T10:02:00Z",
      "version": 3
    }
  ]
}
```

### Example request

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

## Hand a ticket over to a desk space or a forge project as a new linked item (desk:write; agent in the ticket's space)

`POST /api/desk/v1/items/{ref}/handoffs`

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

Header `Idempotency-Key` is required (400 without): the handoff id is derived from the ticket and the key, so a
retry answers the same handoff. The ticket stays as it is; the new item is linked through the handoff (both
histories: `handed_off` here, `handoff_received` there; `desk.handoff.sent` / `.received`). Empty title,
description and priority are the ticket's; a confidential ticket gives a confidential item with its full content.
`target.module` desk: a ticket in the space `target.container` (key; the actor needs `desk:write` and the agent role
there, 403; type by key else the space's default, status by key) in one transaction, the automations of `desk.item.handoff_received` (a conversion: `desk.item.converted_from`) run;
201. `target.module` forge: project key `target.container`; forge checks the person's forge permissions. Title and
description are scrubbed of customer data first (customer name and number, contact, requester and participant
names → „[Kunde]“ / „[Kontakt]“, e-mail addresses → „[E-Mail]“). 201 once forge created the item; 202 with the
pending handoff while forge cannot be reached (retried every 30 s, backing off to an hour, failed after 24 hours with
a system entry „Übergabe an … fehlgeschlagen: …“); a refusal by forge is 422 `handoff_refused` (same entry). Without
forge configured 503 `forge_unavailable` (`forgeEnabled` in the bootstrap). A converted ticket is 409 `converted`,
a pending conversion 409 `conversion_pending`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `target` (HandoffTarget, required)
  - `container` (string, required): Desk space key or forge project key
  - `module` (string, required): Module of the target (one of `desk`, `forge`)
  - `statusKey` (string): Status key of the new item
  - `typeKey` (string): Type key of the new item
- `description` (string): Markdown
- `priority` (string): Priority key (desk target) or label (forge target)
- `title` (string)

Example:

```json
{
  "description": "Im Kundenportal im Browser sind die Tickets richtig als gelöst markiert, in der App stehen sie tagelang unter „Offen“.",
  "priority": "priority::mittel",
  "target": {
    "container": "APP",
    "module": "forge",
    "typeKey": "fehler"
  },
  "title": "App zeigt gelöste Tickets weiterhin als offen"
}
```

### Responses

- **201** Handed over (`application/json`)
- **202** Pending (forge not reached yet) (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `handoff` (Handoff): Desk's side of a handoff or conversion (table `handoffs`).
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `item` (Item)
- `notes` (array of string): What the receiver did not take over

Example 201 answer:

```json
{
  "handoff": {
    "attempts": 1,
    "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "counterpartContainerKey": "APP",
    "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
    "counterpartModule": "forge",
    "counterpartRef": "APP-24",
    "counterpartStage": "new",
    "counterpartStatusKey": "offen",
    "counterpartStatusName": "Offen",
    "createdAt": "2026-11-13T09:10:00Z",
    "createdByName": "Sophie Huber",
    "createdByRef": "sophie.huber@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
    "itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
    "kind": "handoff",
    "role": "origin",
    "state": "open",
    "syncState": "confirmed",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 2
  },
  "item": {
    "createdAt": "2026-11-13T08:20:00Z",
    "customer": {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
      "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
    },
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
    "number": 37,
    "phase": "waiting",
    "priority": "normal",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "status": "wartet_dritte",
    "title": "App zeigt gelöste Tickets weiterhin als offen",
    "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 4
  },
  "notes": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/handoffs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"description":"Im Kundenportal im Browser sind die Tickets richtig als gelöst markiert, in der App stehen sie tagelang unter „Offen“.","priority":"priority::mittel","target":{"container":"APP","module":"forge","typeKey":"fehler"},"title":"App zeigt gelöste Tickets weiterhin als offen"}'
```

## Hand a received ticket back (desk:write; agent in the ticket's space)

`POST /api/desk/v1/items/{ref}/handoffs/{handoffId}/return`

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

Receiver side: the received handoff of this ticket (open or closed; otherwise 409 `handoff_state`) is marked handed
back with the note (at most 2000 characters). The space's `settings.handoff.receiverOnReturn` applies as a system
move ignoring transitions and required fields (default `close`: its `status` when the workflow has it, else the
closed status; `keep`: nothing), reason „Zurückgegeben: <Notiz>“; history `handed_back`, `desk.handoff.returned`,
the automations of `desk.item.handed_back`. A desk origin learns it in the same transaction (system entry with the note,
`originOnReturn` of its space – default none –, history `handback_received`, the automations of `desk.item.handback_received`); forge
learns it from desk's feed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `handoffId` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `note` (string): (max length 2000)

Example:

```json
{
  "note": "Kein Fehler: Die Kundin nutzte eine alte Version der App, nach dem Update stimmt die Anzeige."
}
```

### Responses

- **200** The handed-back row (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `attempts` (integer): Delivery attempts so far
- `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
- `counterpartContainerId` (string (uuid)): Space or project id of the other side
- `counterpartContainerKey` (string): Space or project key of the other side
- `counterpartItemId` (string (uuid)): Item id of the other side
- `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
- `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
- `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
- `counterpartStatusKey` (string): Last known status key of the other side's item
- `counterpartStatusName` (string): Last known status name of the other side's item
- `createdAt` (string (date-time)): When the handoff was started
- `createdByName` (string): Name of who started the handoff
- `createdByRef` (string): Login (e-mail) of who started the handoff
- `id` (string (uuid)): Id of the handoff
- `itemId` (string (uuid)): Desk item of this side
- `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
- `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
- `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
- `returnNote` (string): Note given when the item was handed back
- `returnedAt` (string (date-time)): When the item was handed back
- `returnedByName` (string): Name of who handed it back
- `returnedByRef` (string): Login (e-mail) of who handed it back
- `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
- `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
- `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
- `updatedAt` (string (date-time)): When the handoff row last changed
- `version` (integer): Version of the handoff row

Example 200 answer:

```json
{
  "attempts": 1,
  "counterpartCheckedAt": "2026-11-16T10:02:00Z",
  "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "counterpartContainerKey": "APP",
  "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
  "counterpartModule": "forge",
  "counterpartRef": "APP-24",
  "counterpartStage": "active",
  "counterpartStatusKey": "in_arbeit",
  "counterpartStatusName": "In Arbeit",
  "createdAt": "2026-11-13T09:10:00Z",
  "createdByName": "Sophie Huber",
  "createdByRef": "sophie.huber@muster-it.example",
  "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
  "itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
  "kind": "handoff",
  "role": "origin",
  "state": "open",
  "syncState": "confirmed",
  "updatedAt": "2026-11-16T10:02:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/handoffs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/return' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Kein Fehler: Die Kundin nutzte eine alte Version der App, nach dem Update stimmt die Anzeige."}'
```

## Convert a ticket to another desk space or to a forge project (desk:write; agent in the ticket's space)

`POST /api/desk/v1/items/{ref}/convert`

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

Header `Idempotency-Key` and the ticket's `version` are required. `target.module` desk: a move (`POST /items/{ref}/move`
semantics: same ticket and number, 200). `target.module` forge: the conversion contract (version 1) carries title,
description, type, status, custom fields by key, priority, dates, estimate, labels, assignees, watchers, the
reporter, the agents' comments with author, time, kind and visibility, uploaded files (same DMS documents), links and
the checklist (both listed in forge's note) and notes on what stays here (customer, contacts, mails, the requester's
messages, time, project, parent). Free text is scrubbed of customer data like a handoff; a confidential ticket goes
with full content and `confidential`. While forge has not confirmed, edits are 409 `conversion_pending`; once it has,
the ticket is the read-only tombstone (`convertedTo`, closed; a forwarding stub when it has requesters or people in
copy) with history `converted`. 201 confirmed, 202 pending (retried like a handoff), 422 `handoff_refused`,
409 `has_children` (sub-tickets), `converted`, `version_conflict`; 503 `forge_unavailable`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `target` (HandoffTarget, required)
  - `container` (string, required): Desk space key or forge project key
  - `module` (string, required): Module of the target (one of `desk`, `forge`)
  - `statusKey` (string): Status key of the new item
  - `typeKey` (string): Type key of the new item
- `version` (integer, required)

Example:

```json
{
  "target": {
    "container": "SUP",
    "module": "desk",
    "typeKey": "problem"
  },
  "version": 6
}
```

### Responses

- **200** Moved within desk (`application/json`)
- **201** Converted (`application/json`)
- **202** Pending (forge not reached yet) (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `handoff` (Handoff): Desk's side of a handoff or conversion (table `handoffs`).
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `item` (Item)
- `notes` (array of string): What the receiver did not take over

Example 201 answer:

```json
{
  "handoff": {
    "attempts": 1,
    "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "counterpartContainerKey": "APP",
    "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
    "counterpartModule": "forge",
    "counterpartRef": "APP-24",
    "counterpartStage": "new",
    "counterpartStatusKey": "offen",
    "counterpartStatusName": "Offen",
    "createdAt": "2026-11-13T09:10:00Z",
    "createdByName": "Sophie Huber",
    "createdByRef": "sophie.huber@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
    "itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
    "kind": "handoff",
    "role": "origin",
    "state": "open",
    "syncState": "confirmed",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 2
  },
  "item": {
    "createdAt": "2026-11-13T08:20:00Z",
    "customer": {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
      "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
    },
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
    "number": 37,
    "phase": "waiting",
    "priority": "normal",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "status": "wartet_dritte",
    "title": "App zeigt gelöste Tickets weiterhin als offen",
    "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 4
  },
  "notes": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"target":{"container":"SUP","module":"desk","typeKey":"problem"},"version":6}'
```

## Put a person and/or a team on a ticket (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/assign`

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

`user` (e-mail) in `role` (default: the tenant's default assignee role) and/or `team` (key or id) as `teamRole` (`collaborating` by default, or `responsible`). A person in a primary role replaces the current primary person; a responsible team replaces the current responsible team. `strategy: leastOpen` picks the member of `team` working on the fewest open tickets instead of `user`. At least a person or a team (400 `user`); an unknown team is 400 `team`. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `role` (string): Assignee role of the person (default: the tenant's default role)
- `strategy` (string): user (default) or leastOpen: the member of the team with the fewest open tickets (one of `user`, `leastOpen`)
- `team` (string): Key or id of a team
- `teamRole` (string): Role of the team (default collaborating) (one of `responsible`, `collaborating`)
- `user` (string): E-mail of the person; with strategy leastOpen it is chosen from the team instead

Example:

```json
{
  "role": "assignee",
  "user": "jonas.bauer@muster-it.example"
}
```

### Responses

- **200** The ticket after the step and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/assign' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"role":"assignee","user":"jonas.bauer@muster-it.example"}'
```

## Take people off a ticket (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/unassign`

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

Removes the assignees in `role`; without `role` everyone who works on the ticket (observers stay). Teams are not touched. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `role` (string): Assignee role to remove; empty: everyone working on the ticket (observers stay)

Example:

```json
{
  "role": "watcher"
}
```

### Responses

- **200** The ticket after the step and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/unassign' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"role":"watcher"}'
```

## Add a label to a ticket by its name (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/labels/add`

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

`label` is the name of a label of the ticket's space, else of a tenant-wide one (any case; an unknown or archived one is 400 `label`). A label the ticket already has changes nothing. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `label` (string, required): Name of a label of the ticket's space or of a tenant-wide one

Example:

```json
{
  "label": "vor-ort"
}
```

### Responses

- **200** The ticket after the step and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/labels/add' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"label":"vor-ort"}'
```

## Remove a label from a ticket by its name (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/labels/remove`

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

`label` is the name of a label of the ticket's space, else of a tenant-wide one (an unknown one is 400 `label`). A label the ticket does not have changes nothing. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `label` (string, required): Name of a label of the ticket's space or of a tenant-wide one

Example:

```json
{
  "label": "vor-ort"
}
```

### Responses

- **200** The ticket after the step and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/labels/remove' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"label":"vor-ort"}'
```

## Set the due date of a ticket relative to now (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/due`

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

`in` is a duration (`90m`, `4h`, `2d`; days are 24 hours; else 400 `in`). `businessHours: true` counts it in the tenant's default service calendar (wall-clock time when there is none). One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `in` (string, required): Duration from now: 90m, 4h, 2d
- `businessHours` (boolean): Count the duration in the tenant's default service calendar

Example:

```json
{
  "businessHours": true,
  "in": "4h"
}
```

### Responses

- **200** The ticket after the step and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/due' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"businessHours":true,"in":"4h"}'
```

## Set the follow-up of a ticket relative to now (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/follow-up`

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

`in` is a duration (`90m`, `4h`, `2d`; else 400 `in`), counted in wall-clock time. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `in` (string, required): Duration from now: 90m, 4h, 2d

Example:

```json
{
  "in": "2d"
}
```

### Responses

- **200** The ticket after the step and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/follow-up' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"in":"2d"}'
```

## Comment on the tickets linked to a ticket (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/linked-comments`

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

Adds `body` as a comment (`visibility` internal by default; a public one is mailed to that ticket's requesters) to every ticket linked to this one – only links of `linkType` and `direction` (`outgoing`: this ticket is the link's source, `incoming`: its target, `any`: both) when set. Each linked ticket gets it once; merged tickets, tombstones, tickets the caller cannot comment on and – for an automation of a space – tickets of other spaces are left out and counted in `skipped`. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `body` (string, required): The comment
- `direction` (string): Only links from this ticket (outgoing) or to it (incoming); any (default): both (one of `any`, `outgoing`, `incoming`)
- `linkType` (string): Only links of this type (key of a linkType entry)
- `visibility` (string): internal by default (one of `internal`, `public`)

Example:

```json
{
  "body": "Ursache gefunden: Der PoE-Switch im 2. OG wird heute getauscht.",
  "direction": "incoming",
  "linkType": "caused_by",
  "visibility": "internal"
}
```

### Responses

- **200** How many linked tickets got the comment (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `commented` (integer, required): Linked tickets that got the comment
- `skipped` (integer, required): Linked tickets left out (merged, read-only, not commentable for the caller, outside an automation's space)

Example 200 answer:

```json
{
  "commented": 2,
  "skipped": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/linked-comments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Ursache gefunden: Der PoE-Switch im 2. OG wird heute getauscht.","direction":"incoming","linkType":"caused_by","visibility":"internal"}'
```

## Direct children (desk:read)

`GET /api/desk/v1/items/{ref}/children`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Items (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required)

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "paul.schmid@muster-it.example"
        }
      ],
      "createdAt": "2026-11-02T07:30:00Z",
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "number": 58,
      "parentId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d09",
      "phase": "active",
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "status": "in_arbeit",
      "title": "Probeimport und Prüfung",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07",
      "updatedAt": "2026-11-12T09:00:00Z",
      "version": 4
    }
  ]
}
```

### Example request

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

# Activity

## Comments and internal notes (desk:read)

`GET /api/desk/v1/items/{ref}/entries`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Rows per page (default 200) (default `200`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page (keyset, bound to the list and its order); anything else is 400 invalid with `field: cursor`. |
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Entries (`application/json`)

Fields of the 200 answer:

- `items` (array of Entry, required)
  - `aiGenerated` (boolean): The text was written with AI help
  - `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
  - `authorName` (string): Name of the author
  - `authorRef` (string): Login (e-mail) of the author
  - `automated` (boolean): Written by a rule or service; never counts as a first response
  - `body` (string): Markdown
  - `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
  - `createdAt` (string (date-time)): When the entry was written
  - `editedAt` (string (date-time)): When the entry was last edited
  - `id` (string): Id of the entry
  - `itemId` (string): Item the entry belongs to
  - `kind` (string): comment, email_in, email_out or system
  - `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
    - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
    - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
    - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
    - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
    - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
  - `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
  - `movedFromId` (string): Item the entry was moved from
  - `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page.

Example 200 answer:

```json
{
  "items": [
    {
      "aiGenerated": false,
      "authorKind": "agent",
      "authorName": "Sophie Huber",
      "authorRef": "sophie.huber@muster-it.example",
      "automated": false,
      "body": "Guten Morgen Frau Stadler, danke für die Meldung. Wir prüfen die Access Points im 2. OG per Fernzugriff und melden uns bis 10 Uhr.",
      "channel": "ui",
      "createdAt": "2026-11-17T07:20:00Z",
      "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d02",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "kind": "email_out",
      "visibility": "public"
    },
    {
      "aiGenerated": false,
      "authorKind": "agent",
      "authorName": "Lukas Wimmer",
      "authorRef": "lukas.wimmer@muster-it.example",
      "automated": false,
      "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten).",
      "channel": "ui",
      "createdAt": "2026-11-17T08:40:00Z",
      "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "kind": "comment",
      "visibility": "internal"
    }
  ],
  "nextCursor": "eyJpZCI6IjFiOGM5ZDBlIn0"
}
```

### Example request

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

## Add a comment (public) or note (internal) (desk:write, reporter role)

`POST /api/desk/v1/items/{ref}/entries`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `body` (string, required): Markdown
- `aiGenerated` (boolean)
- `visibility` (string): (one of `internal`, `public`)

Example:

```json
{
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten).",
  "visibility": "internal"
}
```

### Responses

- **201** Created. kind is email_out when a public comment was mailed to the customer; mailNote is set only for a public comment that was not mailed (never for internal notes) (`application/json`)

Fields of the 201 answer:

- `aiGenerated` (boolean): The text was written with AI help
- `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
- `authorName` (string): Name of the author
- `authorRef` (string): Login (e-mail) of the author
- `automated` (boolean): Written by a rule or service; never counts as a first response
- `body` (string): Markdown
- `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
- `createdAt` (string (date-time)): When the entry was written
- `editedAt` (string (date-time)): When the entry was last edited
- `id` (string): Id of the entry
- `itemId` (string): Item the entry belongs to
- `kind` (string): comment, email_in, email_out or system
- `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
  - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
  - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
  - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
  - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
  - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
- `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
- `movedFromId` (string): Item the entry was moved from
- `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)

Example 201 answer:

```json
{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/entries' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten).","visibility":"internal"}'
```

## Edit an entry (desk:write, author or maintainer)

`PATCH /api/desk/v1/items/{ref}/entries/{entryId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `entryId` | path | string | yes |  |

### Request body

`application/json` (required)

- `body` (string, required)

Example:

```json
{
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil."
}
```

### Responses

- **200** Updated (`application/json`)

Fields of the 200 answer:

- `aiGenerated` (boolean): The text was written with AI help
- `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
- `authorName` (string): Name of the author
- `authorRef` (string): Login (e-mail) of the author
- `automated` (boolean): Written by a rule or service; never counts as a first response
- `body` (string): Markdown
- `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
- `createdAt` (string (date-time)): When the entry was written
- `editedAt` (string (date-time)): When the entry was last edited
- `id` (string): Id of the entry
- `itemId` (string): Item the entry belongs to
- `kind` (string): comment, email_in, email_out or system
- `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
  - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
  - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
  - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
  - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
  - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
- `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
- `movedFromId` (string): Item the entry was moved from
- `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)

Example 200 answer:

```json
{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil."}'
```

## Move a wrongly assigned entry to another item (desk:write)

`POST /api/desk/v1/items/{ref}/entries/{entryId}/move`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `entryId` | path | string | yes |  |

### Request body

`application/json` (required)

- `targetId` (string, required)

Example:

```json
{
  "targetId": "#4"
}
```

### Responses

- **200** Moved (`application/json`)

Fields of the 200 answer:

- `aiGenerated` (boolean): The text was written with AI help
- `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
- `authorName` (string): Name of the author
- `authorRef` (string): Login (e-mail) of the author
- `automated` (boolean): Written by a rule or service; never counts as a first response
- `body` (string): Markdown
- `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
- `createdAt` (string (date-time)): When the entry was written
- `editedAt` (string (date-time)): When the entry was last edited
- `id` (string): Id of the entry
- `itemId` (string): Item the entry belongs to
- `kind` (string): comment, email_in, email_out or system
- `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
  - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
  - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
  - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
  - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
  - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
- `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
- `movedFromId` (string): Item the entry was moved from
- `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)

Example 200 answer:

```json
{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"targetId":"#4"}'
```

## Complete change history (desk:read)

`GET /api/desk/v1/items/{ref}/events`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Rows per page (default 200) (default `200`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page (keyset, bound to the list and its order); anything else is 400 invalid with `field: cursor`. |
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Events (`application/json`)

Fields of the 200 answer:

- `items` (array of Event, required)
  - `action` (string): What happened (created, updated, transitioned, …)
  - `actorName` (string): Name of who made the change
  - `actorRef` (string): Login (e-mail) of who made the change
  - `changes` (array of object): Changed fields
    - `field` (string): Changed field
    - `from` (any): Value before
    - `to` (any): Value after
  - `createdAt` (string (date-time)): When the change happened
  - `id` (string): Id of the history entry
  - `itemId` (string): Item the change belongs to
  - `reason` (string): Why the change was made
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page.

Example 200 answer:

```json
{
  "items": [
    {
      "action": "transitioned",
      "actorName": "Sophie Huber",
      "actorRef": "sophie.huber@muster-it.example",
      "changes": [
        {
          "field": "status",
          "from": "neu",
          "to": "in_bearbeitung"
        }
      ],
      "createdAt": "2026-11-17T07:21:00Z",
      "id": "7c4d5e6f-8a9b-4c0d-9e1f-2a3b4c5d6e01",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "reason": ""
    },
    {
      "action": "updated",
      "actorName": "Lukas Wimmer",
      "actorRef": "lukas.wimmer@muster-it.example",
      "changes": [
        {
          "field": "labelIds",
          "from": [
            "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
          ],
          "to": [
            "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02",
            "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01"
          ]
        }
      ],
      "createdAt": "2026-11-17T08:46:00Z",
      "id": "7c4d5e6f-8a9b-4c0d-9e1f-2a3b4c5d6e02",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "reason": ""
    }
  ],
  "nextCursor": "eyJpZCI6IjdjNGQ1ZTZmIn0"
}
```

### Example request

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

## Linked items (desk:read)

`GET /api/desk/v1/items/{ref}/links`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Links (`application/json`)

Fields of the 200 answer:

- `items` (array of Link, required)
  - `createdAt` (string (date-time)): When the link was made
  - `createdBy` (string): Login (e-mail) of who linked
  - `id` (string): Id of the link
  - `other` (ItemSummary)
    - `id` (string): Id of the item
    - `number` (integer): Number of the item
    - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
    - `spaceId` (string): Space of the item
    - `status` (string): Status key
    - `title` (string): Title
    - `typeId` (string): Type of the item
  - `outgoing` (boolean): The requested item is the source of the link
  - `sourceId` (string): Item the link starts from
  - `targetId` (string): Item the link points to
  - `type` (string): Key of a linkType entry

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-17T08:45:00Z",
      "createdBy": "lukas.wimmer@muster-it.example",
      "id": "5f2a3b4c-6d7e-4f8a-9b0c-2d3e4f5a6b01",
      "other": {
        "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c04",
        "number": 4,
        "phase": "new",
        "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
        "status": "neu",
        "title": "Firewall-Regeln für das Gäste-WLAN prüfen",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02"
      },
      "outgoing": true,
      "sourceId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "targetId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c04",
      "type": "relates"
    }
  ]
}
```

### Example request

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

## Link to another item (desk:write)

`POST /api/desk/v1/items/{ref}/links`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `targetId` (string, required)
- `type` (string, required): Key of a linkType entry (bootstrap enums)

Example:

```json
{
  "targetId": "#4",
  "type": "relates"
}
```

### Responses

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

Fields of the 201 answer:

- `createdAt` (string (date-time)): When the link was made
- `createdBy` (string): Login (e-mail) of who linked
- `id` (string): Id of the link
- `other` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `outgoing` (boolean): The requested item is the source of the link
- `sourceId` (string): Item the link starts from
- `targetId` (string): Item the link points to
- `type` (string): Key of a linkType entry

Example 201 answer:

```json
{
  "createdAt": "2026-11-17T08:45:00Z",
  "createdBy": "lukas.wimmer@muster-it.example",
  "id": "5f2a3b4c-6d7e-4f8a-9b0c-2d3e4f5a6b01",
  "other": {
    "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c04",
    "number": 4,
    "phase": "new",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "status": "neu",
    "title": "Firewall-Regeln für das Gäste-WLAN prüfen",
    "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02"
  },
  "outgoing": true,
  "sourceId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "targetId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c04",
  "type": "relates"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/links' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"targetId":"#4","type":"relates"}'
```

## Remove a link (desk:write)

`DELETE /api/desk/v1/items/{ref}/links/{linkId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `linkId` | path | string | yes |  |

### Responses

- **204** Deleted

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/items/string/links/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Checklist (desk:read)

`GET /api/desk/v1/items/{ref}/checklist`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Checklist (`application/json`)

Fields of the 200 answer:

- `items` (array of ChecklistItem, required)
  - `done` (boolean): Whether it is ticked
  - `doneAt` (string (date-time)): When it was ticked
  - `doneBy` (string): Login (e-mail) of who ticked it
  - `id` (string): Id of the checklist item
  - `itemId` (string): Item the checklist belongs to
  - `sortOrder` (integer): Position in lists (ascending)
  - `text` (string): Text of the checklist item

Example 200 answer:

```json
{
  "items": [
    {
      "done": true,
      "doneAt": "2026-11-17T12:30:00Z",
      "doneBy": "lukas.wimmer@muster-it.example",
      "id": "4e1f2a3b-5c6d-4e7f-8a9b-1c2d3e4f5a01",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "sortOrder": 1,
      "text": "Ersatz-Switch aus dem Lager mitnehmen"
    },
    {
      "done": false,
      "id": "4e1f2a3b-5c6d-4e7f-8a9b-1c2d3e4f5a02",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "sortOrder": 2,
      "text": "Roaming in den Zimmern 201–212 testen"
    }
  ]
}
```

### Example request

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

## Add a checklist item (desk:write)

`POST /api/desk/v1/items/{ref}/checklist`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `text` (string, required)

Example:

```json
{
  "text": "Roaming in den Zimmern 201–212 testen"
}
```

### Responses

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

Fields of the 201 answer:

- `done` (boolean): Whether it is ticked
- `doneAt` (string (date-time)): When it was ticked
- `doneBy` (string): Login (e-mail) of who ticked it
- `id` (string): Id of the checklist item
- `itemId` (string): Item the checklist belongs to
- `sortOrder` (integer): Position in lists (ascending)
- `text` (string): Text of the checklist item

Example 201 answer:

```json
{
  "done": true,
  "doneAt": "2026-11-17T12:30:00Z",
  "doneBy": "lukas.wimmer@muster-it.example",
  "id": "4e1f2a3b-5c6d-4e7f-8a9b-1c2d3e4f5a01",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "sortOrder": 1,
  "text": "Ersatz-Switch aus dem Lager mitnehmen"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/checklist' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Roaming in den Zimmern 201–212 testen"}'
```

## Delete a checklist item (desk:write)

`DELETE /api/desk/v1/items/{ref}/checklist/{checkId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `checkId` | path | string | yes |  |

### Responses

- **204** Deleted

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/items/string/checklist/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Update a checklist item (desk:write)

`PATCH /api/desk/v1/items/{ref}/checklist/{checkId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `checkId` | path | string | yes |  |

### Request body

`application/json` (required)

- `done` (boolean)
- `sortOrder` (integer)
- `text` (string)

Example:

```json
{
  "done": true
}
```

### Responses

- **200** Updated (`application/json`)

Fields of the 200 answer:

- `done` (boolean): Whether it is ticked
- `doneAt` (string (date-time)): When it was ticked
- `doneBy` (string): Login (e-mail) of who ticked it
- `id` (string): Id of the checklist item
- `itemId` (string): Item the checklist belongs to
- `sortOrder` (integer): Position in lists (ascending)
- `text` (string): Text of the checklist item

Example 200 answer:

```json
{
  "done": true,
  "doneAt": "2026-11-17T12:30:00Z",
  "doneBy": "lukas.wimmer@muster-it.example",
  "id": "4e1f2a3b-5c6d-4e7f-8a9b-1c2d3e4f5a01",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "sortOrder": 1,
  "text": "Ersatz-Switch aus dem Lager mitnehmen"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/items/string/checklist/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"done":true}'
```

# Time

## Active contracts of a customer for tickets (desk:write)

`GET /api/desk/v1/contracts`

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

Customer contracts of trade that run on `date` (default today), the most specific first. Empty without trade.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `customer` | query | string | yes | Masterdata address id |
| `date` | query | string (date) |  |  |

### Responses

- **200** Contracts (`application/json`)

Fields of the 200 answer:

- `items` (array of Contract, required)

Example 200 answer:

```json
{
  "items": [
    {
      "active": true,
      "customerId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
      "id": "5a7c9e1b-3d5f-4a7c-9e1b-3d5f7a9c1e01",
      "number": "WV-2026-003",
      "quota": false,
      "title": "Wartungsvertrag Netzwerk und WLAN"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/contracts?customer=string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Callbacks

## List callbacks (desk:write)

`GET /api/desk/v1/callbacks`

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

Callbacks (Rückrufe) with the total, `openMine` (the caller's open callbacks, the header badge) and
`openUnassigned` (open callbacks without a responsible person). `scope` `mine` lists the callbacks the caller is
responsible for, `unassigned` the pool of callbacks nobody is responsible for yet (`responsible` is ignored),
`all` everyone's (default). `status` is `open` (no
closed flag), `closed`, `any` (default) or a key of the value list `callbackStatus`. Sorted by desired time
(without one last), then newest (`sort=due`, default), or newest first by `created` / `updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string |  | (one of `mine`, `unassigned`, `all`; default `"all"`) |
| `status` | query | string |  | open, closed, any (default) or a callbackStatus key |
| `responsible` | query | string |  | User ref of the responsible person |
| `customerId` | query | string |  | Masterdata address id |
| `reason` | query | string |  | Key of a callbackReason entry |
| `q` | query | string |  | Phone, contact name, customer name, note or number |
| `from` | query | string (date-time) |  | Desired time from (date or RFC 3339) |
| `to` | query | string (date-time) |  | Desired time before |
| `sort` | query | string |  | (one of `due`, `created`, `updated`; default `"due"`) |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  |  |

### Responses

- **200** A page of callbacks (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Callback, required): Callbacks of the page
  - `closed` (boolean, read-only): The status carries the closed flag
  - `closedAt` (string (date-time), nullable): When the callback was closed
  - `closedBy` (string): Login (e-mail) of who closed the callback
  - `contact` (object): Masterdata contact snapshot (only with a customer)
  - `contactName` (string): Name of the person to call back
  - `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
  - `createdAt` (string (date-time)): When the callback was created
  - `createdBy` (string): Login (e-mail) of who created the callback
  - `createdByName` (string): Name of who created the callback
  - `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
  - `customer` (object): Masterdata address snapshot
  - `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
  - `desiredAt` (string (date-time), nullable): When the contact wants to be called back
  - `desiredHasTime` (boolean): false: only the day of desiredAt counts
  - `doneNote` (string): Result of the call
  - `id` (string (uuid)): Id of the callback
  - `item` (ItemSummary)
    - `id` (string): Id of the item
    - `number` (integer): Number of the item
    - `phase` (Phase)
    - `spaceId` (string): Space of the item
    - `status` (string): Status key
    - `title` (string): Title
    - `typeId` (string): Type of the item
  - `itemId` (string, nullable): The ticket it became
  - `note` (string): Note of the callback
  - `number` (integer): Per tenant
  - `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
  - `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
  - `phone` (string): Phone number to call back
  - `reason` (string): Key of a callbackReason entry, "" = none
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
  - `status` (string): Key of a callbackStatus entry
  - `updatedAt` (string (date-time)): When the callback was last changed
  - `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)
- `openMine` (integer, required): Open callbacks the caller is responsible for
- `openUnassigned` (integer, required): Open callbacks without a responsible person (the pool)
- `total` (integer, required): Number of callbacks matching the filter

Example 200 answer:

```json
{
  "items": [
    {
      "closed": false,
      "contactName": "Katrin Stadler",
      "createdAt": "2026-11-17T15:20:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "desiredAt": "2026-11-19T08:00:00Z",
      "desiredHasTime": true,
      "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
      "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
      "number": 12,
      "overdue": false,
      "phone": "+49 8652 987612",
      "reason": "callback_requested",
      "responsibleName": "Elias Gruber",
      "responsibleRef": "elias.gruber@muster-it.example",
      "status": "open",
      "updatedAt": "2026-11-17T15:20:00Z",
      "version": 1
    }
  ],
  "openMine": 1,
  "openUnassigned": 2,
  "total": 1
}
```

### Example request

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

## Create a callback (desk:write)

`POST /api/desk/v1/callbacks`

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

The status is the `callbackStatus` entry with the `default` flag unless `status` names one; the responsible
person defaults to the caller; `responsibleRef: ""` creates it without one (the pool of unassigned callbacks,
`scope=unassigned`), and nobody is notified. The responsible person gets the notification
`desk.callback_notice` unless they created it themselves. Custom fields are those of `settings.callbacks.fields`
(`customFields`, keys without `cf.`).

The note must satisfy the tenant's note rules (`settings.callbacks.note`): required, minimum length, pattern
(each 400 `invalid`, field `note`, with a message for the person) and the optional AI check (422 `note_rejected`,
the message is the hint). The AI check never blocks when the AI is unavailable. A callback created in a status
with a customer mail behaves like a status change into it (`customerMail`, see `POST /callbacks/{id}/status`).

### Request body

`application/json` (required)

- `clearDesiredAt` (boolean): Removes the desired time
- `contact` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `contactName` (string): ≤ 200 characters
- `customFields` (object): Values of the custom fields of the callback form by key
- `customer` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `desiredAt` (string (date-time)): When the contact wants to be called back
- `desiredHasTime` (boolean): desiredAt carries a time of day (false: only the date counts)
- `doneNote` (string): ≤ 10000 characters
- `note` (string): ≤ 10000 characters
- `origin` (string): Create only (ignored on change): the activity it is made from, `comms:interaction:<id>` or `comms:calendar:<id>` (400 otherwise); Arbeitsplatz › Aktivitäten „Rückruf anlegen“
- `phone` (string): Required on create; digits, a leading +, spaces and ( ) / - . (≤ 40)
- `reason` (string): Key of a callbackReason entry
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref; absent or null on create: the caller; "" = nobody (the pool of unassigned callbacks; on change it unassigns)
- `status` (string): Create only: a callbackStatus key (default: the default entry)
- `version` (integer): Required on change

Example:

```json
{
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleRef": "elias.gruber@muster-it.example"
}
```

### Responses

- **201** Created; `customerMail` is set when its status has a customer mail (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **422** note_rejected: the AI check refused the note (the message is the hint) (`application/json`)

Fields of the 201 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contact":{"id":"6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11","name":"Katrin Stadler"},"contactName":"Katrin Stadler","customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11","name":"Alpenhotel Seeblick GmbH \u0026 Co. KG"},"desiredAt":"2026-11-19T08:00:00Z","desiredHasTime":true,"note":"Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.","phone":"+49 8652 987612","reason":"callback_requested","responsibleRef":"elias.gruber@muster-it.example"}'
```

## Get a callback (desk:write)

`GET /api/desk/v1/callbacks/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Callback (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a callback and its history (desk:admin)

`DELETE /api/desk/v1/callbacks/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a callback at its version (desk:write)

`PATCH /api/desk/v1/callbacks/{id}`

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

Present keys are applied (`clearDesiredAt: true` removes the desired time); `version` is required. The status
changes through `POST /callbacks/{id}/status` (`status` here is 400). A closed callback takes only `doneNote`
(409 `callback_closed`), a converted one too (409 `converted`). A new responsible person (another than the
caller) gets the notification – also when an unassigned callback is assigned; `responsibleRef: ""` puts it back
into the pool (history and outbox `assigned`, no notification). A changed `note` is checked against the note
rules like on create (400 `invalid` on field `note`, 422 `note_rejected`); an unchanged note is not checked again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `clearDesiredAt` (boolean): Removes the desired time
- `contact` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `contactName` (string): ≤ 200 characters
- `customFields` (object): Values of the custom fields of the callback form by key
- `customer` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `desiredAt` (string (date-time)): When the contact wants to be called back
- `desiredHasTime` (boolean): desiredAt carries a time of day (false: only the date counts)
- `doneNote` (string): ≤ 10000 characters
- `note` (string): ≤ 10000 characters
- `origin` (string): Create only (ignored on change): the activity it is made from, `comms:interaction:<id>` or `comms:calendar:<id>` (400 otherwise); Arbeitsplatz › Aktivitäten „Rückruf anlegen“
- `phone` (string): Required on create; digits, a leading +, spaces and ( ) / - . (≤ 40)
- `reason` (string): Key of a callbackReason entry
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref; absent or null on create: the caller; "" = nobody (the pool of unassigned callbacks; on change it unassigns)
- `status` (string): Create only: a callbackStatus key (default: the default entry)
- `version` (integer): Required on change

Example:

```json
{
  "desiredAt": "2026-11-19T12:00:00Z",
  "responsibleRef": "",
  "version": 1
}
```

### Responses

- **200** Updated (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict, callback_closed or converted (`application/json`)
- **422** note_rejected: the AI check refused the changed note (the message is the hint) (`application/json`)

Fields of the 200 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"desiredAt":"2026-11-19T12:00:00Z","responsibleRef":"","version":1}'
```

## Set the status of a callback (desk:write)

`POST /api/desk/v1/callbacks/{id}/status`

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

Any status may follow any other (also reopening a closed one); a closed status stamps `closedAt`/`closedBy`,
an open one clears them. A converted callback keeps its status (409 `converted`). An open callback may move to
its own status again (one more try, e.g. not reached again): a new version, a history line `status_changed`
with `from` = `to` and the status's customer mail as for any move into it; a closed callback moving to its own
status is 422 `same_status`.

Customer mail: when `settings.callbacks.statusMail` ties a text to the new status, the move triggers the mail to the
callback's contact. In mode `auto` the mail is queued in the same transaction (once per move into the status;
history `customer_mail`) and the answer's `customerMail` has `mode` `auto` and no `missing`; when it could not be
sent `customerMail.missing` says why (history `customer_mail_skipped`; the status change succeeds anyway). In mode `manual` nothing is sent and
the answer's `customerMail` is the rendered draft for the client to show; send it with
`POST /callbacks/{id}/customer-mail`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `status` (string, required): Key of a callbackStatus entry
- `version` (integer, required)
- `doneNote` (string): Result of the call (≤ 10000 characters)

Example:

```json
{
  "doneNote": "Kassenanbindung besprochen; Termin vor Ort am Freitag vereinbart.",
  "status": "done",
  "version": 2
}
```

### Responses

- **200** Updated; `customerMail` is set when the new status has a customer mail (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict or converted (`application/json`)
- **422** same_status: a closed callback moved to its own status (`application/json`)

Fields of the 200 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/status' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"doneNote":"Kassenanbindung besprochen; Termin vor Ort am Freitag vereinbart.","status":"done","version":2}'
```

## Record the ticket a callback became (desk:write)

`POST /api/desk/v1/callbacks/{id}/ticket`

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

The second step of turning a callback into a ticket: the client creates the ticket (`createItem`), then links it
here. The ticket must be one the caller sees (404 otherwise). The callback gets `itemId` and `convertedAt`, moves
to the first active closed status unless it is closed already, and stays read-only except its done note. The same
ticket again answers the callback unchanged (200); another ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `itemId` (string, required): Ticket id or number
- `version` (integer, required)

Example:

```json
{
  "itemId": "#2",
  "version": 2
}
```

### Responses

- **200** Converted (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict or converted (`application/json`)

Fields of the 200 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/ticket' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"itemId":"#2","version":2}'
```

## Draft of a mail to the callback's contact (desk:write)

`GET /api/desk/v1/callbacks/{id}/customer-mail`

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

The text of the callback's current status (`settings.callbacks.statusMail`), else the first mail text, rendered
for the callback (`mode` is `manual`), with the contact's address in `to` or the reason in `missing`. The
recipient is the contact's e-mail address in masterdata. Without any mail text: 404 `no_mail_text`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Draft (`application/json`)
- **404** not_found or no_mail_text (the tenant has no mail text) (`application/json`)

Fields of the 200 answer:

- `body` (string, required): Placeholders filled
- `mode` (string, required): Mode of the status mail; the draft route always answers manual (one of `manual`, `auto`)
- `subject` (string, required): Placeholders filled
- `text` (string, required): Key of the mail text
- `textName` (string, required): Name of the mail text the draft was made from
- `to` (string, required): The contact's e-mail address; "" when there is none (see `missing`)
- `missing` (string): Why there is no recipient or no mail: `no_contact` (the callback has no contact), `no_address` (the contact is gone, inactive, blocked or has no valid address), `masterdata_unavailable` (masterdata could not be asked), `mail_unavailable` (mail is not set up). Absent when the mail can go out. (one of `no_contact`, `no_address`, `masterdata_unavailable`, `mail_unavailable`)

Example 200 answer:

```json
{
  "body": "Guten Tag Frau Stadler,\n\nwir haben heute versucht, Sie zurückzurufen, Sie aber leider nicht erreicht. Wir melden uns morgen wieder.\n\nViele Grüße\nElias Gruber",
  "mode": "manual",
  "subject": "Ihr Rückrufwunsch bei Muster IT",
  "text": "nicht-erreicht",
  "textName": "Nicht erreicht",
  "to": "katrin.stadler@alpenhotel-seeblick.example"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/customer-mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Send a mail to the callback's contact (desk:write)

`POST /api/desk/v1/callbacks/{id}/customer-mail`

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

Sends subject and body to the e-mail address of the callback's contact in masterdata at the callback's
`version` (which stays). The `Idempotency-Key` header is required (at most 200 characters, no control
characters): the same key sends and records once, a retry answers the callback without sending again. The mail
is queued through comms and noted in the history (`customer_mail`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `body` (string, required): (max length 8000)
- `subject` (string, required): (max length 200)
- `version` (integer, required)

Example:

```json
{
  "body": "Guten Tag Frau Stadler,\n\nwir haben heute versucht, Sie zurückzurufen, Sie aber leider nicht erreicht. Wir melden uns morgen wieder.\n\nViele Grüße\nElias Gruber",
  "subject": "Ihr Rückrufwunsch bei Muster IT",
  "version": 3
}
```

### Responses

- **200** Sent (`application/json`)
- **400** invalid: missing or invalid Idempotency-Key, subject or body (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict (`application/json`)
- **422** no_recipient: the contact has no usable e-mail address (no contact, gone, inactive, blocked or without address); mail_unavailable: mail (comms) is not set up for desk (`application/json`)
- **503** unavailable: masterdata is not reachable; retry with the same Idempotency-Key (`application/json`)

Fields of the 200 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/customer-mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"body":"Guten Tag Frau Stadler,\n\nwir haben heute versucht, Sie zurückzurufen, Sie aber leider nicht erreicht. Wir melden uns morgen wieder.\n\nViele Grüße\nElias Gruber","subject":"Ihr Rückrufwunsch bei Muster IT","version":3}'
```

## History of a callback, oldest first (desk:write)

`GET /api/desk/v1/callbacks/{id}/events`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** History (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of CallbackEvent, required)
  - `action` (string): `customer_mail`: a mail to the customer was queued (changes `mail` = text name, `to` = address); `customer_mail_skipped`: an automatic mail was not sent (change `reason` = why, as `CallbackMailDraft.missing`) (one of `created`, `updated`, `assigned`, `status_changed`, `converted`, `customer_mail`, `customer_mail_skipped`)
  - `actorName` (string): Name of who made the change
  - `actorRef` (string): Login (e-mail) of who made the change
  - `changes` (array of object): Changed fields; note and doneNote only say that they changed
    - `field` (string): Changed field
    - `from` (any): Value before
    - `to` (any): Value after
  - `createdAt` (string (date-time)): When the change happened
  - `id` (string): Id of the history entry

Example 200 answer:

```json
{
  "items": [
    {
      "action": "created",
      "actorName": "Sophie Huber",
      "actorRef": "sophie.huber@muster-it.example",
      "changes": [],
      "createdAt": "2026-11-17T15:20:00Z",
      "id": "6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f01"
    },
    {
      "action": "status_changed",
      "actorName": "Elias Gruber",
      "actorRef": "elias.gruber@muster-it.example",
      "changes": [
        {
          "field": "status",
          "from": "open",
          "to": "not_reached"
        }
      ],
      "createdAt": "2026-11-18T07:05:00Z",
      "id": "6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f02"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/events' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Mail

## Mailboxes that feed desk: the comms mailbox, default space and type, routes (desk:admin)

`GET /api/desk/v1/mail-sources`

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

### Responses

- **200** Mail sources (`application/json`)

Fields of the 200 answer:

- `items` (array of MailSource, required)
  - `defaultSpaceId` (string, required): Space of tickets no route matched
  - `mailboxId` (string, required): Mailbox id in comms
  - `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
    - `candidates` (array of object): Spaces the AI may choose
      - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
      - `spaceId` (string, required): Space the AI may choose
      - `typeId` (string): Type of tickets created there
    - `enabled` (boolean): The AI chooses the space when no route matched
    - `threshold` (number): Default 0.7 (max 1)
  - `defaultTypeId` (string, nullable): Empty uses the space''s default type
  - `enabled` (boolean): Whether the mailbox feeds desk
  - `id` (string, read-only): Id of the mail source
  - `name` (string): Name of the mail source
  - `replyEnabled` (boolean): Agents may answer by mail through this mailbox
  - `routes` (array of object): Routes in order; the first matching one decides space and type
    - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
    - `spaceId` (string, required): Space of the route's tickets
    - `name` (string): Name of the route
    - `typeId` (string): Type of the route's tickets (default: the space's)
  - `updatedAt` (string (date-time), read-only): When it was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed it
  - `version` (integer): Version of the mail source; send it back on change

Example 200 answer:

```json
{
  "items": [
    {
      "aiRouting": {
        "candidates": [],
        "enabled": false,
        "threshold": 0.8
      },
      "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
      "enabled": true,
      "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
      "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
      "name": "support@muster-it.example",
      "replyEnabled": true,
      "routes": [],
      "updatedAt": "2026-10-20T13:40:00Z",
      "updatedBy": "elias.gruber@muster-it.example",
      "version": 3
    }
  ]
}
```

### Example request

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

## Let a comms mailbox (consumer desk) feed a space; one source per mailbox (desk:admin)

`POST /api/desk/v1/mail-sources`

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

### Request body

`application/json` (required)

- `defaultSpaceId` (string, required): Space of tickets no route matched
- `mailboxId` (string, required): Mailbox id in comms
- `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
  - `candidates` (array of object): Spaces the AI may choose
    - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
    - `spaceId` (string, required): Space the AI may choose
    - `typeId` (string): Type of tickets created there
  - `enabled` (boolean): The AI chooses the space when no route matched
  - `threshold` (number): Default 0.7 (max 1)
- `defaultTypeId` (string, nullable): Empty uses the space''s default type
- `enabled` (boolean): Whether the mailbox feeds desk
- `id` (string, read-only): Id of the mail source
- `name` (string): Name of the mail source
- `replyEnabled` (boolean): Agents may answer by mail through this mailbox
- `routes` (array of object): Routes in order; the first matching one decides space and type
  - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
  - `spaceId` (string, required): Space of the route's tickets
  - `name` (string): Name of the route
  - `typeId` (string): Type of the route's tickets (default: the space's)
- `updatedAt` (string (date-time), read-only): When it was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed it
- `version` (integer): Version of the mail source; send it back on change

Example:

```json
{
  "defaultSpaceId": "SUP",
  "defaultTypeId": "serviceanfrage",
  "enabled": true,
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\"",
      "name": "Störungsmeldungen",
      "spaceId": "SUP",
      "typeId": "stoerung"
    }
  ]
}
```

### Responses

- **201** Created (`application/json`)
- **409** The mailbox already feeds desk

Fields of the 201 answer:

- `defaultSpaceId` (string, required): Space of tickets no route matched
- `mailboxId` (string, required): Mailbox id in comms
- `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
  - `candidates` (array of object): Spaces the AI may choose
    - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
    - `spaceId` (string, required): Space the AI may choose
    - `typeId` (string): Type of tickets created there
  - `enabled` (boolean): The AI chooses the space when no route matched
  - `threshold` (number): Default 0.7 (max 1)
- `defaultTypeId` (string, nullable): Empty uses the space''s default type
- `enabled` (boolean): Whether the mailbox feeds desk
- `id` (string, read-only): Id of the mail source
- `name` (string): Name of the mail source
- `replyEnabled` (boolean): Agents may answer by mail through this mailbox
- `routes` (array of object): Routes in order; the first matching one decides space and type
  - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
  - `spaceId` (string, required): Space of the route's tickets
  - `name` (string): Name of the route
  - `typeId` (string): Type of the route's tickets (default: the space's)
- `updatedAt` (string (date-time), read-only): When it was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed it
- `version` (integer): Version of the mail source; send it back on change

Example 201 answer:

```json
{
  "aiRouting": {
    "candidates": [],
    "enabled": false,
    "threshold": 0.8
  },
  "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "enabled": true,
  "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"",
      "name": "Störungsmeldungen",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
    }
  ],
  "updatedAt": "2026-10-20T13:40:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/mail-sources' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"defaultSpaceId":"SUP","defaultTypeId":"serviceanfrage","enabled":true,"mailboxId":"3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01","name":"support@muster-it.example","replyEnabled":true,"routes":[{"condition":"trigger.data.subject contains \"Störung\"","name":"Störungsmeldungen","spaceId":"SUP","typeId":"stoerung"}]}'
```

## Change a mail source; needs the current version, the mailbox cannot change (desk:admin)

`PUT /api/desk/v1/mail-sources/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `defaultSpaceId` (string, required): Space of tickets no route matched
- `mailboxId` (string, required): Mailbox id in comms
- `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
  - `candidates` (array of object): Spaces the AI may choose
    - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
    - `spaceId` (string, required): Space the AI may choose
    - `typeId` (string): Type of tickets created there
  - `enabled` (boolean): The AI chooses the space when no route matched
  - `threshold` (number): Default 0.7 (max 1)
- `defaultTypeId` (string, nullable): Empty uses the space''s default type
- `enabled` (boolean): Whether the mailbox feeds desk
- `id` (string, read-only): Id of the mail source
- `name` (string): Name of the mail source
- `replyEnabled` (boolean): Agents may answer by mail through this mailbox
- `routes` (array of object): Routes in order; the first matching one decides space and type
  - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
  - `spaceId` (string, required): Space of the route's tickets
  - `name` (string): Name of the route
  - `typeId` (string): Type of the route's tickets (default: the space's)
- `updatedAt` (string (date-time), read-only): When it was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed it
- `version` (integer): Version of the mail source; send it back on change

Example:

```json
{
  "aiRouting": {
    "candidates": [],
    "enabled": false,
    "threshold": 0.8
  },
  "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "enabled": true,
  "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"",
      "name": "Störungsmeldungen",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
    }
  ],
  "updatedAt": "2026-10-20T13:40:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 3
}
```

### Responses

- **200** Saved (`application/json`)
- **409** Version conflict

Fields of the 200 answer:

- `defaultSpaceId` (string, required): Space of tickets no route matched
- `mailboxId` (string, required): Mailbox id in comms
- `aiRouting` (object): When no route matches, the AI chooses the space of a new ticket among the candidates (described in the admin's words); below the threshold, or when nothing fits, the default space is used.
  - `candidates` (array of object): Spaces the AI may choose
    - `description` (string, required): What belongs in the space, in the admin's words (max length 500)
    - `spaceId` (string, required): Space the AI may choose
    - `typeId` (string): Type of tickets created there
  - `enabled` (boolean): The AI chooses the space when no route matched
  - `threshold` (number): Default 0.7 (max 1)
- `defaultTypeId` (string, nullable): Empty uses the space''s default type
- `enabled` (boolean): Whether the mailbox feeds desk
- `id` (string, read-only): Id of the mail source
- `name` (string): Name of the mail source
- `replyEnabled` (boolean): Agents may answer by mail through this mailbox
- `routes` (array of object): Routes in order; the first matching one decides space and type
  - `condition` (string, required): When the route takes a mail: a bool expression in the flow language over `trigger.data`, the facts of the received mail (`from`, `fromDomain`, `to`, `subject`, `body`, `hasAttachments`, `mailbox`; `GET /conditions/catalog`, `mail`). Required. One that cannot be evaluated for a mail does not hold (the next route, at last the default space). (max length 4000)
  - `spaceId` (string, required): Space of the route's tickets
  - `name` (string): Name of the route
  - `typeId` (string): Type of the route's tickets (default: the space's)
- `updatedAt` (string (date-time), read-only): When it was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed it
- `version` (integer): Version of the mail source; send it back on change

Example 200 answer:

```json
{
  "aiRouting": {
    "candidates": [],
    "enabled": false,
    "threshold": 0.8
  },
  "defaultSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "defaultTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
  "enabled": true,
  "id": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "name": "support@muster-it.example",
  "replyEnabled": true,
  "routes": [
    {
      "condition": "trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"",
      "name": "Störungsmeldungen",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"
    }
  ],
  "updatedAt": "2026-10-20T13:40:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/mail-sources/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aiRouting":{"candidates":[],"enabled":false,"threshold":0.8},"defaultSpaceId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00","defaultTypeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f02","enabled":true,"id":"3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b11","mailboxId":"3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01","name":"support@muster-it.example","replyEnabled":true,"routes":[{"condition":"trigger.data.subject contains \"Störung\" || trigger.data.subject contains \"geht nicht\"","name":"Störungsmeldungen","spaceId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01"}],"updatedAt":"2026-10-20T13:40:00Z","updatedBy":"elias.gruber@muster-it.example","version":3}'
```

## Stop a mailbox from feeding desk; its mail is logged as unrouted (desk:admin)

`DELETE /api/desk/v1/mail-sources/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/mail-sources/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## What desk made of received mail: created, appended, held, dropped, unrouted, failed (desk:admin)

`GET /api/desk/v1/mail-log`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `disposition` | query | string |  | Comma-separated dispositions, e.g. held_spam,held_rate |
| `limit` | query | integer |  | (max 200) |
| `offset` | query | integer |  |  |

### Responses

- **200** Page (`application/json`)

Fields of the 200 answer:

- `items` (array of MailLogEntry)
  - `ai` (object): Decisions of the AI: classify (unclear mail) and route (space of a new ticket)
    - `classify` (MailAIUse)
      - `choice` (string): What the AI chose
      - `confidence` (number): Confidence of the AI (0–1)
      - `logId` (string): AI call log record
      - `used` (boolean): The AI was asked
    - `route` (MailAIUse)
      - `choice` (string): What the AI chose
      - `confidence` (number): Confidence of the AI (0–1)
      - `logId` (string): AI call log record
      - `used` (boolean): The AI was asked
  - `classification` (string): What desk classified the mail as
  - `commsMailId` (string): Received mail in comms
  - `createdAt` (string (date-time)): When desk processed the mail
  - `disposition` (string): What desk made of the mail (one of `created`, `appended`, `duplicate`, `bounce_processed`, `auto_dropped`, `bulk_dropped`, `loop_dropped`, `held_spam`, `held_rate`, `unrouted`, `failed`, `released`)
  - `emlDocumentId` (string): DMS document of the original mail (.eml): set for received mails, and for sent mails once comms archived them (after the sent event); the file is a ticket file of source `eml`
  - `entryId` (string): Entry the mail became
  - `from` (string): Sender address
  - `id` (string): Id of the log record
  - `itemId` (string): Ticket created or appended to
  - `itemNumber` (integer): Number of that ticket
  - `mailboxId` (string): comms mailbox the mail came in through
  - `reason` (string): Why the mail was held, dropped or failed
  - `receivedAt` (string (date-time)): When the mail was received
  - `subject` (string): Subject
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "classification": "reply",
      "commsMailId": "2a9b0c1d-3e4f-4a5b-8c7d-9e0f1a2b3c02",
      "createdAt": "2026-11-17T15:02:03Z",
      "disposition": "appended",
      "entryId": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d07",
      "from": "katrin.stadler@alpenhotel-seeblick.example",
      "id": "1f8a9b0c-2d3e-4f4a-9b6c-8d9e0f1a2b02",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "itemNumber": 1,
      "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
      "receivedAt": "2026-11-17T15:02:00Z",
      "subject": "AW: [#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus"
    },
    {
      "classification": "spam",
      "commsMailId": "2a9b0c1d-3e4f-4a5b-8c7d-9e0f1a2b3c01",
      "createdAt": "2026-11-18T06:02:13Z",
      "disposition": "held_spam",
      "from": "angebote@gewinnspiel.example",
      "id": "1f8a9b0c-2d3e-4f4a-9b6c-8d9e0f1a2b01",
      "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
      "reason": "Absender ist neu, Text enthält nur einen Link",
      "receivedAt": "2026-11-18T06:02:11Z",
      "subject": "Ihr Gewinn wartet"
    }
  ],
  "total": 2
}
```

### Example request

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

## Turn a held, dropped, unrouted or failed mail into a ticket, or append it to itemId (desk:admin)

`POST /api/desk/v1/mail-log/{id}/release`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `itemId` (string): Item id or number

Example:

```json
{
  "itemId": "#1"
}
```

### Responses

- **200** The new record (`application/json`)
- **503** Desk receives no mail (code unavailable)

Fields of the 200 answer:

- `ai` (object): Decisions of the AI: classify (unclear mail) and route (space of a new ticket)
  - `classify` (MailAIUse)
    - `choice` (string): What the AI chose
    - `confidence` (number): Confidence of the AI (0–1)
    - `logId` (string): AI call log record
    - `used` (boolean): The AI was asked
  - `route` (MailAIUse)
    - `choice` (string): What the AI chose
    - `confidence` (number): Confidence of the AI (0–1)
    - `logId` (string): AI call log record
    - `used` (boolean): The AI was asked
- `classification` (string): What desk classified the mail as
- `commsMailId` (string): Received mail in comms
- `createdAt` (string (date-time)): When desk processed the mail
- `disposition` (string): What desk made of the mail (one of `created`, `appended`, `duplicate`, `bounce_processed`, `auto_dropped`, `bulk_dropped`, `loop_dropped`, `held_spam`, `held_rate`, `unrouted`, `failed`, `released`)
- `emlDocumentId` (string): DMS document of the original mail (.eml): set for received mails, and for sent mails once comms archived them (after the sent event); the file is a ticket file of source `eml`
- `entryId` (string): Entry the mail became
- `from` (string): Sender address
- `id` (string): Id of the log record
- `itemId` (string): Ticket created or appended to
- `itemNumber` (integer): Number of that ticket
- `mailboxId` (string): comms mailbox the mail came in through
- `reason` (string): Why the mail was held, dropped or failed
- `receivedAt` (string (date-time)): When the mail was received
- `subject` (string): Subject

Example 200 answer:

```json
{
  "ai": {
    "classify": {
      "choice": "spam",
      "confidence": 0.94,
      "logId": "4b0c1d2e-5f6a-4b7c-9d8e-0f1a2b3c4d01",
      "used": true
    },
    "route": {
      "used": false
    }
  },
  "classification": "spam",
  "commsMailId": "2a9b0c1d-3e4f-4a5b-8c7d-9e0f1a2b3c01",
  "createdAt": "2026-11-18T06:02:13Z",
  "disposition": "held_spam",
  "emlDocumentId": "3d0e1f2a-4b5c-4d6e-9f8a-0b1c2d3e4f09",
  "from": "angebote@gewinnspiel.example",
  "id": "1f8a9b0c-2d3e-4f4a-9b6c-8d9e0f1a2b01",
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "reason": "Absender ist neu, Text enthält nur einen Link",
  "receivedAt": "2026-11-18T06:02:11Z",
  "subject": "Ihr Gewinn wartet"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/mail-log/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/release' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"itemId":"#1"}'
```

## The caller's mail signature (Markdown) (desk:read)

`GET /api/desk/v1/me/mail-signature`

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

A person's own setting; service accounts get `403 person_required`.

### Responses

- **200** Signature (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `body` (string): Markdown
- `enabled` (boolean): Whether the signature is added to new mails
- `updatedAt` (string (date-time), read-only): When the signature was last saved
- `userRef` (string, read-only): Login (e-mail) of the agent

Example 200 answer:

```json
{
  "body": "Viele Grüße\nSophie Huber\nService Desk · Muster IT GmbH\nTelefon +49 851 123456-10",
  "enabled": true,
  "updatedAt": "2026-09-01T08:00:00Z",
  "userRef": "sophie.huber@muster-it.example"
}
```

### Example request

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

## Save the caller's mail signature (desk:write)

`PUT /api/desk/v1/me/mail-signature`

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

A person's own setting; service accounts get `403 person_required`.

### Request body

`application/json` (required)

- `body` (string): Markdown
- `enabled` (boolean): Whether the signature is added to new mails
- `updatedAt` (string (date-time), read-only): When the signature was last saved
- `userRef` (string, read-only): Login (e-mail) of the agent

Example:

```json
{
  "body": "Viele Grüße\nSophie Huber\nService Desk · Muster IT GmbH\nTelefon +49 851 123456-10",
  "enabled": true,
  "updatedAt": "2026-09-01T08:00:00Z",
  "userRef": "sophie.huber@muster-it.example"
}
```

### Responses

- **200** Saved (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `body` (string): Markdown
- `enabled` (boolean): Whether the signature is added to new mails
- `updatedAt` (string (date-time), read-only): When the signature was last saved
- `userRef` (string, read-only): Login (e-mail) of the agent

Example 200 answer:

```json
{
  "body": "Viele Grüße\nSophie Huber\nService Desk · Muster IT GmbH\nTelefon +49 851 123456-10",
  "enabled": true,
  "updatedAt": "2026-09-01T08:00:00Z",
  "userRef": "sophie.huber@muster-it.example"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/me/mail-signature' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Viele Grüße\nSophie Huber\nService Desk · Muster IT GmbH\nTelefon +49 851 123456-10","enabled":true,"updatedAt":"2026-09-01T08:00:00Z","userRef":"sophie.huber@muster-it.example"}'
```

## Mail of an email entry: headers, recipients, delivery, attachments and the HTML body sanitised for display (desk:read)

`GET /api/desk/v1/items/{ref}/entries/{entryId}/mail`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `images` | query | boolean |  | Load remote images (they can track the reader); default false |
| `ref` | path | string | yes | Item id or number |
| `entryId` | path | string | yes |  |

### Responses

- **200** Mail (`application/json`)

Fields of the 200 answer:

- `blockedImages` (integer): Remote images left out
- `html` (string): Sanitised HTML body; inline images point to the attachment download
- `mail` (object): The mail of the entry
  - `attachments` (array of object): Attachments of the mail, also those that were not stored
    - `contentType` (string): MIME type
    - `documentId` (string): DMS document of the stored file (empty when skipped)
    - `inline` (boolean): An inline image of the HTML body
    - `name` (string): File name
    - `reason` (string): Why the file was skipped
    - `size` (integer): Size in bytes
    - `skipped` (boolean): Not stored (blocked type
  - `cc` (array of Address): Recipients in copy
    - `address` (string): E-mail address
    - `name` (string): Display name (may be empty)
  - `classification` (string): What desk classified a received mail as
  - `deliveryState` (string): Delivery state of a sent mail (draft, queued, sent, delivered, …)
  - `direction` (string): in: received; out: sent (one of `in`, `out`)
  - `entryId` (string): Entry of the mail
  - `from` (Address)
    - `address` (string): E-mail address
    - `name` (string): Display name (may be empty)
  - `hasHtml` (boolean): The mail has an HTML body
  - `inReplyTo` (string): In-Reply-To header
  - `isAuto` (boolean): Automatic answer (out of office)
  - `mailboxId` (string): comms mailbox the mail came in or went out through
  - `mainText` (string): Received mails: the text without quoted history and signature (missing when nothing was cut)
  - `messageId` (string): Message-ID header
  - `receivedAt` (string (date-time)): When the mail was received
  - `references` (array of string): References header (message ids)
  - `sentAt` (string (date-time)): When the mail was sent
  - `subject` (string): Subject
  - `to` (array of Address): Recipients
    - `address` (string): E-mail address
    - `name` (string): Display name (may be empty)
  - `trimMethod` (string): How mainText was found: rules (heuristic) or the AI (one of `heuristic`, `ai`)

Example 200 answer:

```json
{
  "blockedImages": 0,
  "html": "\u003cp\u003eGuten Morgen Frau Stadler,\u003c/p\u003e\u003cp\u003edanke für die Meldung. Wir prüfen die Access Points im 2. OG per Fernzugriff und melden uns bis 10 Uhr.\u003c/p\u003e",
  "mail": {
    "attachments": [],
    "cc": [],
    "deliveryState": "delivered",
    "direction": "out",
    "entryId": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d02",
    "from": {
      "address": "support@muster-it.example",
      "name": "Sophie Huber (Muster IT)"
    },
    "hasHtml": true,
    "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
    "messageId": "\u003c1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d02@muster-it.example\u003e",
    "references": [],
    "sentAt": "2026-11-17T07:20:04Z",
    "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
    "to": [
      {
        "address": "katrin.stadler@alpenhotel-seeblick.example",
        "name": "Katrin Stadler"
      }
    ]
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a draft (desk:write, agent role)

`DELETE /api/desk/v1/items/{ref}/entries/{entryId}/mail`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `entryId` | path | string | yes |  |

### Responses

- **204** Deleted

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a draft; send it with send=true (desk:write, agent role)

`PATCH /api/desk/v1/items/{ref}/entries/{entryId}/mail`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `entryId` | path | string | yes |  |

### Request body

`application/json` (required)

- `aiGenerated` (boolean): The text was written with AI help
- `attachmentIds` (array of string): Documents of the ticket
- `bcc` (array of Address): Recipients in blind copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `body` (string): Markdown
- `cc` (array of Address): Recipients in copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `inReplyToEntryId` (string): The mail entry of the ticket this mail answers (threading). An internal mail answers only internal mails (422 public_thread). Empty on an existing draft keeps the mail it answers.
- `includeChain` (boolean): Add every earlier mail of the ticket the recipients may see (received and sent, public, no automatic answers or failed deliveries) below the text, newest first, Outlook style ("-----Original Message-----", Von, Gesendet, An, Cc, Betreff; never Bcc); at most 100 mails and 200 KB of text, older ones are left out with a note. An internal mail carries only its own thread (the mail it answers and its ancestors). Default true; stored with the mail and kept on a resend.
- `mailboxId` (string): Empty uses the default mailbox
- `send` (boolean): Send now; false saves a draft
- `signature` (boolean): Append the signature (default true)
- `subject` (string): Subject
- `to` (array of Address): Recipients
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `visibility` (string): internal: an internal mail to third parties (suppliers, …). It is sent, but the entry stays internal and is never shown to customers. It needs explicit recipients, none of them a participant of the ticket (422 recipient_is_participant on the field), its subject carries no [#N] token, its Reply-To an internal tag, and answers to it are stored internal. Empty: public, unless inReplyToEntryId is an internal mail (then internal; public is refused with 422 internal_thread). Saving or sending an existing draft with it empty keeps the draft's kind (internal or not); only an explicit value changes it. Kept on a resend. (one of `public`, `internal`)

Example:

```json
{
  "body": "Ich komme heute um 14 Uhr vorbei und tausche den Switch aus.",
  "send": false,
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ]
}
```

### Responses

- **200** The entry with its mail (`application/json`)
- **400** Invalid, or already sent
- **422** Internal mail to a participant (recipient_is_participant, field to/cc/bcc), or a thread it may not answer (internal_thread, public_thread)

Fields of the 200 answer:

- `aiGenerated` (boolean): The text was written with AI help
- `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
- `authorName` (string): Name of the author
- `authorRef` (string): Login (e-mail) of the author
- `automated` (boolean): Written by a rule or service; never counts as a first response
- `body` (string): Markdown
- `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
- `createdAt` (string (date-time)): When the entry was written
- `editedAt` (string (date-time)): When the entry was last edited
- `id` (string): Id of the entry
- `itemId` (string): Item the entry belongs to
- `kind` (string): comment, email_in, email_out or system
- `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
  - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
  - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
  - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
  - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
  - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
- `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
- `movedFromId` (string): Item the entry was moved from
- `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)

Example 200 answer:

```json
{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Ich komme heute um 14 Uhr vorbei und tausche den Switch aus.","send":false,"subject":"[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus","to":[{"address":"katrin.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}]}'
```

## Send a failed mail again as a new entry, optionally to corrected recipients (to, cc, bcc; agent role) (desk:write)

`POST /api/desk/v1/items/{ref}/entries/{entryId}/mail/resend`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `entryId` | path | string | yes |  |

### Request body

`application/json`

- `aiGenerated` (boolean): The text was written with AI help
- `attachmentIds` (array of string): Documents of the ticket
- `bcc` (array of Address): Recipients in blind copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `body` (string): Markdown
- `cc` (array of Address): Recipients in copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `inReplyToEntryId` (string): The mail entry of the ticket this mail answers (threading). An internal mail answers only internal mails (422 public_thread). Empty on an existing draft keeps the mail it answers.
- `includeChain` (boolean): Add every earlier mail of the ticket the recipients may see (received and sent, public, no automatic answers or failed deliveries) below the text, newest first, Outlook style ("-----Original Message-----", Von, Gesendet, An, Cc, Betreff; never Bcc); at most 100 mails and 200 KB of text, older ones are left out with a note. An internal mail carries only its own thread (the mail it answers and its ancestors). Default true; stored with the mail and kept on a resend.
- `mailboxId` (string): Empty uses the default mailbox
- `send` (boolean): Send now; false saves a draft
- `signature` (boolean): Append the signature (default true)
- `subject` (string): Subject
- `to` (array of Address): Recipients
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `visibility` (string): internal: an internal mail to third parties (suppliers, …). It is sent, but the entry stays internal and is never shown to customers. It needs explicit recipients, none of them a participant of the ticket (422 recipient_is_participant on the field), its subject carries no [#N] token, its Reply-To an internal tag, and answers to it are stored internal. Empty: public, unless inReplyToEntryId is an internal mail (then internal; public is refused with 422 internal_thread). Saving or sending an existing draft with it empty keeps the draft's kind (internal or not); only an explicit value changes it. Kept on a resend. (one of `public`, `internal`)

Example:

```json
{
  "send": true,
  "to": [
    {
      "address": "k.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ]
}
```

### Responses

- **201** The new entry (`application/json`)

Fields of the 201 answer:

- `aiGenerated` (boolean): The text was written with AI help
- `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
- `authorName` (string): Name of the author
- `authorRef` (string): Login (e-mail) of the author
- `automated` (boolean): Written by a rule or service; never counts as a first response
- `body` (string): Markdown
- `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
- `createdAt` (string (date-time)): When the entry was written
- `editedAt` (string (date-time)): When the entry was last edited
- `id` (string): Id of the entry
- `itemId` (string): Item the entry belongs to
- `kind` (string): comment, email_in, email_out or system
- `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
  - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
  - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
  - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
  - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
  - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
- `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
- `movedFromId` (string): Item the entry was moved from
- `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)

Example 201 answer:

```json
{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/entries/string/mail/resend' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"send":true,"to":[{"address":"k.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}]}'
```

## Composer defaults: requester (to) and people in copy, reply subject with [#N], mailbox and signature (desk:read, agent role)

`GET /api/desk/v1/items/{ref}/mail/defaults`

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

Without parameters the defaults of an answer to the customers (public mails only). replyTo answers a mail of the
ticket: an internal mail to or from third parties gives its sender (to) and its other recipients (cc) without own
mailboxes and participants, the subject "Re: …" without token and visibility internal. visibility=internal starts
a new internal mail to third parties (no recipients).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `replyTo` | query | string |  | Entry id of the mail answered |
| `visibility` | query | string |  | (one of `public`, `internal`) |
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Defaults (`application/json`)
- **400** replyTo is no mail of the ticket, or an unknown visibility (code invalid)
- **422** public answer to an internal mail (internal_thread), internal answer to a customer mail (public_thread)

Fields of the 200 answer:

- `cc` (array of Address): Recipients in copy (participants)
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `inReplyToEntryId` (string): The mail answered (replyTo)
- `mailboxId` (string): Default mailbox of the space
- `mailboxes` (array of object): Mailboxes the mail can be sent from
  - `mailboxId` (string): comms mailbox id
  - `name` (string): Name of the mailbox
- `signature` (AgentSignature)
  - `body` (string): Markdown
  - `enabled` (boolean): Whether the signature is added to new mails
  - `updatedAt` (string (date-time), read-only): When the signature was last saved
  - `userRef` (string, read-only): Login (e-mail) of the agent
- `subject` (string): Reply subject with the [#N] token
- `to` (array of Address): Recipients (the requester)
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `visibility` (string): internal for a new internal mail to third parties or an answer to one (one of `public`, `internal`)

Example 200 answer:

```json
{
  "cc": [],
  "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
  "mailboxes": [
    {
      "mailboxId": "3f0a1b2c-4d5e-4f6a-9b8c-0d1e2f3a4b01",
      "name": "support@muster-it.example"
    }
  ],
  "signature": {
    "body": "Viele Grüße\nSophie Huber",
    "enabled": true,
    "updatedAt": "2026-09-01T08:00:00Z",
    "userRef": "sophie.huber@muster-it.example"
  },
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ],
  "visibility": "public"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/items/string/mail/defaults' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Write a mail: saved as draft, sent with send=true (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/mail`

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

Sending queues the mail in the transaction that stores the entry; comms sends it from the chosen
mailbox (Reply-To with the ticket's tag for SES mailboxes) and reports the delivery. The entry's
mail.deliveryState goes queued → sent → delivered (or bounced, failed, suppressed). The first response
of the SLA is met when the mail is sent.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `aiGenerated` (boolean): The text was written with AI help
- `attachmentIds` (array of string): Documents of the ticket
- `bcc` (array of Address): Recipients in blind copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `body` (string): Markdown
- `cc` (array of Address): Recipients in copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `inReplyToEntryId` (string): The mail entry of the ticket this mail answers (threading). An internal mail answers only internal mails (422 public_thread). Empty on an existing draft keeps the mail it answers.
- `includeChain` (boolean): Add every earlier mail of the ticket the recipients may see (received and sent, public, no automatic answers or failed deliveries) below the text, newest first, Outlook style ("-----Original Message-----", Von, Gesendet, An, Cc, Betreff; never Bcc); at most 100 mails and 200 KB of text, older ones are left out with a note. An internal mail carries only its own thread (the mail it answers and its ancestors). Default true; stored with the mail and kept on a resend.
- `mailboxId` (string): Empty uses the default mailbox
- `send` (boolean): Send now; false saves a draft
- `signature` (boolean): Append the signature (default true)
- `subject` (string): Subject
- `to` (array of Address): Recipients
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `visibility` (string): internal: an internal mail to third parties (suppliers, …). It is sent, but the entry stays internal and is never shown to customers. It needs explicit recipients, none of them a participant of the ticket (422 recipient_is_participant on the field), its subject carries no [#N] token, its Reply-To an internal tag, and answers to it are stored internal. Empty: public, unless inReplyToEntryId is an internal mail (then internal; public is refused with 422 internal_thread). Saving or sending an existing draft with it empty keeps the draft's kind (internal or not); only an explicit value changes it. Kept on a resend. (one of `public`, `internal`)

Example:

```json
{
  "body": "Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.",
  "includeChain": true,
  "send": true,
  "signature": true,
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ],
  "visibility": "public"
}
```

### Responses

- **201** The entry with its mail (`application/json`)
- **422** Internal mail to a participant (recipient_is_participant, field to/cc/bcc), public answer to an internal mail (internal_thread), internal answer to a customer mail (public_thread)
- **503** Desk sends no mail (code unavailable)

Fields of the 201 answer:

- `aiGenerated` (boolean): The text was written with AI help
- `authorKind` (string): external: a third party who answered an internal mail (the entry is internal) (one of `agent`, `requester`, `system`, `ai`, `rule`, `external`)
- `authorName` (string): Name of the author
- `authorRef` (string): Login (e-mail) of the author
- `automated` (boolean): Written by a rule or service; never counts as a first response
- `body` (string): Markdown
- `channel` (string): Where the entry came from (one of `ui`, `mail`, `portal`, `api`)
- `createdAt` (string (date-time)): When the entry was written
- `editedAt` (string (date-time)): When the entry was last edited
- `id` (string): Id of the entry
- `itemId` (string): Item the entry belongs to
- `kind` (string): comment, email_in, email_out or system
- `mail` (object): Mail of email_in and email_out entries: direction, from, to, cc, subject, deliveryState (draft, queued, sent, delivered, deferred, bounced, failed, suppressed), recipientStates, attachments
  - `inReplyToEntryId` (string): Outgoing mails: the mail entry of the ticket it answers; a draft keeps it when it is saved or sent without inReplyToEntryId
  - `includeChain` (boolean): Sent mails: whether the earlier mails of the ticket went out below the text
  - `mainText` (string): Received mails: the text without quoted history, signature, closing and legal footer; missing when nothing was cut or the entry was edited. `body` stays the full text.
  - `thirdParty` (boolean): An internal mail to or from third parties (suppliers, …; sent with visibility internal or answering one). An internal mail without it – a customer mail a merge or move hid – still belongs to the customer's thread.
  - `trimMethod` (string): How mainText was found: rules on the text, or the AI for a long mail (settings.mail.aiTrim) (one of `heuristic`, `ai`)
- `mailNote` (string): why no mail was sent for a public comment (`work_type`: the ticket type has the work focus, comments on it are never mailed) (one of `no_mailbox`, `no_recipient`, `mail_unavailable`, `work_type`)
- `movedFromId` (string): Item the entry was moved from
- `visibility` (string): internal: only staff see it; public: the requester sees it too (one of `internal`, `public`)

Example 201 answer:

```json
{
  "aiGenerated": false,
  "authorKind": "agent",
  "authorName": "Lukas Wimmer",
  "authorRef": "lukas.wimmer@muster-it.example",
  "automated": false,
  "body": "Controller zeigt AP-207 mit ständigen Neustarts (PoE-Budget am Switch im Technikraum 2. OG überschritten). AP-201 läuft stabil.",
  "channel": "ui",
  "createdAt": "2026-11-17T08:40:00Z",
  "id": "1b8c9d0e-2f3a-4b4c-9d6e-8f9a0b1c2d03",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "kind": "comment",
  "visibility": "internal"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.","includeChain":true,"send":true,"signature":true,"subject":"[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus","to":[{"address":"katrin.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}],"visibility":"public"}'
```

## Render a mail exactly as it would be sent (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/mail/preview`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `aiGenerated` (boolean): The text was written with AI help
- `attachmentIds` (array of string): Documents of the ticket
- `bcc` (array of Address): Recipients in blind copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `body` (string): Markdown
- `cc` (array of Address): Recipients in copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `inReplyToEntryId` (string): The mail entry of the ticket this mail answers (threading). An internal mail answers only internal mails (422 public_thread). Empty on an existing draft keeps the mail it answers.
- `includeChain` (boolean): Add every earlier mail of the ticket the recipients may see (received and sent, public, no automatic answers or failed deliveries) below the text, newest first, Outlook style ("-----Original Message-----", Von, Gesendet, An, Cc, Betreff; never Bcc); at most 100 mails and 200 KB of text, older ones are left out with a note. An internal mail carries only its own thread (the mail it answers and its ancestors). Default true; stored with the mail and kept on a resend.
- `mailboxId` (string): Empty uses the default mailbox
- `send` (boolean): Send now; false saves a draft
- `signature` (boolean): Append the signature (default true)
- `subject` (string): Subject
- `to` (array of Address): Recipients
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `visibility` (string): internal: an internal mail to third parties (suppliers, …). It is sent, but the entry stays internal and is never shown to customers. It needs explicit recipients, none of them a participant of the ticket (422 recipient_is_participant on the field), its subject carries no [#N] token, its Reply-To an internal tag, and answers to it are stored internal. Empty: public, unless inReplyToEntryId is an internal mail (then internal; public is refused with 422 internal_thread). Saving or sending an existing draft with it empty keeps the draft's kind (internal or not); only an explicit value changes it. Kept on a resend. (one of `public`, `internal`)

Example:

```json
{
  "body": "Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.",
  "includeChain": true,
  "send": true,
  "signature": true,
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "to": [
    {
      "address": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler"
    }
  ],
  "visibility": "public"
}
```

### Responses

- **200** Rendered mail (`application/json`)

Fields of the 200 answer:

- `html` (string)
- `subject` (string)
- `text` (string)

Example 200 answer:

```json
{
  "html": "\u003cp\u003eDer Switch ist getauscht, alle Access Points laufen wieder stabil.\u003c/p\u003e\u003cp\u003eViele Grüße\u003cbr\u003eSophie Huber\u003c/p\u003e",
  "subject": "[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "text": "Der Switch ist getauscht, alle Access Points laufen wieder stabil.\n\nViele Grüße\nSophie Huber"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/mail/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Der Switch ist getauscht, alle Access Points laufen wieder stabil. Bitte geben Sie uns Bescheid, falls Gäste noch Probleme melden.","includeChain":true,"send":true,"signature":true,"subject":"[#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus","to":[{"address":"katrin.stadler@alpenhotel-seeblick.example","name":"Katrin Stadler"}],"visibility":"public"}'
```

## Requester and people in copy (receive replies, see the ticket in the customer portal) (desk:read)

`GET /api/desk/v1/items/{ref}/participants`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Participants (`application/json`)

Fields of the 200 answer:

- `items` (array of Participant, required)
  - `addedBy` (string): Login (e-mail) of who added the participant
  - `contactRef` (object): Masterdata contact person of the participant
  - `createdAt` (string (date-time)): When the participant was added
  - `email` (string): E-mail address
  - `name` (string): Name
  - `requesterId` (string): Requester id
  - `role` (string): requester or cc (in copy) (one of `requester`, `cc`)

Example 200 answer:

```json
{
  "items": [
    {
      "addedBy": "sophie.huber@muster-it.example",
      "contactRef": {
        "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
        "name": "Katrin Stadler"
      },
      "createdAt": "2026-11-17T07:12:00Z",
      "email": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler",
      "requesterId": "0a7b8c9d-1e2f-4a3b-8c5d-7e8f9a0b1c01",
      "role": "requester"
    }
  ]
}
```

### Example request

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

## Add a person in copy, or make them the requester (the previous requester stays in copy; agent role) (desk:write)

`POST /api/desk/v1/items/{ref}/participants`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `email` (string (email), required)
- `name` (string)
- `role` (string): (one of `requester`, `cc`)

Example:

```json
{
  "email": "florian.moser@alpenhotel-seeblick.example",
  "name": "Florian Moser",
  "role": "cc"
}
```

### Responses

- **200** Participants (`application/json`)

Fields of the 200 answer:

- `items` (array of Participant, required)
  - `addedBy` (string): Login (e-mail) of who added the participant
  - `contactRef` (object): Masterdata contact person of the participant
  - `createdAt` (string (date-time)): When the participant was added
  - `email` (string): E-mail address
  - `name` (string): Name
  - `requesterId` (string): Requester id
  - `role` (string): requester or cc (in copy) (one of `requester`, `cc`)

Example 200 answer:

```json
{
  "items": [
    {
      "addedBy": "sophie.huber@muster-it.example",
      "createdAt": "2026-11-17T07:12:00Z",
      "email": "katrin.stadler@alpenhotel-seeblick.example",
      "name": "Katrin Stadler",
      "requesterId": "0a7b8c9d-1e2f-4a3b-8c5d-7e8f9a0b1c01",
      "role": "requester"
    },
    {
      "addedBy": "sophie.huber@muster-it.example",
      "createdAt": "2026-11-18T09:20:00Z",
      "email": "florian.moser@alpenhotel-seeblick.example",
      "name": "Florian Moser",
      "requesterId": "0a7b8c9d-1e2f-4a3b-8c5d-7e8f9a0b1c02",
      "role": "cc"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/participants' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"email":"florian.moser@alpenhotel-seeblick.example","name":"Florian Moser","role":"cc"}'
```

## Take a person off the ticket (desk:write, agent role)

`DELETE /api/desk/v1/items/{ref}/participants/{requesterId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `requesterId` | path | string | yes |  |

### Responses

- **204** Removed

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/items/string/participants/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Files of the ticket: every file, mail attachments, inline images, originals (.eml) and generated files (desk:read)

`GET /api/desk/v1/items/{ref}/attachments`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Files (`application/json`)

Fields of the 200 answer:

- `items` (array of ItemAttachment, required)
  - `contentId` (string): Content-ID of an inline image
  - `createdAt` (string (date-time)): When the file was added
  - `documentId` (string): DMS document holding the file
  - `entryId` (string): Entry (mail or comment) the file came with
  - `id` (string): Id of the file record
  - `inline` (boolean): An inline image of a mail body
  - `itemId` (string): Item the file belongs to
  - `mime` (string): MIME type
  - `name` (string): File name
  - `portalVisible` (boolean): Requesters see the file in the customer portal
  - `size` (integer): Size in bytes
  - `source` (string): mail: attachment of a mail; upload: staff upload; portal: requester upload; conversion: brought along by a conversion; eml: the original (.eml) of a received or sent mail (entryId set, never visible to requesters, never handed to forge); generated: made by desk (meeting transcripts) (one of `mail`, `upload`, `portal`, `conversion`, `eml`, `generated`)
  - `uploadedBy` (string): Login (e-mail) of who uploaded it

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-17T08:41:00Z",
      "documentId": "3d0e1f2a-4b5c-4d6e-9f8a-0b1c2d3e4f01",
      "id": "2c9d0e1f-3a4b-4c5d-8e7f-9a0b1c2d3e01",
      "inline": false,
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "mime": "text/plain",
      "name": "Controller-Log_AP-207.txt",
      "portalVisible": false,
      "size": 18233,
      "source": "upload",
      "uploadedBy": "lukas.wimmer@muster-it.example"
    }
  ]
}
```

### Example request

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

## Upload a file to the ticket, within the tenant's mail limits (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/attachments`

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

The file is stored in DMS and scanned for malware afterwards: until the scan cleared it, its content answers `409 scan_pending`, a file the scan found something in `403 infected`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required)

### Responses

- **201** The stored file (`application/json`)
- **400** No multipart `file` part, no usable file name, or the file breaks the tenant's mail limits (size, blocked type) – code invalid, field file (`application/json`)
- **403** No desk:write, or not at least the agent role in the ticket's space (code forbidden) (`application/json`)
- **404** No such ticket, or one the caller does not see (`application/json`)
- **503** The file store is not configured (code unavailable) (`application/json`)

Fields of the 201 answer:

- `contentId` (string): Content-ID of an inline image
- `createdAt` (string (date-time)): When the file was added
- `documentId` (string): DMS document holding the file
- `entryId` (string): Entry (mail or comment) the file came with
- `id` (string): Id of the file record
- `inline` (boolean): An inline image of a mail body
- `itemId` (string): Item the file belongs to
- `mime` (string): MIME type
- `name` (string): File name
- `portalVisible` (boolean): Requesters see the file in the customer portal
- `size` (integer): Size in bytes
- `source` (string): mail: attachment of a mail; upload: staff upload; portal: requester upload; conversion: brought along by a conversion; eml: the original (.eml) of a received or sent mail (entryId set, never visible to requesters, never handed to forge); generated: made by desk (meeting transcripts) (one of `mail`, `upload`, `portal`, `conversion`, `eml`, `generated`)
- `uploadedBy` (string): Login (e-mail) of who uploaded it

Example 201 answer:

```json
{
  "contentId": "",
  "createdAt": "2026-11-17T08:41:00Z",
  "documentId": "3d0e1f2a-4b5c-4d6e-9f8a-0b1c2d3e4f01",
  "entryId": "",
  "id": "2c9d0e1f-3a4b-4c5d-8e7f-9a0b1c2d3e01",
  "inline": false,
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "mime": "text/plain",
  "name": "Controller-Log_AP-207.txt",
  "portalVisible": false,
  "size": 18233,
  "source": "upload",
  "uploadedBy": "lukas.wimmer@muster-it.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/attachments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## A file of the ticket: viewable types inline, everything else and download=true as attachment (desk:read)

`GET /api/desk/v1/items/{ref}/attachments/{documentId}/content`

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

Viewable types (png, jpeg, gif, webp, PDF, text types incl. JSON, and message/rfc822 as `text/plain; charset=utf-8`) answer `Content-Disposition: inline`; HTML, SVG, XML, office files, archives and unknown types are a download. `download=true` always downloads with the real file name. The decision is made by `common/pkg/filecontent`, the same for the customer routes.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `download` | query | boolean |  | true (or 1) answers as a download (`Content-Disposition: attachment` with the file name) instead of the inline view of viewable types (default `false`) |
| `ref` | path | string | yes | Item id or number |
| `documentId` | path | string | yes |  |

### Responses

- **200** The file (`application/octet-stream`)
- **403** The malware scan found something (code infected)
- **404** No such file on the ticket
- **409** The malware scan has not cleared the file (yet): pending, or failed and scanned again later (code scan_pending; DMS answers the same as not_scanned)
- **503** The file store is not configured (code unavailable)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/items/string/attachments/string/content' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## A stored mail (.eml, message/rfc822) of the ticket for display: headers, text, sanitised HTML and part manifest (desk:read)

`GET /api/desk/v1/items/{ref}/attachments/{documentId}/mail`

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

Parsed by comms, HTML sanitised like the mail of an entry (`getEntryMail`). Inline images of the entry's own mail link to their stored files, others are dropped; remote images are blocked unless `images=true`. Only files of type `message/rfc822`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `images` | query | boolean |  | true loads remote images (they can track the reader) (default `false`) |
| `ref` | path | string | yes | Item id or number |
| `documentId` | path | string | yes |  |

### Responses

- **200** The mail (`application/json`)
- **400** The file is no mail (message/rfc822), too large for display (40 MB) or cannot be read (code invalid, field documentId)
- **403** The malware scan found something (code infected)
- **404** No such file on the ticket
- **409** The malware scan has not cleared the file (yet): pending, or failed and scanned again later (code scan_pending; DMS answers the same as not_scanned)
- **503** The file store or the mail parser is not configured (code unavailable)

Fields of the 200 answer:

- `blockedImages` (integer): Remote images left out; images=true loads them
- `cc` (array of Address): Recipients in copy
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `date` (string (date-time)): Date header
- `from` (Address)
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)
- `html` (string): Sanitised HTML body
- `parts` (array of object): Parts of the mail (attachments and inline files)
  - `contentType` (string): MIME type
  - `inline` (boolean): An inline part
  - `name` (string): File name
  - `size` (integer): Size in bytes
- `subject` (string): Subject
- `text` (string): Plain-text body
- `to` (array of Address): Recipients
  - `address` (string): E-mail address
  - `name` (string): Display name (may be empty)

Example 200 answer:

```json
{
  "blockedImages": 0,
  "cc": [],
  "date": "2026-11-17T15:02:00Z",
  "from": {
    "address": "katrin.stadler@alpenhotel-seeblick.example",
    "name": "Katrin Stadler"
  },
  "html": "\u003cp\u003eVielen Dank, die Gäste sind wieder zufrieden!\u003c/p\u003e",
  "parts": [
    {
      "contentType": "text/plain",
      "inline": false,
      "name": "",
      "size": 48
    },
    {
      "contentType": "text/html",
      "inline": false,
      "name": "",
      "size": 61
    }
  ],
  "subject": "AW: [#1] WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "text": "Vielen Dank, die Gäste sind wieder zufrieden!",
  "to": [
    {
      "address": "support@muster-it.example",
      "name": "Muster IT Support"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/items/string/attachments/string/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Projects

## Projects with spent time and budget state (desk:read)

`GET /api/desk/v1/projects`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |
| `status` | query | string |  | Comma-separated statuses |
| `phase` | query | string |  | Comma-separated phases (new, active, waiting, done) of the projects' statuses – of their type's workflow, or of the built-in statuses |
| `customer` | query | string |  |  |
| `spaceId` | query | string |  | Home space of the projects (id or key); an unknown space gives an empty list |
| `type` | query | string |  | Project type of the projects (id or key); an unknown type gives an empty list |
| `responsible` | query | string |  | Responsible person of the projects: `me` (the caller) or a person reference |
| `archived` | query | boolean |  |  |
| `limit` | query | integer |  | (max 500) |
| `offset` | query | integer |  |  |

### Responses

- **200** Projects (`application/json`)

Fields of the 200 answer:

- `items` (array of Project)
  - `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
  - `number` (integer, read-only): Project number, unique in the tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
  - `warnPercent` (integer): Budget warning from this share (default 80) (max 100)
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "budgetAmount": 22400,
      "budgetMinutes": 9600,
      "budgetState": "ok",
      "createdAt": "2026-11-02T07:30:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
        "name": "Donau Maschinenbau AG"
      },
      "endOn": "2026-11-23",
      "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "number": 1,
      "phase": "active",
      "responsibleName": "Emma Maier",
      "responsibleRef": "emma.maier@muster-it.example",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "spentMinutes": 4260,
      "startOn": "2026-11-02",
      "status": "laufend",
      "title": "ERP-Einführung Donau Maschinenbau",
      "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
      "updatedAt": "2026-11-12T16:00:00Z",
      "version": 6
    }
  ],
  "total": 1
}
```

### Example request

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

## Create a project; it gets the next project number (desk:write)

`POST /api/desk/v1/projects`

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

`spaceId` (the home space, id or key) is required.

### Request body

`application/json` (required)

- `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
- `title` (string, required): Title of the project (max length 200)
- `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
- `budgetAmount` (number, nullable): Budget as a net amount (EUR)
- `budgetMinutes` (integer, nullable): Time budget; the warning uses it
- `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
- `createdAt` (string (date-time), read-only): When the project was created
- `createdBy` (string, read-only): Login (e-mail) of who created the project
- `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
- `customer` (Ref | null): Masterdata customer of the project
- `description` (string): Description of the project
- `endOn` (string (date), nullable): Planned end
- `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
- `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
- `id` (string, read-only): Id of the project
- `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
- `number` (integer, read-only): Project number, unique in the tenant
- `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
- `plannedMinutes` (integer, nullable): Planned effort in minutes
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): Login (e-mail) of the person responsible
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
- `startOn` (string (date), nullable): Planned start
- `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
- `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
- `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
- `updatedAt` (string (date-time), read-only): When the project was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
- `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
- `warnPercent` (integer): Budget warning from this share (default 80) (max 100)

Example:

```json
{
  "budgetMinutes": 2400,
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12",
    "name": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"
  },
  "endOn": "2026-12-19",
  "responsibleRef": "marie.wagner@muster-it.example",
  "spaceId": "PRJ",
  "startOn": "2026-12-01",
  "title": "Microsoft-365-Umstellung Kanzlei Hofmann",
  "warnPercent": 80
}
```

### Responses

- **201** Project (`application/json`)
- **422** Invalid field; `spaceId` is missing, not a space of the tenant, or archived

Fields of the 201 answer:

- `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
- `title` (string, required): Title of the project (max length 200)
- `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
- `budgetAmount` (number, nullable): Budget as a net amount (EUR)
- `budgetMinutes` (integer, nullable): Time budget; the warning uses it
- `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
- `createdAt` (string (date-time), read-only): When the project was created
- `createdBy` (string, read-only): Login (e-mail) of who created the project
- `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
- `customer` (Ref | null): Masterdata customer of the project
- `description` (string): Description of the project
- `endOn` (string (date), nullable): Planned end
- `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
- `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
- `id` (string, read-only): Id of the project
- `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
- `number` (integer, read-only): Project number, unique in the tenant
- `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
- `plannedMinutes` (integer, nullable): Planned effort in minutes
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): Login (e-mail) of the person responsible
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
- `startOn` (string (date), nullable): Planned start
- `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
- `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
- `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
- `updatedAt` (string (date-time), read-only): When the project was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
- `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
- `warnPercent` (integer): Budget warning from this share (default 80) (max 100)

Example 201 answer:

```json
{
  "archived": false,
  "budgetAmount": 22400,
  "budgetMinutes": 9600,
  "budgetState": "ok",
  "createdAt": "2026-11-02T07:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "customFields": {
    "ansprechpartner_kunde": "Stefan Eder (IT-Leiter)",
    "auftragsnummer": "A-2026-0412"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
    "name": "Donau Maschinenbau AG"
  },
  "description": "Einführung der ERP-Lösung bei Donau Maschinenbau am Standort Neutraubling: Installation, Konfiguration, Datenübernahme, Schulung und Produktivstart.",
  "endOn": "2026-11-23",
  "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "itemsByPhase": {
    "active": 3,
    "done": 9,
    "new": 9,
    "waiting": 0
  },
  "number": 1,
  "phase": "active",
  "plannedMinutes": 8400,
  "responsibleName": "Emma Maier",
  "responsibleRef": "emma.maier@muster-it.example",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
  "spentMinutes": 4260,
  "startOn": "2026-11-02",
  "status": "laufend",
  "ticketDisplay": "tickets",
  "title": "ERP-Einführung Donau Maschinenbau",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "updatedAt": "2026-11-12T16:00:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "version": 6,
  "warnPercent": 80
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"budgetMinutes":2400,"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12","name":"Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"},"endOn":"2026-12-19","responsibleRef":"marie.wagner@muster-it.example","spaceId":"PRJ","startOn":"2026-12-01","title":"Microsoft-365-Umstellung Kanzlei Hofmann","warnPercent":80}'
```

## Create a project of a template's type with the template's tasks (desk:write)

`POST /api/desk/v1/projects/from-template`

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

The project gets the template's project type and field values (the request's values win). Task dates count
from `startOn` (else the project's start, else today); the project's start and end default to the plan's.
Tasks are created in the project type's task space with the actor's rights, so creation rules, history and
live updates run as for any ticket; everything is one transaction. `dryRun=true` stores nothing and answers
the plan after checking every task like a real create.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `dryRun` | query | boolean |  |  |

### Request body

`application/json` (required)

- `project` (Project, required)
  - `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
  - `number` (integer, read-only): Project number, unique in the tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
  - `warnPercent` (integer): Budget warning from this share (default 80) (max 100)
- `templateId` (string, required): Id or key
- `startOn` (string (date)): Day the template's offsets count from

Example:

```json
{
  "project": {
    "budgetAmount": 22400,
    "budgetMinutes": 9600,
    "customFields": {
      "auftragsnummer": "A-2026-0412"
    },
    "customer": {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
      "name": "Donau Maschinenbau AG"
    },
    "responsibleRef": "emma.maier@muster-it.example",
    "spaceId": "PRJ",
    "title": "ERP-Einführung Donau Maschinenbau"
  },
  "startOn": "2026-11-02",
  "templateId": "9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01"
}
```

### Responses

- **200** The plan (dryRun) (`application/json`)
- **201** Created (`application/json`)
- **400** Unknown or archived template, invalid project, or a task that cannot be created (the error names the template task)
- **422** A task misses required fields of its type (missing_fields), or the project's `spaceId` is missing, unknown or archived

Fields of the 201 answer:

- `dryRun` (boolean): Only the plan: nothing was created
- `payments` (array of ProjectPayment): The payment plan the template created (not in a dry run)
  - `amount` (number): Net amount or percentage (amountKind)
  - `amountKind` (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of `fixed`, `percent`)
  - `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
  - `document` (object, read-only): The invoice handed to trade (once requested)
  - `dueOn` (string (date), nullable): Due on this date
  - `grossTotal` (number, nullable, read-only): Gross total of the invoice
  - `id` (string, read-only): Id of the payment
  - `invoiceNumber` (string, read-only): Given by trade on release
  - `invoicedOn` (string (date), nullable, read-only): Invoice date
  - `lastError` (string, read-only): Why the last send to trade failed
  - `milestoneId` (string, nullable): Due when this milestone of the project is reached
  - `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
  - `netTotal` (number, nullable, read-only): Net total of the invoice
  - `position` (integer): Position in the payment plan
  - `projectId` (string, read-only): Project of the payment
  - `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
  - `requestedBy` (string, read-only): The person, or system (automatic draft)
  - `role` (string): interim payment or the final payment (one of `interim`, `final`)
  - `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
  - `state` (string, read-only): State of the payment (one of `planned`, `due`, `requested`, `drafted`, `invoiced`, `skipped`)
  - `taxRate` (number): VAT rate in percent (max 100)
  - `title` (string): Title of the payment (invoice line) (max length 200)
  - `tradeTransactionId` (string, read-only): Invoice transaction in trade
  - `version` (integer): Version of the payment; send it back on change
- `project` (Project)
  - `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
  - `number` (integer, read-only): Project number, unique in the tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
  - `warnPercent` (integer): Budget warning from this share (default 80) (max 100)
- `tasks` (array of object): Template tasks placed on the calendar

Example 201 answer:

```json
{
  "dryRun": false,
  "payments": [
    {
      "amount": 30,
      "amountKind": "percent",
      "attempt": 0,
      "dueOn": null,
      "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
      "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
      "net": 6720,
      "position": 0,
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "role": "interim",
      "state": "planned",
      "taxRate": 19,
      "title": "Abschlag nach Konfiguration",
      "version": 1
    }
  ],
  "project": {
    "budgetAmount": 22400,
    "budgetMinutes": 9600,
    "createdAt": "2026-11-02T07:30:00Z",
    "customFields": {
      "auftragsnummer": "A-2026-0412"
    },
    "customer": {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
      "name": "Donau Maschinenbau AG"
    },
    "endOn": "2026-11-22",
    "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
    "number": 1,
    "phase": "new",
    "responsibleName": "Emma Maier",
    "responsibleRef": "emma.maier@muster-it.example",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "startOn": "2026-11-02",
    "status": "geplant",
    "title": "ERP-Einführung Donau Maschinenbau",
    "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
    "updatedAt": "2026-11-02T07:30:00Z",
    "version": 1
  },
  "tasks": [
    {
      "dueOn": "2026-11-04",
      "durationDays": 3,
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d01",
      "itemNumber": 48,
      "key": "installation",
      "offsetDays": 0,
      "startOn": "2026-11-02",
      "title": "Grundinstallation"
    },
    {
      "dueOn": "2026-11-03",
      "durationDays": 2,
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d02",
      "itemNumber": 49,
      "key": "server",
      "milestoneKey": "basis",
      "offsetDays": 0,
      "parentKey": "installation",
      "startOn": "2026-11-02",
      "title": "Server und Datenbank einrichten"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/from-template' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"project":{"budgetAmount":22400,"budgetMinutes":9600,"customFields":{"auftragsnummer":"A-2026-0412"},"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21","name":"Donau Maschinenbau AG"},"responsibleRef":"emma.maier@muster-it.example","spaceId":"PRJ","title":"ERP-Einführung Donau Maschinenbau"},"startOn":"2026-11-02","templateId":"9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01"}'
```

## Create a project type (desk:admin)

`POST /api/desk/v1/project-types`

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

Project types come with the bootstrap (`projectTypes`). Their workflow must be a workflow of scope `project`.

### Request body

`application/json` (required)

- `key` (string, required): Lower-case letters, digits, - or _; fixed
- `name` (string, required): Name of the project type (max length 200)
- `workflowId` (string, required): A workflow of scope project
- `archived` (boolean): Archived: the project type is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the project type
- `description` (string): Description of the project type
- `icon` (string): Icon of the project type
- `id` (string, read-only): Id of the project type
- `layout` (array of LayoutField): Custom fields ("cf.<key>") of the project record; sections facts, main, aside
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `settings` (object): Settings of the project type
  - `billing` (object): Project billing
    - `autoDraft` (boolean): Request a payment (hand its draft to trade) as soon as it is due; default off
    - `hourUnit` (string): No longer used: hourly billing is HR's (ADR 0040); ignored on write and no longer returned (max length 20)
    - `taxRate` (number): VAT rate of new payments (default 19) (max 100)
    - `unit` (string): Unit of the payment invoice lines (default Pauschal) (max length 20)
  - `taskSpaceId` (string): Space template tasks are created in (id or key on input)
  - `taskTypeId` (string): Item type of template tasks that name none (id or key on input)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the project type; send it back on change (409 version_conflict when it is outdated)

Example:

```json
{
  "archived": false,
  "color": "primary",
  "description": "Projekt mit Meilensteinen, Zeitplan und Abrechnung nach Zahlungsplan",
  "icon": "i-lucide-briefcase",
  "id": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "key": "kundenprojekt",
  "layout": [
    {
      "key": "cf.auftragsnummer",
      "section": "facts"
    },
    {
      "key": "cf.ansprechpartner_kunde",
      "section": "facts"
    }
  ],
  "name": "Kundenprojekt",
  "settings": {
    "billing": {
      "autoDraft": false,
      "taxRate": 19,
      "unit": "Pauschal"
    },
    "taskSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "taskTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
  },
  "sortOrder": 1,
  "version": 1,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e03"
}
```

### Responses

- **201** Project type (`application/json`)

Fields of the 201 answer:

- `key` (string, required): Lower-case letters, digits, - or _; fixed
- `name` (string, required): Name of the project type (max length 200)
- `workflowId` (string, required): A workflow of scope project
- `archived` (boolean): Archived: the project type is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the project type
- `description` (string): Description of the project type
- `icon` (string): Icon of the project type
- `id` (string, read-only): Id of the project type
- `layout` (array of LayoutField): Custom fields ("cf.<key>") of the project record; sections facts, main, aside
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `settings` (object): Settings of the project type
  - `billing` (object): Project billing
    - `autoDraft` (boolean): Request a payment (hand its draft to trade) as soon as it is due; default off
    - `hourUnit` (string): No longer used: hourly billing is HR's (ADR 0040); ignored on write and no longer returned (max length 20)
    - `taxRate` (number): VAT rate of new payments (default 19) (max 100)
    - `unit` (string): Unit of the payment invoice lines (default Pauschal) (max length 20)
  - `taskSpaceId` (string): Space template tasks are created in (id or key on input)
  - `taskTypeId` (string): Item type of template tasks that name none (id or key on input)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the project type; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "archived": false,
  "color": "primary",
  "description": "Projekt mit Meilensteinen, Zeitplan und Abrechnung nach Zahlungsplan",
  "icon": "i-lucide-briefcase",
  "id": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "key": "kundenprojekt",
  "layout": [
    {
      "key": "cf.auftragsnummer",
      "section": "facts"
    },
    {
      "key": "cf.ansprechpartner_kunde",
      "section": "facts"
    }
  ],
  "name": "Kundenprojekt",
  "settings": {
    "billing": {
      "autoDraft": false,
      "taxRate": 19,
      "unit": "Pauschal"
    },
    "taskSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "taskTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
  },
  "sortOrder": 1,
  "version": 1,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e03"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/project-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"color":"primary","description":"Projekt mit Meilensteinen, Zeitplan und Abrechnung nach Zahlungsplan","icon":"i-lucide-briefcase","id":"6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01","key":"kundenprojekt","layout":[{"key":"cf.auftragsnummer","section":"facts"},{"key":"cf.ansprechpartner_kunde","section":"facts"}],"name":"Kundenprojekt","settings":{"billing":{"autoDraft":false,"taxRate":19,"unit":"Pauschal"},"taskSpaceId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00","taskTypeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"},"sortOrder":1,"version":1,"workflowId":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e03"}'
```

## Change a project type at its version; key stays, the workflow stays while the type has projects (desk:admin)

`PUT /api/desk/v1/project-types/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Lower-case letters, digits, - or _; fixed
- `name` (string, required): Name of the project type (max length 200)
- `workflowId` (string, required): A workflow of scope project
- `archived` (boolean): Archived: the project type is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the project type
- `description` (string): Description of the project type
- `icon` (string): Icon of the project type
- `id` (string, read-only): Id of the project type
- `layout` (array of LayoutField): Custom fields ("cf.<key>") of the project record; sections facts, main, aside
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `settings` (object): Settings of the project type
  - `billing` (object): Project billing
    - `autoDraft` (boolean): Request a payment (hand its draft to trade) as soon as it is due; default off
    - `hourUnit` (string): No longer used: hourly billing is HR's (ADR 0040); ignored on write and no longer returned (max length 20)
    - `taxRate` (number): VAT rate of new payments (default 19) (max 100)
    - `unit` (string): Unit of the payment invoice lines (default Pauschal) (max length 20)
  - `taskSpaceId` (string): Space template tasks are created in (id or key on input)
  - `taskTypeId` (string): Item type of template tasks that name none (id or key on input)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the project type; send it back on change (409 version_conflict when it is outdated)

Example:

```json
{
  "archived": false,
  "color": "primary",
  "description": "Projekt mit Meilensteinen, Zeitplan und Abrechnung nach Zahlungsplan",
  "icon": "i-lucide-briefcase",
  "id": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "key": "kundenprojekt",
  "layout": [
    {
      "key": "cf.auftragsnummer",
      "section": "facts"
    },
    {
      "key": "cf.ansprechpartner_kunde",
      "section": "facts"
    }
  ],
  "name": "Kundenprojekt",
  "settings": {
    "billing": {
      "autoDraft": false,
      "taxRate": 19,
      "unit": "Pauschal"
    },
    "taskSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "taskTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
  },
  "sortOrder": 1,
  "version": 1,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e03"
}
```

### Responses

- **200** Project type (`application/json`)
- **409** Version conflict, or the type has projects and its workflow would change (in_use)

Fields of the 200 answer:

- `key` (string, required): Lower-case letters, digits, - or _; fixed
- `name` (string, required): Name of the project type (max length 200)
- `workflowId` (string, required): A workflow of scope project
- `archived` (boolean): Archived: the project type is kept for existing data but no longer offered in pickers
- `color` (string): Display color of the project type
- `description` (string): Description of the project type
- `icon` (string): Icon of the project type
- `id` (string, read-only): Id of the project type
- `layout` (array of LayoutField): Custom fields ("cf.<key>") of the project record; sections facts, main, aside
  - `key` (string, required): System field (priority, dueAt, customer, …) or "cf.<key>"
  - `required` (boolean): The field must be filled
  - `section` (string): Section of the record page the field is shown in (one of `facts`, `main`, `aside`, `closure`)
- `settings` (object): Settings of the project type
  - `billing` (object): Project billing
    - `autoDraft` (boolean): Request a payment (hand its draft to trade) as soon as it is due; default off
    - `hourUnit` (string): No longer used: hourly billing is HR's (ADR 0040); ignored on write and no longer returned (max length 20)
    - `taxRate` (number): VAT rate of new payments (default 19) (max 100)
    - `unit` (string): Unit of the payment invoice lines (default Pauschal) (max length 20)
  - `taskSpaceId` (string): Space template tasks are created in (id or key on input)
  - `taskTypeId` (string): Item type of template tasks that name none (id or key on input)
- `sortOrder` (integer): Position in lists (ascending)
- `version` (integer): Version of the project type; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "archived": false,
  "color": "primary",
  "description": "Projekt mit Meilensteinen, Zeitplan und Abrechnung nach Zahlungsplan",
  "icon": "i-lucide-briefcase",
  "id": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "key": "kundenprojekt",
  "layout": [
    {
      "key": "cf.auftragsnummer",
      "section": "facts"
    },
    {
      "key": "cf.ansprechpartner_kunde",
      "section": "facts"
    }
  ],
  "name": "Kundenprojekt",
  "settings": {
    "billing": {
      "autoDraft": false,
      "taxRate": 19,
      "unit": "Pauschal"
    },
    "taskSpaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "taskTypeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
  },
  "sortOrder": 1,
  "version": 1,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e03"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/project-types/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"color":"primary","description":"Projekt mit Meilensteinen, Zeitplan und Abrechnung nach Zahlungsplan","icon":"i-lucide-briefcase","id":"6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01","key":"kundenprojekt","layout":[{"key":"cf.auftragsnummer","section":"facts"},{"key":"cf.ansprechpartner_kunde","section":"facts"}],"name":"Kundenprojekt","settings":{"billing":{"autoDraft":false,"taxRate":19,"unit":"Pauschal"},"taskSpaceId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00","taskTypeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"},"sortOrder":1,"version":1,"workflowId":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e03"}'
```

## Create a template of a project type (desk:admin)

`POST /api/desk/v1/project-templates`

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

Templates come with the bootstrap (`projectTemplates`).

### Request body

`application/json` (required)

- `key` (string, required): Key of the template, unique in the tenant
- `name` (string, required): Name of the template (max length 200)
- `typeId` (string, required): Project type (id or key on input); fixed
- `archived` (boolean): Archived: the template is kept for existing data but no longer offered in pickers
- `blueprint` (object): What a project made from the template gets
  - `dependencies` (array of object): Finish-to-start between tasks (keys); no cycles
    - `from` (string, required): Key of the task that has to end first
    - `to` (string, required): Key of the task that starts after it
    - `lagDays` (integer): Days between the end of from and the start of to (max 365)
  - `fields` (object): Custom field values of new projects
  - `milestones` (array of object): Milestones of the new project
    - `key` (string, required): Key of the milestone in the template
    - `title` (string, required): Title of the milestone
    - `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
    - `offsetDays` (integer): Due this many days after the project start (max 3650)
  - `payments` (array of object): The payment plan of new projects (one final payment)
    - `amount` (number, required): Net amount or percentage (amountKind)
    - `role` (string, required): interim payment or the final payment (one of `interim`, `final`)
    - `title` (string, required): Title of the payment
    - `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
    - `milestoneKey` (string): A milestone of the template that makes it due
    - `taxRate` (number): VAT rate in percent
  - `tasks` (array of BlueprintTask): Tasks: items of the new project
    - `key` (string, required): Key of the task in the template (referenced by dependencies) (max length 64)
    - `title` (string, required): Title of the item the task creates (max length 200)
    - `description` (string): Description of the item the task creates
    - `durationDays` (integer): Calendar days including the first; 0 and 1 are one day (max 3650)
    - `estimateMinutes` (integer, nullable): Estimate of the created item in minutes
    - `milestoneKey` (string): A milestone of the template the task counts for
    - `offsetDays` (integer): Days after the project start (max 3650)
    - `parentKey` (string): An earlier task; its type is on a higher level than this task's
    - `typeId` (string): Item type (id or key); empty uses the project type's task type
- `description` (string): Description of the template
- `id` (string, read-only): Id of the template
- `version` (integer): Version of the template; send it back on change (409 version_conflict when it is outdated)

Example:

```json
{
  "archived": false,
  "blueprint": {
    "dependencies": [
      {
        "from": "server",
        "lagDays": 0,
        "to": "software"
      },
      {
        "from": "software",
        "lagDays": 4,
        "to": "start"
      }
    ],
    "fields": {},
    "milestones": [
      {
        "completion": "items",
        "key": "basis",
        "offsetDays": 2,
        "title": "Grundinstallation abgeschlossen"
      },
      {
        "completion": "manual",
        "key": "live",
        "offsetDays": 20,
        "title": "Go-live"
      }
    ],
    "payments": [
      {
        "amount": 30,
        "amountKind": "percent",
        "milestoneKey": "basis",
        "role": "interim",
        "title": "Abschlag nach Grundinstallation"
      },
      {
        "amount": 70,
        "amountKind": "percent",
        "milestoneKey": "live",
        "role": "final",
        "title": "Schlussrechnung"
      }
    ],
    "tasks": [
      {
        "durationDays": 3,
        "key": "installation",
        "offsetDays": 0,
        "title": "Grundinstallation",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06"
      },
      {
        "durationDays": 2,
        "key": "server",
        "milestoneKey": "basis",
        "offsetDays": 0,
        "parentKey": "installation",
        "title": "Server und Datenbank einrichten",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "software",
        "milestoneKey": "basis",
        "offsetDays": 2,
        "parentKey": "installation",
        "title": "Software installieren und lizenzieren",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "start",
        "milestoneKey": "live",
        "offsetDays": 18,
        "title": "Produktivstart",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      }
    ]
  },
  "description": "Vier Wochen: Installation, Konfiguration, Datenübernahme, Schnittstellen, Schulung und Go-live.",
  "id": "9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01",
  "key": "erp-einfuehrung",
  "name": "ERP-Einführung",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "version": 2
}
```

### Responses

- **201** Template (`application/json`)

Fields of the 201 answer:

- `key` (string, required): Key of the template, unique in the tenant
- `name` (string, required): Name of the template (max length 200)
- `typeId` (string, required): Project type (id or key on input); fixed
- `archived` (boolean): Archived: the template is kept for existing data but no longer offered in pickers
- `blueprint` (object): What a project made from the template gets
  - `dependencies` (array of object): Finish-to-start between tasks (keys); no cycles
    - `from` (string, required): Key of the task that has to end first
    - `to` (string, required): Key of the task that starts after it
    - `lagDays` (integer): Days between the end of from and the start of to (max 365)
  - `fields` (object): Custom field values of new projects
  - `milestones` (array of object): Milestones of the new project
    - `key` (string, required): Key of the milestone in the template
    - `title` (string, required): Title of the milestone
    - `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
    - `offsetDays` (integer): Due this many days after the project start (max 3650)
  - `payments` (array of object): The payment plan of new projects (one final payment)
    - `amount` (number, required): Net amount or percentage (amountKind)
    - `role` (string, required): interim payment or the final payment (one of `interim`, `final`)
    - `title` (string, required): Title of the payment
    - `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
    - `milestoneKey` (string): A milestone of the template that makes it due
    - `taxRate` (number): VAT rate in percent
  - `tasks` (array of BlueprintTask): Tasks: items of the new project
    - `key` (string, required): Key of the task in the template (referenced by dependencies) (max length 64)
    - `title` (string, required): Title of the item the task creates (max length 200)
    - `description` (string): Description of the item the task creates
    - `durationDays` (integer): Calendar days including the first; 0 and 1 are one day (max 3650)
    - `estimateMinutes` (integer, nullable): Estimate of the created item in minutes
    - `milestoneKey` (string): A milestone of the template the task counts for
    - `offsetDays` (integer): Days after the project start (max 3650)
    - `parentKey` (string): An earlier task; its type is on a higher level than this task's
    - `typeId` (string): Item type (id or key); empty uses the project type's task type
- `description` (string): Description of the template
- `id` (string, read-only): Id of the template
- `version` (integer): Version of the template; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "archived": false,
  "blueprint": {
    "dependencies": [
      {
        "from": "server",
        "lagDays": 0,
        "to": "software"
      },
      {
        "from": "software",
        "lagDays": 4,
        "to": "start"
      }
    ],
    "fields": {},
    "milestones": [
      {
        "completion": "items",
        "key": "basis",
        "offsetDays": 2,
        "title": "Grundinstallation abgeschlossen"
      },
      {
        "completion": "manual",
        "key": "live",
        "offsetDays": 20,
        "title": "Go-live"
      }
    ],
    "payments": [
      {
        "amount": 30,
        "amountKind": "percent",
        "milestoneKey": "basis",
        "role": "interim",
        "title": "Abschlag nach Grundinstallation"
      },
      {
        "amount": 70,
        "amountKind": "percent",
        "milestoneKey": "live",
        "role": "final",
        "title": "Schlussrechnung"
      }
    ],
    "tasks": [
      {
        "durationDays": 3,
        "key": "installation",
        "offsetDays": 0,
        "title": "Grundinstallation",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06"
      },
      {
        "durationDays": 2,
        "key": "server",
        "milestoneKey": "basis",
        "offsetDays": 0,
        "parentKey": "installation",
        "title": "Server und Datenbank einrichten",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "software",
        "milestoneKey": "basis",
        "offsetDays": 2,
        "parentKey": "installation",
        "title": "Software installieren und lizenzieren",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "start",
        "milestoneKey": "live",
        "offsetDays": 18,
        "title": "Produktivstart",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      }
    ]
  },
  "description": "Vier Wochen: Installation, Konfiguration, Datenübernahme, Schnittstellen, Schulung und Go-live.",
  "id": "9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01",
  "key": "erp-einfuehrung",
  "name": "ERP-Einführung",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/project-templates' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"blueprint":{"dependencies":[{"from":"server","lagDays":0,"to":"software"},{"from":"software","lagDays":4,"to":"start"}],"fields":{},"milestones":[{"completion":"items","key":"basis","offsetDays":2,"title":"Grundinstallation abgeschlossen"},{"completion":"manual","key":"live","offsetDays":20,"title":"Go-live"}],"payments":[{"amount":30,"amountKind":"percent","milestoneKey":"basis","role":"interim","title":"Abschlag nach Grundinstallation"},{"amount":70,"amountKind":"percent","milestoneKey":"live","role":"final","title":"Schlussrechnung"}],"tasks":[{"durationDays":3,"key":"installation","offsetDays":0,"title":"Grundinstallation","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06"},{"durationDays":2,"key":"server","milestoneKey":"basis","offsetDays":0,"parentKey":"installation","title":"Server und Datenbank einrichten","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"},{"durationDays":1,"key":"software","milestoneKey":"basis","offsetDays":2,"parentKey":"installation","title":"Software installieren und lizenzieren","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"},{"durationDays":1,"key":"start","milestoneKey":"live","offsetDays":18,"title":"Produktivstart","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"}]},"description":"Vier Wochen: Installation, Konfiguration, Datenübernahme, Schnittstellen, Schulung und Go-live.","id":"9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01","key":"erp-einfuehrung","name":"ERP-Einführung","typeId":"6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01","version":2}'
```

## Change a template at its version; key and project type stay (desk:admin)

`PUT /api/desk/v1/project-templates/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string, required): Key of the template, unique in the tenant
- `name` (string, required): Name of the template (max length 200)
- `typeId` (string, required): Project type (id or key on input); fixed
- `archived` (boolean): Archived: the template is kept for existing data but no longer offered in pickers
- `blueprint` (object): What a project made from the template gets
  - `dependencies` (array of object): Finish-to-start between tasks (keys); no cycles
    - `from` (string, required): Key of the task that has to end first
    - `to` (string, required): Key of the task that starts after it
    - `lagDays` (integer): Days between the end of from and the start of to (max 365)
  - `fields` (object): Custom field values of new projects
  - `milestones` (array of object): Milestones of the new project
    - `key` (string, required): Key of the milestone in the template
    - `title` (string, required): Title of the milestone
    - `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
    - `offsetDays` (integer): Due this many days after the project start (max 3650)
  - `payments` (array of object): The payment plan of new projects (one final payment)
    - `amount` (number, required): Net amount or percentage (amountKind)
    - `role` (string, required): interim payment or the final payment (one of `interim`, `final`)
    - `title` (string, required): Title of the payment
    - `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
    - `milestoneKey` (string): A milestone of the template that makes it due
    - `taxRate` (number): VAT rate in percent
  - `tasks` (array of BlueprintTask): Tasks: items of the new project
    - `key` (string, required): Key of the task in the template (referenced by dependencies) (max length 64)
    - `title` (string, required): Title of the item the task creates (max length 200)
    - `description` (string): Description of the item the task creates
    - `durationDays` (integer): Calendar days including the first; 0 and 1 are one day (max 3650)
    - `estimateMinutes` (integer, nullable): Estimate of the created item in minutes
    - `milestoneKey` (string): A milestone of the template the task counts for
    - `offsetDays` (integer): Days after the project start (max 3650)
    - `parentKey` (string): An earlier task; its type is on a higher level than this task's
    - `typeId` (string): Item type (id or key); empty uses the project type's task type
- `description` (string): Description of the template
- `id` (string, read-only): Id of the template
- `version` (integer): Version of the template; send it back on change (409 version_conflict when it is outdated)

Example:

```json
{
  "archived": false,
  "blueprint": {
    "dependencies": [
      {
        "from": "server",
        "lagDays": 0,
        "to": "software"
      },
      {
        "from": "software",
        "lagDays": 4,
        "to": "start"
      }
    ],
    "fields": {},
    "milestones": [
      {
        "completion": "items",
        "key": "basis",
        "offsetDays": 2,
        "title": "Grundinstallation abgeschlossen"
      },
      {
        "completion": "manual",
        "key": "live",
        "offsetDays": 20,
        "title": "Go-live"
      }
    ],
    "payments": [
      {
        "amount": 30,
        "amountKind": "percent",
        "milestoneKey": "basis",
        "role": "interim",
        "title": "Abschlag nach Grundinstallation"
      },
      {
        "amount": 70,
        "amountKind": "percent",
        "milestoneKey": "live",
        "role": "final",
        "title": "Schlussrechnung"
      }
    ],
    "tasks": [
      {
        "durationDays": 3,
        "key": "installation",
        "offsetDays": 0,
        "title": "Grundinstallation",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06"
      },
      {
        "durationDays": 2,
        "key": "server",
        "milestoneKey": "basis",
        "offsetDays": 0,
        "parentKey": "installation",
        "title": "Server und Datenbank einrichten",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "software",
        "milestoneKey": "basis",
        "offsetDays": 2,
        "parentKey": "installation",
        "title": "Software installieren und lizenzieren",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "start",
        "milestoneKey": "live",
        "offsetDays": 18,
        "title": "Produktivstart",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      }
    ]
  },
  "description": "Vier Wochen: Installation, Konfiguration, Datenübernahme, Schnittstellen, Schulung und Go-live.",
  "id": "9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01",
  "key": "erp-einfuehrung",
  "name": "ERP-Einführung",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "version": 2
}
```

### Responses

- **200** Template (`application/json`)
- **409** Version conflict

Fields of the 200 answer:

- `key` (string, required): Key of the template, unique in the tenant
- `name` (string, required): Name of the template (max length 200)
- `typeId` (string, required): Project type (id or key on input); fixed
- `archived` (boolean): Archived: the template is kept for existing data but no longer offered in pickers
- `blueprint` (object): What a project made from the template gets
  - `dependencies` (array of object): Finish-to-start between tasks (keys); no cycles
    - `from` (string, required): Key of the task that has to end first
    - `to` (string, required): Key of the task that starts after it
    - `lagDays` (integer): Days between the end of from and the start of to (max 365)
  - `fields` (object): Custom field values of new projects
  - `milestones` (array of object): Milestones of the new project
    - `key` (string, required): Key of the milestone in the template
    - `title` (string, required): Title of the milestone
    - `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
    - `offsetDays` (integer): Due this many days after the project start (max 3650)
  - `payments` (array of object): The payment plan of new projects (one final payment)
    - `amount` (number, required): Net amount or percentage (amountKind)
    - `role` (string, required): interim payment or the final payment (one of `interim`, `final`)
    - `title` (string, required): Title of the payment
    - `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
    - `milestoneKey` (string): A milestone of the template that makes it due
    - `taxRate` (number): VAT rate in percent
  - `tasks` (array of BlueprintTask): Tasks: items of the new project
    - `key` (string, required): Key of the task in the template (referenced by dependencies) (max length 64)
    - `title` (string, required): Title of the item the task creates (max length 200)
    - `description` (string): Description of the item the task creates
    - `durationDays` (integer): Calendar days including the first; 0 and 1 are one day (max 3650)
    - `estimateMinutes` (integer, nullable): Estimate of the created item in minutes
    - `milestoneKey` (string): A milestone of the template the task counts for
    - `offsetDays` (integer): Days after the project start (max 3650)
    - `parentKey` (string): An earlier task; its type is on a higher level than this task's
    - `typeId` (string): Item type (id or key); empty uses the project type's task type
- `description` (string): Description of the template
- `id` (string, read-only): Id of the template
- `version` (integer): Version of the template; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "archived": false,
  "blueprint": {
    "dependencies": [
      {
        "from": "server",
        "lagDays": 0,
        "to": "software"
      },
      {
        "from": "software",
        "lagDays": 4,
        "to": "start"
      }
    ],
    "fields": {},
    "milestones": [
      {
        "completion": "items",
        "key": "basis",
        "offsetDays": 2,
        "title": "Grundinstallation abgeschlossen"
      },
      {
        "completion": "manual",
        "key": "live",
        "offsetDays": 20,
        "title": "Go-live"
      }
    ],
    "payments": [
      {
        "amount": 30,
        "amountKind": "percent",
        "milestoneKey": "basis",
        "role": "interim",
        "title": "Abschlag nach Grundinstallation"
      },
      {
        "amount": 70,
        "amountKind": "percent",
        "milestoneKey": "live",
        "role": "final",
        "title": "Schlussrechnung"
      }
    ],
    "tasks": [
      {
        "durationDays": 3,
        "key": "installation",
        "offsetDays": 0,
        "title": "Grundinstallation",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06"
      },
      {
        "durationDays": 2,
        "key": "server",
        "milestoneKey": "basis",
        "offsetDays": 0,
        "parentKey": "installation",
        "title": "Server und Datenbank einrichten",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "software",
        "milestoneKey": "basis",
        "offsetDays": 2,
        "parentKey": "installation",
        "title": "Software installieren und lizenzieren",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      },
      {
        "durationDays": 1,
        "key": "start",
        "milestoneKey": "live",
        "offsetDays": 18,
        "title": "Produktivstart",
        "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"
      }
    ]
  },
  "description": "Vier Wochen: Installation, Konfiguration, Datenübernahme, Schnittstellen, Schulung und Go-live.",
  "id": "9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01",
  "key": "erp-einfuehrung",
  "name": "ERP-Einführung",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/project-templates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"blueprint":{"dependencies":[{"from":"server","lagDays":0,"to":"software"},{"from":"software","lagDays":4,"to":"start"}],"fields":{},"milestones":[{"completion":"items","key":"basis","offsetDays":2,"title":"Grundinstallation abgeschlossen"},{"completion":"manual","key":"live","offsetDays":20,"title":"Go-live"}],"payments":[{"amount":30,"amountKind":"percent","milestoneKey":"basis","role":"interim","title":"Abschlag nach Grundinstallation"},{"amount":70,"amountKind":"percent","milestoneKey":"live","role":"final","title":"Schlussrechnung"}],"tasks":[{"durationDays":3,"key":"installation","offsetDays":0,"title":"Grundinstallation","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06"},{"durationDays":2,"key":"server","milestoneKey":"basis","offsetDays":0,"parentKey":"installation","title":"Server und Datenbank einrichten","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"},{"durationDays":1,"key":"software","milestoneKey":"basis","offsetDays":2,"parentKey":"installation","title":"Software installieren und lizenzieren","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"},{"durationDays":1,"key":"start","milestoneKey":"live","offsetDays":18,"title":"Produktivstart","typeId":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07"}]},"description":"Vier Wochen: Installation, Konfiguration, Datenübernahme, Schnittstellen, Schulung und Go-live.","id":"9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01","key":"erp-einfuehrung","name":"ERP-Einführung","typeId":"6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01","version":2}'
```

## A project by id or number (desk:read)

`GET /api/desk/v1/projects/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Id or number |

### Responses

- **200** Project (`application/json`)

Fields of the 200 answer:

- `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
- `title` (string, required): Title of the project (max length 200)
- `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
- `budgetAmount` (number, nullable): Budget as a net amount (EUR)
- `budgetMinutes` (integer, nullable): Time budget; the warning uses it
- `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
- `createdAt` (string (date-time), read-only): When the project was created
- `createdBy` (string, read-only): Login (e-mail) of who created the project
- `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
- `customer` (Ref | null): Masterdata customer of the project
- `description` (string): Description of the project
- `endOn` (string (date), nullable): Planned end
- `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
- `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
- `id` (string, read-only): Id of the project
- `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
- `number` (integer, read-only): Project number, unique in the tenant
- `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
- `plannedMinutes` (integer, nullable): Planned effort in minutes
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): Login (e-mail) of the person responsible
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
- `startOn` (string (date), nullable): Planned start
- `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
- `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
- `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
- `updatedAt` (string (date-time), read-only): When the project was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
- `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
- `warnPercent` (integer): Budget warning from this share (default 80) (max 100)

Example 200 answer:

```json
{
  "archived": false,
  "budgetAmount": 22400,
  "budgetMinutes": 9600,
  "budgetState": "ok",
  "createdAt": "2026-11-02T07:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "customFields": {
    "ansprechpartner_kunde": "Stefan Eder (IT-Leiter)",
    "auftragsnummer": "A-2026-0412"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
    "name": "Donau Maschinenbau AG"
  },
  "description": "Einführung der ERP-Lösung bei Donau Maschinenbau am Standort Neutraubling: Installation, Konfiguration, Datenübernahme, Schulung und Produktivstart.",
  "endOn": "2026-11-23",
  "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "itemsByPhase": {
    "active": 3,
    "done": 9,
    "new": 9,
    "waiting": 0
  },
  "number": 1,
  "phase": "active",
  "plannedMinutes": 8400,
  "responsibleName": "Emma Maier",
  "responsibleRef": "emma.maier@muster-it.example",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
  "spentMinutes": 4260,
  "startOn": "2026-11-02",
  "status": "laufend",
  "ticketDisplay": "tickets",
  "title": "ERP-Einführung Donau Maschinenbau",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "updatedAt": "2026-11-12T16:00:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "version": 6,
  "warnPercent": 80
}
```

### Example request

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

## Change a project at its version; archived: true takes it out of pickers (desk:write)

`PUT /api/desk/v1/projects/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

### Request body

`application/json` (required)

- `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
- `title` (string, required): Title of the project (max length 200)
- `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
- `budgetAmount` (number, nullable): Budget as a net amount (EUR)
- `budgetMinutes` (integer, nullable): Time budget; the warning uses it
- `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
- `createdAt` (string (date-time), read-only): When the project was created
- `createdBy` (string, read-only): Login (e-mail) of who created the project
- `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
- `customer` (Ref | null): Masterdata customer of the project
- `description` (string): Description of the project
- `endOn` (string (date), nullable): Planned end
- `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
- `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
- `id` (string, read-only): Id of the project
- `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
- `number` (integer, read-only): Project number, unique in the tenant
- `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
- `plannedMinutes` (integer, nullable): Planned effort in minutes
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): Login (e-mail) of the person responsible
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
- `startOn` (string (date), nullable): Planned start
- `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
- `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
- `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
- `updatedAt` (string (date-time), read-only): When the project was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
- `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
- `warnPercent` (integer): Budget warning from this share (default 80) (max 100)

Example:

```json
{
  "budgetMinutes": 10200,
  "endOn": "2026-11-27",
  "spaceId": "PRJ",
  "status": "laufend",
  "title": "ERP-Einführung Donau Maschinenbau",
  "version": 6
}
```

### Responses

- **200** Project (`application/json`)
- **409** Version conflict
- **422** Invalid field; `spaceId` is missing, not a space of the tenant, or a move into an archived space (a project staying in its later-archived space stays editable)

Fields of the 200 answer:

- `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
- `title` (string, required): Title of the project (max length 200)
- `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
- `budgetAmount` (number, nullable): Budget as a net amount (EUR)
- `budgetMinutes` (integer, nullable): Time budget; the warning uses it
- `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
- `createdAt` (string (date-time), read-only): When the project was created
- `createdBy` (string, read-only): Login (e-mail) of who created the project
- `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
- `customer` (Ref | null): Masterdata customer of the project
- `description` (string): Description of the project
- `endOn` (string (date), nullable): Planned end
- `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
- `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
- `id` (string, read-only): Id of the project
- `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
- `number` (integer, read-only): Project number, unique in the tenant
- `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
- `plannedMinutes` (integer, nullable): Planned effort in minutes
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): Login (e-mail) of the person responsible
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
- `startOn` (string (date), nullable): Planned start
- `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
- `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
- `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
- `updatedAt` (string (date-time), read-only): When the project was last changed
- `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
- `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
- `warnPercent` (integer): Budget warning from this share (default 80) (max 100)

Example 200 answer:

```json
{
  "archived": false,
  "budgetAmount": 22400,
  "budgetMinutes": 9600,
  "budgetState": "ok",
  "createdAt": "2026-11-02T07:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "customFields": {
    "ansprechpartner_kunde": "Stefan Eder (IT-Leiter)",
    "auftragsnummer": "A-2026-0412"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
    "name": "Donau Maschinenbau AG"
  },
  "description": "Einführung der ERP-Lösung bei Donau Maschinenbau am Standort Neutraubling: Installation, Konfiguration, Datenübernahme, Schulung und Produktivstart.",
  "endOn": "2026-11-23",
  "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "itemsByPhase": {
    "active": 3,
    "done": 9,
    "new": 9,
    "waiting": 0
  },
  "number": 1,
  "phase": "active",
  "plannedMinutes": 8400,
  "responsibleName": "Emma Maier",
  "responsibleRef": "emma.maier@muster-it.example",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
  "spentMinutes": 4260,
  "startOn": "2026-11-02",
  "status": "laufend",
  "ticketDisplay": "tickets",
  "title": "ERP-Einführung Donau Maschinenbau",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "updatedAt": "2026-11-12T16:00:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "version": 6,
  "warnPercent": 80
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/projects/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"budgetMinutes":10200,"endOn":"2026-11-27","spaceId":"PRJ","status":"laufend","title":"ERP-Einführung Donau Maschinenbau","version":6}'
```

## The plan of a project: its items, milestones, dependencies and findings (desk:read)

`GET /api/desk/v1/projects/{id}/plan`

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

Items the caller does not see are left out, and so are dependencies to them. Findings flag delays and conflicts as of today; nothing is moved – reschedule an item with PATCH /items/{ref} (startOn, dueAt) at its version.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Id or number |

### Responses

- **200** Plan (`application/json`)

Fields of the 200 answer:

- `dependencies` (array of ItemDependency): Only between visible items
  - `createdAt` (string (date-time), read-only): When it was created
  - `createdBy` (string, read-only): Login (e-mail) of who created it
  - `id` (string, read-only): Id of the dependency
  - `kind` (string): Kind of dependency (one of `finish_to_start`)
  - `lagDays` (integer): Days between the predecessor's end and the successor's start; negative = overlap (max 365)
  - `predecessorId` (string): Item that has to end first
  - `projectId` (string, read-only): Project of the dependency
  - `successorId` (string): Starts lagDays after the predecessor ended (finish-to-start)
- `findings` (array of PlanFinding): What the plan flags
  - `days` (integer): By how many days (conflict, late, at_risk)
  - `dependencyId` (string): Dependency concerned
  - `itemId` (string): Item concerned
  - `kind` (string): What the plan flags (one of `conflict`, `late`, `blocked`, `at_risk`, `milestone_late`, `undated`)
  - `milestoneId` (string): Milestone concerned
- `items` (array of object): The project's items the caller sees; endOn is the date of the due date (Europe/Berlin)
  - `assignees` (array of object): People working on the item
  - `endOn` (string (date), nullable): End of the item
  - `estimateMinutes` (integer, nullable): Estimate in minutes
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `parentId` (string, nullable): Parent item
  - `phase` (string): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `projectMilestoneId` (string, nullable): Milestone of the item
  - `spaceId` (string): Space of the item
  - `spentMinutes` (integer, nullable): Work HR booked on the ticket; null when HR does not answer
  - `startOn` (string (date), nullable): Start of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
  - `version` (integer): Send it when rescheduling through PATCH /items/{ref}
- `milestones` (array of ProjectMilestone): Milestones of the project
  - `achievedAt` (string (date-time), nullable, read-only): When the milestone was reached
  - `achievedBy` (string, read-only): The person, or system for completion by items
  - `completion` (string): manual: achieved by hand; items: reached once all its items are done (and open again when one reopens) (one of `manual`, `items`)
  - `contractId` (string, read-only): Contract of a contract batch (empty otherwise)
  - `customerId` (string, read-only): The invoice's customer
  - `description` (string): Description of the milestone
  - `dueOn` (string (date)): Due date
  - `id` (string, read-only): Id of the milestone
  - `items` (integer, read-only): Visible items of the milestone (plan only)
  - `itemsDone` (integer, read-only): Visible items of the milestone that are done (plan only)
  - `label` (string, read-only): The unit as the invoice names it (project, contract, customer name)
  - `position` (integer): Position among the project's milestones
  - `projectId` (string, read-only): Project of a project batch (empty otherwise)
  - `scope` (string, read-only): (one of `project`, `contract`, `customer`)
  - `title` (string): Title of the milestone (max length 200)
  - `version` (integer): Version of the milestone; send it back on change
- `project` (Project)
  - `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
  - `number` (integer, read-only): Project number, unique in the tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
  - `warnPercent` (integer): Budget warning from this share (default 80) (max 100)
- `today` (string (date)): The day the findings are computed for (Europe/Berlin)

Example 200 answer:

```json
{
  "dependencies": [
    {
      "createdAt": "2026-11-02T07:30:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "id": "8e5f6a7b-9c0d-4e1f-8a3b-5c6d7e8f9a01",
      "kind": "finish_to_start",
      "lagDays": 1,
      "predecessorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "successorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0c"
    }
  ],
  "findings": [
    {
      "days": 5,
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "kind": "late"
    },
    {
      "days": 3,
      "kind": "milestone_late",
      "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03"
    }
  ],
  "items": [
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "emma.maier@muster-it.example"
        }
      ],
      "endOn": "2026-11-15",
      "estimateMinutes": null,
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d09",
      "number": 56,
      "parentId": null,
      "phase": "active",
      "projectMilestoneId": null,
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "spentMinutes": 600,
      "startOn": "2026-11-10",
      "status": "in_arbeit",
      "title": "Datenübernahme",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06",
      "version": 3
    },
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "paul.schmid@muster-it.example"
        }
      ],
      "endOn": "2026-11-13",
      "estimateMinutes": 480,
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "number": 58,
      "parentId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d09",
      "phase": "active",
      "projectMilestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "spentMinutes": 540,
      "startOn": "2026-11-12",
      "status": "in_arbeit",
      "title": "Probeimport und Prüfung",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07",
      "version": 4
    }
  ],
  "milestones": [
    {
      "achievedAt": null,
      "completion": "items",
      "dueOn": "2026-11-15",
      "id": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
      "items": 3,
      "itemsDone": 1,
      "position": 2,
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "scope": "project",
      "title": "Daten übernommen",
      "version": 1
    }
  ],
  "project": {
    "customer": {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
      "name": "Donau Maschinenbau AG"
    },
    "endOn": "2026-11-23",
    "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
    "number": 1,
    "phase": "active",
    "responsibleRef": "emma.maier@muster-it.example",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "startOn": "2026-11-02",
    "status": "laufend",
    "title": "ERP-Einführung Donau Maschinenbau",
    "version": 6
  },
  "today": "2026-11-18"
}
```

### Example request

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

## Add a milestone to a project (desk:write)

`POST /api/desk/v1/projects/{id}/milestones`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

### Request body

`application/json` (required)

- `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
- `description` (string): Description of the milestone
- `dueOn` (string (date)): Due date
- `position` (integer): Position among the project's milestones
- `title` (string): Title of the milestone
- `version` (integer): Required on change

Example:

```json
{
  "completion": "manual",
  "description": "Versand und Spediteur sind angebunden und getestet.",
  "dueOn": "2026-11-20",
  "title": "Schnittstellen abgenommen"
}
```

### Responses

- **201** Milestone (`application/json`)

Fields of the 201 answer:

- `achievedAt` (string (date-time), nullable, read-only): When the milestone was reached
- `achievedBy` (string, read-only): The person, or system for completion by items
- `completion` (string): manual: achieved by hand; items: reached once all its items are done (and open again when one reopens) (one of `manual`, `items`)
- `contractId` (string, read-only): Contract of a contract batch (empty otherwise)
- `customerId` (string, read-only): The invoice's customer
- `description` (string): Description of the milestone
- `dueOn` (string (date)): Due date
- `id` (string, read-only): Id of the milestone
- `items` (integer, read-only): Visible items of the milestone (plan only)
- `itemsDone` (integer, read-only): Visible items of the milestone that are done (plan only)
- `label` (string, read-only): The unit as the invoice names it (project, contract, customer name)
- `position` (integer): Position among the project's milestones
- `projectId` (string, read-only): Project of a project batch (empty otherwise)
- `scope` (string, read-only): (one of `project`, `contract`, `customer`)
- `title` (string): Title of the milestone (max length 200)
- `version` (integer): Version of the milestone; send it back on change

Example 201 answer:

```json
{
  "achievedAt": "2026-11-10T16:00:00Z",
  "achievedBy": "system",
  "completion": "items",
  "description": "Key-User haben die Konfiguration abgenommen.",
  "dueOn": "2026-11-11",
  "id": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "items": 5,
  "itemsDone": 5,
  "label": "ERP-Einführung Donau Maschinenbau",
  "position": 1,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "scope": "project",
  "title": "Konfiguration abgenommen",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/milestones' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"completion":"manual","description":"Versand und Spediteur sind angebunden und getestet.","dueOn":"2026-11-20","title":"Schnittstellen abgenommen"}'
```

## Change a milestone at its version (desk:write)

`PUT /api/desk/v1/projects/{id}/milestones/{mid}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `mid` | path | string | yes |  |

### Request body

`application/json` (required)

- `completion` (string): manual: achieved by hand; items: reached once all its items are done (one of `manual`, `items`)
- `description` (string): Description of the milestone
- `dueOn` (string (date)): Due date
- `position` (integer): Position among the project's milestones
- `title` (string): Title of the milestone
- `version` (integer): Required on change

Example:

```json
{
  "dueOn": "2026-11-13",
  "version": 1
}
```

### Responses

- **200** Milestone (`application/json`)
- **409** Version conflict

Fields of the 200 answer:

- `achievedAt` (string (date-time), nullable, read-only): When the milestone was reached
- `achievedBy` (string, read-only): The person, or system for completion by items
- `completion` (string): manual: achieved by hand; items: reached once all its items are done (and open again when one reopens) (one of `manual`, `items`)
- `contractId` (string, read-only): Contract of a contract batch (empty otherwise)
- `customerId` (string, read-only): The invoice's customer
- `description` (string): Description of the milestone
- `dueOn` (string (date)): Due date
- `id` (string, read-only): Id of the milestone
- `items` (integer, read-only): Visible items of the milestone (plan only)
- `itemsDone` (integer, read-only): Visible items of the milestone that are done (plan only)
- `label` (string, read-only): The unit as the invoice names it (project, contract, customer name)
- `position` (integer): Position among the project's milestones
- `projectId` (string, read-only): Project of a project batch (empty otherwise)
- `scope` (string, read-only): (one of `project`, `contract`, `customer`)
- `title` (string): Title of the milestone (max length 200)
- `version` (integer): Version of the milestone; send it back on change

Example 200 answer:

```json
{
  "achievedAt": "2026-11-10T16:00:00Z",
  "achievedBy": "system",
  "completion": "items",
  "description": "Key-User haben die Konfiguration abgenommen.",
  "dueOn": "2026-11-11",
  "id": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "items": 5,
  "itemsDone": 5,
  "label": "ERP-Einführung Donau Maschinenbau",
  "position": 1,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "scope": "project",
  "title": "Konfiguration abgenommen",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/projects/string/milestones/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"dueOn":"2026-11-13","version":1}'
```

## Remove a milestone; its items stay in the project (desk:write)

`DELETE /api/desk/v1/projects/{id}/milestones/{mid}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `mid` | path | string | yes |  |

### Responses

- **204** Removed

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/projects/string/milestones/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Mark a milestone reached; writes desk.project.milestone_achieved (desk:write)

`POST /api/desk/v1/projects/{id}/milestones/{mid}/achieve`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `mid` | path | string | yes |  |

### Responses

- **200** Milestone (`application/json`)
- **409** milestone_state: already reached, or completed by its items

Fields of the 200 answer:

- `achievedAt` (string (date-time), nullable, read-only): When the milestone was reached
- `achievedBy` (string, read-only): The person, or system for completion by items
- `completion` (string): manual: achieved by hand; items: reached once all its items are done (and open again when one reopens) (one of `manual`, `items`)
- `contractId` (string, read-only): Contract of a contract batch (empty otherwise)
- `customerId` (string, read-only): The invoice's customer
- `description` (string): Description of the milestone
- `dueOn` (string (date)): Due date
- `id` (string, read-only): Id of the milestone
- `items` (integer, read-only): Visible items of the milestone (plan only)
- `itemsDone` (integer, read-only): Visible items of the milestone that are done (plan only)
- `label` (string, read-only): The unit as the invoice names it (project, contract, customer name)
- `position` (integer): Position among the project's milestones
- `projectId` (string, read-only): Project of a project batch (empty otherwise)
- `scope` (string, read-only): (one of `project`, `contract`, `customer`)
- `title` (string): Title of the milestone (max length 200)
- `version` (integer): Version of the milestone; send it back on change

Example 200 answer:

```json
{
  "achievedAt": "2026-11-10T16:00:00Z",
  "achievedBy": "system",
  "completion": "items",
  "description": "Key-User haben die Konfiguration abgenommen.",
  "dueOn": "2026-11-11",
  "id": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "items": 5,
  "itemsDone": 5,
  "label": "ERP-Einführung Donau Maschinenbau",
  "position": 1,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "scope": "project",
  "title": "Konfiguration abgenommen",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/milestones/string/achieve' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Take the achievement back; writes desk.project.milestone_reopened (desk:write)

`POST /api/desk/v1/projects/{id}/milestones/{mid}/reopen`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `mid` | path | string | yes |  |

### Responses

- **200** Milestone (`application/json`)
- **409** milestone_state: not reached, or completed by its items

Fields of the 200 answer:

- `achievedAt` (string (date-time), nullable, read-only): When the milestone was reached
- `achievedBy` (string, read-only): The person, or system for completion by items
- `completion` (string): manual: achieved by hand; items: reached once all its items are done (and open again when one reopens) (one of `manual`, `items`)
- `contractId` (string, read-only): Contract of a contract batch (empty otherwise)
- `customerId` (string, read-only): The invoice's customer
- `description` (string): Description of the milestone
- `dueOn` (string (date)): Due date
- `id` (string, read-only): Id of the milestone
- `items` (integer, read-only): Visible items of the milestone (plan only)
- `itemsDone` (integer, read-only): Visible items of the milestone that are done (plan only)
- `label` (string, read-only): The unit as the invoice names it (project, contract, customer name)
- `position` (integer): Position among the project's milestones
- `projectId` (string, read-only): Project of a project batch (empty otherwise)
- `scope` (string, read-only): (one of `project`, `contract`, `customer`)
- `title` (string): Title of the milestone (max length 200)
- `version` (integer): Version of the milestone; send it back on change

Example 200 answer:

```json
{
  "achievedAt": "2026-11-10T16:00:00Z",
  "achievedBy": "system",
  "completion": "items",
  "description": "Key-User haben die Konfiguration abgenommen.",
  "dueOn": "2026-11-11",
  "id": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "items": 5,
  "itemsDone": 5,
  "label": "ERP-Einführung Donau Maschinenbau",
  "position": 1,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "scope": "project",
  "title": "Konfiguration abgenommen",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/milestones/string/reopen' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Make one item of the project start after another ended (desk:write)

`POST /api/desk/v1/projects/{id}/dependencies`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

### Request body

`application/json` (required)

- `predecessorId` (string, required): Item id or number
- `successorId` (string, required): Item id or number
- `lagDays` (integer): (max 365)

Example:

```json
{
  "lagDays": 1,
  "predecessorId": "#58",
  "successorId": "#59"
}
```

### Responses

- **201** Dependency (`application/json`)
- **400** An item is not one of the project
- **409** dependency_cycle, or duplicate (the pair exists)

Fields of the 201 answer:

- `createdAt` (string (date-time), read-only): When it was created
- `createdBy` (string, read-only): Login (e-mail) of who created it
- `id` (string, read-only): Id of the dependency
- `kind` (string): Kind of dependency (one of `finish_to_start`)
- `lagDays` (integer): Days between the predecessor's end and the successor's start; negative = overlap (max 365)
- `predecessorId` (string): Item that has to end first
- `projectId` (string, read-only): Project of the dependency
- `successorId` (string): Starts lagDays after the predecessor ended (finish-to-start)

Example 201 answer:

```json
{
  "createdAt": "2026-11-02T07:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "id": "8e5f6a7b-9c0d-4e1f-8a3b-5c6d7e8f9a01",
  "kind": "finish_to_start",
  "lagDays": 1,
  "predecessorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "successorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0c"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/dependencies' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"lagDays":1,"predecessorId":"#58","successorId":"#59"}'
```

## Change the lag of a dependency (desk:write)

`PUT /api/desk/v1/projects/{id}/dependencies/{did}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `did` | path | string | yes |  |

### Request body

`application/json` (required)

- `lagDays` (integer): (max 365)

Example:

```json
{
  "lagDays": 2
}
```

### Responses

- **200** Dependency (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time), read-only): When it was created
- `createdBy` (string, read-only): Login (e-mail) of who created it
- `id` (string, read-only): Id of the dependency
- `kind` (string): Kind of dependency (one of `finish_to_start`)
- `lagDays` (integer): Days between the predecessor's end and the successor's start; negative = overlap (max 365)
- `predecessorId` (string): Item that has to end first
- `projectId` (string, read-only): Project of the dependency
- `successorId` (string): Starts lagDays after the predecessor ended (finish-to-start)

Example 200 answer:

```json
{
  "createdAt": "2026-11-02T07:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "id": "8e5f6a7b-9c0d-4e1f-8a3b-5c6d7e8f9a01",
  "kind": "finish_to_start",
  "lagDays": 1,
  "predecessorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "successorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0c"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/projects/string/dependencies/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"lagDays":2}'
```

## Remove a dependency (desk:write)

`DELETE /api/desk/v1/projects/{id}/dependencies/{did}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `did` | path | string | yes |  |

### Responses

- **204** Removed

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/projects/string/dependencies/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The payment plan of a project with contract value and invoiced sum (hr:work:billing)

`GET /api/desk/v1/projects/{id}/payments`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Id or number |

### Responses

- **200** Billing (`application/json`)

Fields of the 200 answer:

- `autoDraft` (boolean): The project type requests payments as soon as they are due
- `contractValue` (number): Net sum of all payments (what the final invoice bills in total)
- `invoiced` (number): Net of the released invoices
- `payments` (array of ProjectPayment): Payments of the plan in order
  - `amount` (number): Net amount or percentage (amountKind)
  - `amountKind` (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of `fixed`, `percent`)
  - `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
  - `document` (object, read-only): The invoice handed to trade (once requested)
  - `dueOn` (string (date), nullable): Due on this date
  - `grossTotal` (number, nullable, read-only): Gross total of the invoice
  - `id` (string, read-only): Id of the payment
  - `invoiceNumber` (string, read-only): Given by trade on release
  - `invoicedOn` (string (date), nullable, read-only): Invoice date
  - `lastError` (string, read-only): Why the last send to trade failed
  - `milestoneId` (string, nullable): Due when this milestone of the project is reached
  - `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
  - `netTotal` (number, nullable, read-only): Net total of the invoice
  - `position` (integer): Position in the payment plan
  - `projectId` (string, read-only): Project of the payment
  - `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
  - `requestedBy` (string, read-only): The person, or system (automatic draft)
  - `role` (string): interim payment or the final payment (one of `interim`, `final`)
  - `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
  - `state` (string, read-only): State of the payment (one of `planned`, `due`, `requested`, `drafted`, `invoiced`, `skipped`)
  - `taxRate` (number): VAT rate in percent (max 100)
  - `title` (string): Title of the payment (invoice line) (max length 200)
  - `tradeTransactionId` (string, read-only): Invoice transaction in trade
  - `version` (integer): Version of the payment; send it back on change

Example 200 answer:

```json
{
  "autoDraft": false,
  "contractValue": 22400,
  "invoiced": 6720,
  "payments": [
    {
      "amount": 30,
      "amountKind": "percent",
      "attempt": 1,
      "dueOn": null,
      "grossTotal": 7996.8,
      "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
      "invoiceNumber": "RE-2026-0187",
      "invoicedOn": "2026-11-11",
      "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
      "net": 6720,
      "netTotal": 6720,
      "position": 0,
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "role": "interim",
      "state": "invoiced",
      "taxRate": 19,
      "title": "Abschlag nach Konfiguration",
      "version": 4
    },
    {
      "amount": 30,
      "amountKind": "percent",
      "attempt": 0,
      "dueOn": null,
      "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f02",
      "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
      "net": 6720,
      "position": 1,
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "role": "interim",
      "state": "planned",
      "taxRate": 19,
      "title": "Abschlag nach Datenübernahme",
      "version": 1
    },
    {
      "amount": 40,
      "amountKind": "percent",
      "attempt": 0,
      "dueOn": null,
      "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f03",
      "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e04",
      "net": 8960,
      "position": 2,
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "role": "final",
      "state": "planned",
      "taxRate": 19,
      "title": "Schlussrechnung",
      "version": 1
    }
  ]
}
```

### Example request

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

## Add an interim or the final payment to the plan (hr:work:billing)

`POST /api/desk/v1/projects/{id}/payments`

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

It is due at once when its milestone is reached or its date has come. A project has one final payment.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Id or number |

### Request body

`application/json` (required)

- `amount` (number): Net amount or percentage (amountKind)
- `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
- `clearDueOn` (boolean): Remove the due date
- `clearMilestone` (boolean): Remove the milestone
- `dueOn` (string (date)): Date the payment is due
- `milestoneId` (string): Milestone that makes the payment due
- `position` (integer): Position in the payment plan
- `role` (string): interim payment or the final payment (one of `interim`, `final`)
- `taxRate` (number): Default: the project type's (19)
- `title` (string): Title of the payment (invoice line)
- `version` (integer): Current version (required on change)

Example:

```json
{
  "amount": 30,
  "amountKind": "percent",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
  "role": "interim",
  "taxRate": 19,
  "title": "Abschlag nach Datenübernahme"
}
```

### Responses

- **201** Payment (`application/json`)
- **400** Invalid payment, a second final payment, or a milestone of another project

Fields of the 201 answer:

- `amount` (number): Net amount or percentage (amountKind)
- `amountKind` (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of `fixed`, `percent`)
- `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
- `document` (object, read-only): The invoice handed to trade (once requested)
- `dueOn` (string (date), nullable): Due on this date
- `grossTotal` (number, nullable, read-only): Gross total of the invoice
- `id` (string, read-only): Id of the payment
- `invoiceNumber` (string, read-only): Given by trade on release
- `invoicedOn` (string (date), nullable, read-only): Invoice date
- `lastError` (string, read-only): Why the last send to trade failed
- `milestoneId` (string, nullable): Due when this milestone of the project is reached
- `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
- `netTotal` (number, nullable, read-only): Net total of the invoice
- `position` (integer): Position in the payment plan
- `projectId` (string, read-only): Project of the payment
- `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
- `requestedBy` (string, read-only): The person, or system (automatic draft)
- `role` (string): interim payment or the final payment (one of `interim`, `final`)
- `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
- `state` (string, read-only): State of the payment (one of `planned`, `due`, `requested`, `drafted`, `invoiced`, `skipped`)
- `taxRate` (number): VAT rate in percent (max 100)
- `title` (string): Title of the payment (invoice line) (max length 200)
- `tradeTransactionId` (string, read-only): Invoice transaction in trade
- `version` (integer): Version of the payment; send it back on change

Example 201 answer:

```json
{
  "amount": 30,
  "amountKind": "percent",
  "attempt": 1,
  "document": {},
  "dueOn": null,
  "grossTotal": 7996.8,
  "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
  "invoiceNumber": "RE-2026-0187",
  "invoicedOn": "2026-11-11",
  "lastError": "",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "net": 6720,
  "netTotal": 6720,
  "position": 0,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "requestedAt": "2026-11-10T16:05:00Z",
  "requestedBy": "emma.maier@muster-it.example",
  "role": "interim",
  "sendAttempts": 1,
  "state": "invoiced",
  "taxRate": 19,
  "title": "Abschlag nach Konfiguration",
  "tradeTransactionId": "8f5a6b7c-9d0e-4f1a-8b2c-3d4e5f6a7b01",
  "version": 4
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"amount":30,"amountKind":"percent","milestoneId":"6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03","role":"interim","taxRate":19,"title":"Abschlag nach Datenübernahme"}'
```

## Change a payment at its version; after it was requested only its position (hr:work:billing)

`PUT /api/desk/v1/projects/{id}/payments/{pid}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `pid` | path | string | yes |  |

### Request body

`application/json` (required)

- `amount` (number): Net amount or percentage (amountKind)
- `amountKind` (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of `fixed`, `percent`)
- `clearDueOn` (boolean): Remove the due date
- `clearMilestone` (boolean): Remove the milestone
- `dueOn` (string (date)): Date the payment is due
- `milestoneId` (string): Milestone that makes the payment due
- `position` (integer): Position in the payment plan
- `role` (string): interim payment or the final payment (one of `interim`, `final`)
- `taxRate` (number): Default: the project type's (19)
- `title` (string): Title of the payment (invoice line)
- `version` (integer): Current version (required on change)

Example:

```json
{
  "amount": 35,
  "dueOn": "2026-11-30",
  "version": 1
}
```

### Responses

- **200** Payment (`application/json`)
- **409** version_conflict, or payment_state (it was requested)

Fields of the 200 answer:

- `amount` (number): Net amount or percentage (amountKind)
- `amountKind` (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of `fixed`, `percent`)
- `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
- `document` (object, read-only): The invoice handed to trade (once requested)
- `dueOn` (string (date), nullable): Due on this date
- `grossTotal` (number, nullable, read-only): Gross total of the invoice
- `id` (string, read-only): Id of the payment
- `invoiceNumber` (string, read-only): Given by trade on release
- `invoicedOn` (string (date), nullable, read-only): Invoice date
- `lastError` (string, read-only): Why the last send to trade failed
- `milestoneId` (string, nullable): Due when this milestone of the project is reached
- `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
- `netTotal` (number, nullable, read-only): Net total of the invoice
- `position` (integer): Position in the payment plan
- `projectId` (string, read-only): Project of the payment
- `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
- `requestedBy` (string, read-only): The person, or system (automatic draft)
- `role` (string): interim payment or the final payment (one of `interim`, `final`)
- `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
- `state` (string, read-only): State of the payment (one of `planned`, `due`, `requested`, `drafted`, `invoiced`, `skipped`)
- `taxRate` (number): VAT rate in percent (max 100)
- `title` (string): Title of the payment (invoice line) (max length 200)
- `tradeTransactionId` (string, read-only): Invoice transaction in trade
- `version` (integer): Version of the payment; send it back on change

Example 200 answer:

```json
{
  "amount": 30,
  "amountKind": "percent",
  "attempt": 1,
  "document": {},
  "dueOn": null,
  "grossTotal": 7996.8,
  "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
  "invoiceNumber": "RE-2026-0187",
  "invoicedOn": "2026-11-11",
  "lastError": "",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "net": 6720,
  "netTotal": 6720,
  "position": 0,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "requestedAt": "2026-11-10T16:05:00Z",
  "requestedBy": "emma.maier@muster-it.example",
  "role": "interim",
  "sendAttempts": 1,
  "state": "invoiced",
  "taxRate": 19,
  "title": "Abschlag nach Konfiguration",
  "tradeTransactionId": "8f5a6b7c-9d0e-4f1a-8b2c-3d4e5f6a7b01",
  "version": 4
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"amount":35,"dueOn":"2026-11-30","version":1}'
```

## Remove a payment that was not requested (hr:work:billing)

`DELETE /api/desk/v1/projects/{id}/payments/{pid}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `pid` | path | string | yes |  |

### Responses

- **204** Removed
- **409** payment_state: it was requested

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Hand the payment's invoice to trade as a draft; writes desk.project.payment_requested (hr:work:billing)

`POST /api/desk/v1/projects/{id}/payments/{pid}/request`

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

The invoice is made once, dated today: an interim invoice bills the payment's net amount; the final invoice bills the contract value (one line per VAT rate) and deducts the invoiced interim invoices, interim payments not requested yet become skipped. Trade numbers and releases it after a person's review; trade's feed moves the payment to drafted, invoiced, or back to due when the draft is discarded or the invoice revoked. When trade cannot be reached the payment stays requested (lastError) and desk retries; requesting it again sends at once.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `pid` | path | string | yes |  |

### Responses

- **200** Payment (drafted, or requested when trade did not take it yet) (`application/json`)
- **400** The project has no customer, or a percentage without budget amount
- **409** payment_state: already on its way, or an interim invoice is not released yet (final invoice)
- **503** Project billing is not connected to trade

Fields of the 200 answer:

- `amount` (number): Net amount or percentage (amountKind)
- `amountKind` (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of `fixed`, `percent`)
- `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
- `document` (object, read-only): The invoice handed to trade (once requested)
- `dueOn` (string (date), nullable): Due on this date
- `grossTotal` (number, nullable, read-only): Gross total of the invoice
- `id` (string, read-only): Id of the payment
- `invoiceNumber` (string, read-only): Given by trade on release
- `invoicedOn` (string (date), nullable, read-only): Invoice date
- `lastError` (string, read-only): Why the last send to trade failed
- `milestoneId` (string, nullable): Due when this milestone of the project is reached
- `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
- `netTotal` (number, nullable, read-only): Net total of the invoice
- `position` (integer): Position in the payment plan
- `projectId` (string, read-only): Project of the payment
- `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
- `requestedBy` (string, read-only): The person, or system (automatic draft)
- `role` (string): interim payment or the final payment (one of `interim`, `final`)
- `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
- `state` (string, read-only): State of the payment (one of `planned`, `due`, `requested`, `drafted`, `invoiced`, `skipped`)
- `taxRate` (number): VAT rate in percent (max 100)
- `title` (string): Title of the payment (invoice line) (max length 200)
- `tradeTransactionId` (string, read-only): Invoice transaction in trade
- `version` (integer): Version of the payment; send it back on change

Example 200 answer:

```json
{
  "amount": 30,
  "amountKind": "percent",
  "attempt": 1,
  "dueOn": null,
  "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f02",
  "lastError": "",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
  "net": 6720,
  "position": 1,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "requestedAt": "2026-11-18T09:30:00Z",
  "requestedBy": "emma.maier@muster-it.example",
  "role": "interim",
  "sendAttempts": 0,
  "state": "requested",
  "taxRate": 19,
  "title": "Abschlag nach Datenübernahme",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments/string/request' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Take back a requested payment trade has not taken; it is due again with a new document (hr:work:billing)

`POST /api/desk/v1/projects/{id}/payments/{pid}/withdraw`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `pid` | path | string | yes |  |

### Responses

- **200** Payment (`application/json`)
- **409** payment_state: not requested, or trade holds the draft (discard it in trade)

Fields of the 200 answer:

- `amount` (number): Net amount or percentage (amountKind)
- `amountKind` (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of `fixed`, `percent`)
- `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
- `document` (object, read-only): The invoice handed to trade (once requested)
- `dueOn` (string (date), nullable): Due on this date
- `grossTotal` (number, nullable, read-only): Gross total of the invoice
- `id` (string, read-only): Id of the payment
- `invoiceNumber` (string, read-only): Given by trade on release
- `invoicedOn` (string (date), nullable, read-only): Invoice date
- `lastError` (string, read-only): Why the last send to trade failed
- `milestoneId` (string, nullable): Due when this milestone of the project is reached
- `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
- `netTotal` (number, nullable, read-only): Net total of the invoice
- `position` (integer): Position in the payment plan
- `projectId` (string, read-only): Project of the payment
- `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
- `requestedBy` (string, read-only): The person, or system (automatic draft)
- `role` (string): interim payment or the final payment (one of `interim`, `final`)
- `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
- `state` (string, read-only): State of the payment (one of `planned`, `due`, `requested`, `drafted`, `invoiced`, `skipped`)
- `taxRate` (number): VAT rate in percent (max 100)
- `title` (string): Title of the payment (invoice line) (max length 200)
- `tradeTransactionId` (string, read-only): Invoice transaction in trade
- `version` (integer): Version of the payment; send it back on change

Example 200 answer:

```json
{
  "amount": 30,
  "amountKind": "percent",
  "attempt": 1,
  "dueOn": null,
  "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f02",
  "lastError": "",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
  "net": 6720,
  "position": 1,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "requestedAt": null,
  "role": "interim",
  "sendAttempts": 0,
  "state": "due",
  "taxRate": 19,
  "title": "Abschlag nach Datenübernahme",
  "version": 4
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments/string/withdraw' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Spent and billable time of the project against budget and plan, items by phase (desk:read). Items: GET /items?project=<id>

`GET /api/desk/v1/projects/{id}/summary`

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

Spent and billable minutes are HR's totals of the work booked with the project as reference (`desk:project:<id>`, ADR 0040). When HR does not answer they are null, as are remaining minutes, percent and budget state – never an error.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

### Responses

- **200** Summary (`application/json`)

Fields of the 200 answer:

- `billableMinutes` (integer, nullable)
- `budgetMinutes` (integer, nullable)
- `budgetPercent` (integer, nullable)
- `budgetState` (string): (one of `ok`, `warning`, `exceeded`)
- `items` (integer)
- `itemsByPhase` (object)
- `plannedMinutes` (integer, nullable)
- `remainingMinutes` (integer, nullable)
- `spentMinutes` (integer, nullable)

Example 200 answer:

```json
{
  "billableMinutes": 3900,
  "budgetMinutes": 9600,
  "budgetPercent": 44,
  "budgetState": "ok",
  "items": 21,
  "itemsByPhase": {
    "active": 3,
    "done": 9,
    "new": 9,
    "waiting": 0
  },
  "plannedMinutes": 8400,
  "remainingMinutes": 5340,
  "spentMinutes": 4260
}
```

### Example request

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

# Portal

## Desk's app settings of the customer portal (tickets, help); without them the defaults at version 0 (desk:admin, ADR 0023)

`GET /api/desk/v1/portal-config`

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

### Responses

- **200** Portal (`application/json`)

Fields of the 200 answer:

- `settings` (object, required): Settings of desk's portal apps
  - `agentName` (string): How agents are named to requesters: full name, first name or „Support“ (one of `full`, `first`, `support`)
  - `attachments` (object): File limits of requester uploads
    - `allowedMime` (array of string): Allowed MIME types of requester uploads
    - `maxBytes` (integer): Maximum size per file in bytes
    - `maxCount` (integer): Maximum number of files
  - `companyView` (object): Allows the company view; who has it is set on the customer account (customerportal)
    - `enabled` (boolean): The company view may be granted
  - `forms` (array of object): Forms requesters open tickets with
    - `key` (string, required): Key of the form
    - `label` (string, required): Name of the form (max length 80)
    - `spaceKey` (string, required): Space of the tickets
    - `typeKey` (string, required): Type of the tickets
    - `defaultPriority` (string): Priority key of the tickets
    - `description` (string): Description shown with the form
    - `fields` (array of object): Fields of the form
      - `key` (string, required): cf.<key>
      - `help` (string): Help text
      - `label` (string): Label shown to the requester
      - `required` (boolean): The requester must fill it
    - `public` (object): Opens the form for submissions without sign-in
      - `enabled` (boolean): Submissions without sign-in are on
      - `key` (string, read-only): Generated; names the form in the public URL (not secret)
      - `origins` (array of string): Sites that may embed the form, like https://www.example.de; * any
  - `help` (object): Help area settings
    - `ask` (boolean): Requesters may ask questions answered from the released articles; missing is on
  - `limits` (object): Limits per requester
    - `entriesPerHour` (integer): Replies per requester and hour
    - `ticketsPerDay` (integer): New tickets per requester and day
  - `phaseLabels` (object): Names for requesters by phase (fallback)
  - `platformFeedback` (object): Platform feedback targets per kind; only the operator tenant (10639/MBCOM) may enable kinds
    - `kinds` (object): Keys: bug, feature, emergency, account
  - `satisfaction` (object): Customer satisfaction: the requester rates a closed ticket once (1–5 stars, optional comment) within `days` after it was closed (`rateCustomerTicket`; event `desk.ticket.rated`)
    - `days` (integer): Days after closing; missing or 0 is 14 (max 90)
    - `enabled` (boolean): Requesters may rate closed tickets
  - `statusLabels` (object): Names for requesters by "<workflowKey>:<statusKey>"; the key "forwarded" names forwarding stubs (default „Weitergeleitet“)
  - `types` (object): Per type key: visible to requesters, fields they see (priority, dueAt, customer, contact, category, startOn, cf.<key>)
- `platformAvailable` (boolean, read-only): This tenant is the operator tenant
- `portalUrl` (string, read-only): Address of the tenant's customer portal (from customerportal); missing without one
- `updatedAt` (string (date-time), read-only): When they were last saved
- `updatedBy` (string, read-only): Login (e-mail) of who last saved them
- `version` (integer): Version of the settings (0: never saved); send it back on change

Example 200 answer:

```json
{
  "platformAvailable": false,
  "portalUrl": "https://muster-it.connectcloud.example",
  "settings": {
    "agentName": "full",
    "attachments": {
      "allowedMime": [
        "image/png",
        "image/jpeg",
        "application/pdf"
      ],
      "maxBytes": 10485760,
      "maxCount": 5
    },
    "companyView": {
      "enabled": true
    },
    "forms": [
      {
        "defaultPriority": "normal",
        "description": "Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.",
        "fields": [
          {
            "help": "z. B. Drucker Empfang",
            "key": "cf.betroffenes_system",
            "label": "Betroffenes Gerät oder System",
            "required": false
          }
        ],
        "key": "stoerung",
        "label": "Störung melden",
        "public": {
          "enabled": false
        },
        "spaceKey": "SUP",
        "typeKey": "stoerung"
      }
    ],
    "help": {
      "ask": true
    },
    "limits": {
      "entriesPerHour": 30,
      "ticketsPerDay": 20
    },
    "phaseLabels": {
      "active": "In Bearbeitung",
      "done": "Erledigt",
      "new": "Eingegangen",
      "waiting": "Wartet auf Rückmeldung"
    },
    "satisfaction": {
      "days": 14,
      "enabled": true
    },
    "statusLabels": {},
    "types": {
      "serviceanfrage": {
        "fields": [
          "priority",
          "category",
          "dueAt"
        ],
        "visible": true
      },
      "stoerung": {
        "fields": [
          "priority",
          "category",
          "cf.betroffenes_system"
        ],
        "visible": true
      }
    }
  },
  "updatedAt": "2026-10-28T10:15:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 5
}
```

### Example request

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

## Create (version 0) or change desk's app settings of the customer portal at their version (desk:admin)

`PUT /api/desk/v1/portal-config`

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

### Request body

`application/json` (required)

- `settings` (object, required): Settings of desk's portal apps
  - `agentName` (string): How agents are named to requesters: full name, first name or „Support“ (one of `full`, `first`, `support`)
  - `attachments` (object): File limits of requester uploads
    - `allowedMime` (array of string): Allowed MIME types of requester uploads
    - `maxBytes` (integer): Maximum size per file in bytes
    - `maxCount` (integer): Maximum number of files
  - `companyView` (object): Allows the company view; who has it is set on the customer account (customerportal)
    - `enabled` (boolean): The company view may be granted
  - `forms` (array of object): Forms requesters open tickets with
    - `key` (string, required): Key of the form
    - `label` (string, required): Name of the form (max length 80)
    - `spaceKey` (string, required): Space of the tickets
    - `typeKey` (string, required): Type of the tickets
    - `defaultPriority` (string): Priority key of the tickets
    - `description` (string): Description shown with the form
    - `fields` (array of object): Fields of the form
      - `key` (string, required): cf.<key>
      - `help` (string): Help text
      - `label` (string): Label shown to the requester
      - `required` (boolean): The requester must fill it
    - `public` (object): Opens the form for submissions without sign-in
      - `enabled` (boolean): Submissions without sign-in are on
      - `key` (string, read-only): Generated; names the form in the public URL (not secret)
      - `origins` (array of string): Sites that may embed the form, like https://www.example.de; * any
  - `help` (object): Help area settings
    - `ask` (boolean): Requesters may ask questions answered from the released articles; missing is on
  - `limits` (object): Limits per requester
    - `entriesPerHour` (integer): Replies per requester and hour
    - `ticketsPerDay` (integer): New tickets per requester and day
  - `phaseLabels` (object): Names for requesters by phase (fallback)
  - `platformFeedback` (object): Platform feedback targets per kind; only the operator tenant (10639/MBCOM) may enable kinds
    - `kinds` (object): Keys: bug, feature, emergency, account
  - `satisfaction` (object): Customer satisfaction: the requester rates a closed ticket once (1–5 stars, optional comment) within `days` after it was closed (`rateCustomerTicket`; event `desk.ticket.rated`)
    - `days` (integer): Days after closing; missing or 0 is 14 (max 90)
    - `enabled` (boolean): Requesters may rate closed tickets
  - `statusLabels` (object): Names for requesters by "<workflowKey>:<statusKey>"; the key "forwarded" names forwarding stubs (default „Weitergeleitet“)
  - `types` (object): Per type key: visible to requesters, fields they see (priority, dueAt, customer, contact, category, startOn, cf.<key>)
- `platformAvailable` (boolean, read-only): This tenant is the operator tenant
- `portalUrl` (string, read-only): Address of the tenant's customer portal (from customerportal); missing without one
- `updatedAt` (string (date-time), read-only): When they were last saved
- `updatedBy` (string, read-only): Login (e-mail) of who last saved them
- `version` (integer): Version of the settings (0: never saved); send it back on change

Example:

```json
{
  "platformAvailable": false,
  "portalUrl": "https://muster-it.connectcloud.example",
  "settings": {
    "agentName": "full",
    "attachments": {
      "allowedMime": [
        "image/png",
        "image/jpeg",
        "application/pdf"
      ],
      "maxBytes": 10485760,
      "maxCount": 5
    },
    "companyView": {
      "enabled": true
    },
    "forms": [
      {
        "defaultPriority": "normal",
        "description": "Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.",
        "fields": [
          {
            "help": "z. B. Drucker Empfang",
            "key": "cf.betroffenes_system",
            "label": "Betroffenes Gerät oder System",
            "required": false
          }
        ],
        "key": "stoerung",
        "label": "Störung melden",
        "public": {
          "enabled": false
        },
        "spaceKey": "SUP",
        "typeKey": "stoerung"
      }
    ],
    "help": {
      "ask": true
    },
    "limits": {
      "entriesPerHour": 30,
      "ticketsPerDay": 20
    },
    "phaseLabels": {
      "active": "In Bearbeitung",
      "done": "Erledigt",
      "new": "Eingegangen",
      "waiting": "Wartet auf Rückmeldung"
    },
    "satisfaction": {
      "days": 14,
      "enabled": true
    },
    "statusLabels": {},
    "types": {
      "serviceanfrage": {
        "fields": [
          "priority",
          "category",
          "dueAt"
        ],
        "visible": true
      },
      "stoerung": {
        "fields": [
          "priority",
          "category",
          "cf.betroffenes_system"
        ],
        "visible": true
      }
    }
  },
  "updatedAt": "2026-10-28T10:15:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 5
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Invalid
- **409** Version conflict

Fields of the 200 answer:

- `settings` (object, required): Settings of desk's portal apps
  - `agentName` (string): How agents are named to requesters: full name, first name or „Support“ (one of `full`, `first`, `support`)
  - `attachments` (object): File limits of requester uploads
    - `allowedMime` (array of string): Allowed MIME types of requester uploads
    - `maxBytes` (integer): Maximum size per file in bytes
    - `maxCount` (integer): Maximum number of files
  - `companyView` (object): Allows the company view; who has it is set on the customer account (customerportal)
    - `enabled` (boolean): The company view may be granted
  - `forms` (array of object): Forms requesters open tickets with
    - `key` (string, required): Key of the form
    - `label` (string, required): Name of the form (max length 80)
    - `spaceKey` (string, required): Space of the tickets
    - `typeKey` (string, required): Type of the tickets
    - `defaultPriority` (string): Priority key of the tickets
    - `description` (string): Description shown with the form
    - `fields` (array of object): Fields of the form
      - `key` (string, required): cf.<key>
      - `help` (string): Help text
      - `label` (string): Label shown to the requester
      - `required` (boolean): The requester must fill it
    - `public` (object): Opens the form for submissions without sign-in
      - `enabled` (boolean): Submissions without sign-in are on
      - `key` (string, read-only): Generated; names the form in the public URL (not secret)
      - `origins` (array of string): Sites that may embed the form, like https://www.example.de; * any
  - `help` (object): Help area settings
    - `ask` (boolean): Requesters may ask questions answered from the released articles; missing is on
  - `limits` (object): Limits per requester
    - `entriesPerHour` (integer): Replies per requester and hour
    - `ticketsPerDay` (integer): New tickets per requester and day
  - `phaseLabels` (object): Names for requesters by phase (fallback)
  - `platformFeedback` (object): Platform feedback targets per kind; only the operator tenant (10639/MBCOM) may enable kinds
    - `kinds` (object): Keys: bug, feature, emergency, account
  - `satisfaction` (object): Customer satisfaction: the requester rates a closed ticket once (1–5 stars, optional comment) within `days` after it was closed (`rateCustomerTicket`; event `desk.ticket.rated`)
    - `days` (integer): Days after closing; missing or 0 is 14 (max 90)
    - `enabled` (boolean): Requesters may rate closed tickets
  - `statusLabels` (object): Names for requesters by "<workflowKey>:<statusKey>"; the key "forwarded" names forwarding stubs (default „Weitergeleitet“)
  - `types` (object): Per type key: visible to requesters, fields they see (priority, dueAt, customer, contact, category, startOn, cf.<key>)
- `platformAvailable` (boolean, read-only): This tenant is the operator tenant
- `portalUrl` (string, read-only): Address of the tenant's customer portal (from customerportal); missing without one
- `updatedAt` (string (date-time), read-only): When they were last saved
- `updatedBy` (string, read-only): Login (e-mail) of who last saved them
- `version` (integer): Version of the settings (0: never saved); send it back on change

Example 200 answer:

```json
{
  "platformAvailable": false,
  "portalUrl": "https://muster-it.connectcloud.example",
  "settings": {
    "agentName": "full",
    "attachments": {
      "allowedMime": [
        "image/png",
        "image/jpeg",
        "application/pdf"
      ],
      "maxBytes": 10485760,
      "maxCount": 5
    },
    "companyView": {
      "enabled": true
    },
    "forms": [
      {
        "defaultPriority": "normal",
        "description": "Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.",
        "fields": [
          {
            "help": "z. B. Drucker Empfang",
            "key": "cf.betroffenes_system",
            "label": "Betroffenes Gerät oder System",
            "required": false
          }
        ],
        "key": "stoerung",
        "label": "Störung melden",
        "public": {
          "enabled": false
        },
        "spaceKey": "SUP",
        "typeKey": "stoerung"
      }
    ],
    "help": {
      "ask": true
    },
    "limits": {
      "entriesPerHour": 30,
      "ticketsPerDay": 20
    },
    "phaseLabels": {
      "active": "In Bearbeitung",
      "done": "Erledigt",
      "new": "Eingegangen",
      "waiting": "Wartet auf Rückmeldung"
    },
    "satisfaction": {
      "days": 14,
      "enabled": true
    },
    "statusLabels": {},
    "types": {
      "serviceanfrage": {
        "fields": [
          "priority",
          "category",
          "dueAt"
        ],
        "visible": true
      },
      "stoerung": {
        "fields": [
          "priority",
          "category",
          "cf.betroffenes_system"
        ],
        "visible": true
      }
    }
  },
  "updatedAt": "2026-10-28T10:15:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 5
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/portal-config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"platformAvailable":false,"portalUrl":"https://muster-it.connectcloud.example","settings":{"agentName":"full","attachments":{"allowedMime":["image/png","image/jpeg","application/pdf"],"maxBytes":10485760,"maxCount":5},"companyView":{"enabled":true},"forms":[{"defaultPriority":"normal","description":"Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.","fields":[{"help":"z. B. Drucker Empfang","key":"cf.betroffenes_system","label":"Betroffenes Gerät oder System","required":false}],"key":"stoerung","label":"Störung melden","public":{"enabled":false},"spaceKey":"SUP","typeKey":"stoerung"}],"help":{"ask":true},"limits":{"entriesPerHour":30,"ticketsPerDay":20},"phaseLabels":{"active":"In Bearbeitung","done":"Erledigt","new":"Eingegangen","waiting":"Wartet auf Rückmeldung"},"satisfaction":{"days":14,"enabled":true},"statusLabels":{},"types":{"serviceanfrage":{"fields":["priority","category","dueAt"],"visible":true},"stoerung":{"fields":["priority","category","cf.betroffenes_system"],"visible":true}}},"updatedAt":"2026-10-28T10:15:00Z","updatedBy":"elias.gruber@muster-it.example","version":5}'
```

## Help area numbers of the customer portal per day (UTC) of the last days, today included: articles suggested while writing a ticket, opened from a suggestion, marked as helpful. Days without events are missing (desk:admin)

`GET /api/desk/v1/help-stats`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `days` | query | integer |  | (default `30`; max 366) |

### Responses

- **200** Counters, oldest first (`application/json`)
- **400** days out of range

Fields of the 200 answer:

- `items` (array of HelpStat, required)
  - `day` (string (date)): Day (UTC)
  - `helped` (integer): Articles marked as helpful
  - `opened` (integer): Articles opened from a suggestion
  - `suggested` (integer): Articles suggested while writing a ticket

Example 200 answer:

```json
{
  "items": [
    {
      "day": "2026-11-16",
      "helped": 3,
      "opened": 6,
      "suggested": 14
    },
    {
      "day": "2026-11-17",
      "helped": 5,
      "opened": 9,
      "suggested": 21
    }
  ]
}
```

### Example request

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

## Search people who wrote to desk or use the portal by address or name (desk:write)

`GET /api/desk/v1/requesters`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |
| `limit` | query | integer |  | (max 200) |
| `offset` | query | integer |  |  |

### Responses

- **200** Requesters (`application/json`)

Fields of the 200 answer:

- `items` (array of RequesterView)
  - `companyRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
    - `id` (string, required): Id in the other system
    - `name` (string, required): Name at the time of the reference
    - `extra` (object): Further facts of the referenced record
  - `contactRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
    - `id` (string, required): Id in the other system
    - `name` (string, required): Name at the time of the reference
    - `extra` (object): Further facts of the referenced record
  - `createdAt` (string (date-time)): When the requester was first seen
  - `email` (string): E-mail address
  - `emailVerifiedAt` (string (date-time)): When the e-mail address was verified
  - `id` (string): Id of the requester
  - `kind` (string): external: an outside person; platform: a user of another platform tenant (one of `external`, `platform`)
  - `name` (string): Name
  - `originCustomerNo` (string): Customer number of the platform tenant (platform requesters)
  - `originTenantName` (string): Name of the platform tenant (platform requesters)
  - `status` (string): blocked: the person cannot use desk's portal apps (403 requester_blocked) (one of `active`, `blocked`)
  - `tickets` (integer): Tickets the person is on
  - `updatedAt` (string (date-time)): When the requester was last changed
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "companyRef": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "contactRef": {
        "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
        "name": "Katrin Stadler"
      },
      "createdAt": "2026-09-14T08:00:00Z",
      "email": "katrin.stadler@alpenhotel-seeblick.example",
      "id": "0a7b8c9d-1e2f-4a3b-8c5d-7e8f9a0b1c01",
      "kind": "external",
      "name": "Katrin Stadler",
      "status": "active",
      "tickets": 6,
      "updatedAt": "2026-11-17T07:12:00Z"
    }
  ],
  "total": 1
}
```

### Example request

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

## A requester with the number of its tickets (desk:write)

`GET /api/desk/v1/requesters/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Requester (`application/json`)

Fields of the 200 answer:

- `companyRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `contactRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `createdAt` (string (date-time)): When the requester was first seen
- `email` (string): E-mail address
- `emailVerifiedAt` (string (date-time)): When the e-mail address was verified
- `id` (string): Id of the requester
- `kind` (string): external: an outside person; platform: a user of another platform tenant (one of `external`, `platform`)
- `name` (string): Name
- `originCustomerNo` (string): Customer number of the platform tenant (platform requesters)
- `originTenantName` (string): Name of the platform tenant (platform requesters)
- `status` (string): blocked: the person cannot use desk's portal apps (403 requester_blocked) (one of `active`, `blocked`)
- `tickets` (integer): Tickets the person is on
- `updatedAt` (string (date-time)): When the requester was last changed

Example 200 answer:

```json
{
  "companyRef": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "contactRef": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-09-14T08:00:00Z",
  "email": "katrin.stadler@alpenhotel-seeblick.example",
  "emailVerifiedAt": "2026-09-14T08:02:00Z",
  "id": "0a7b8c9d-1e2f-4a3b-8c5d-7e8f9a0b1c01",
  "kind": "external",
  "name": "Katrin Stadler",
  "status": "active",
  "tickets": 6,
  "updatedAt": "2026-11-17T07:12:00Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/requesters/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change name, contact and company, or block a requester (desk:write); a blocked requester cannot use desk's portal apps from the next request on

`PATCH /api/desk/v1/requesters/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `clearCompany` (boolean)
- `clearContact` (boolean)
- `companyRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `contactRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `name` (string): (max length 200)
- `status` (string): (one of `active`, `blocked`)

Example:

```json
{
  "companyRef": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "contactRef": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "name": "Katrin Stadler"
}
```

### Responses

- **200** Requester (`application/json`)

Fields of the 200 answer:

- `companyRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `contactRef` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `createdAt` (string (date-time)): When the requester was first seen
- `email` (string): E-mail address
- `emailVerifiedAt` (string (date-time)): When the e-mail address was verified
- `id` (string): Id of the requester
- `kind` (string): external: an outside person; platform: a user of another platform tenant (one of `external`, `platform`)
- `name` (string): Name
- `originCustomerNo` (string): Customer number of the platform tenant (platform requesters)
- `originTenantName` (string): Name of the platform tenant (platform requesters)
- `status` (string): blocked: the person cannot use desk's portal apps (403 requester_blocked) (one of `active`, `blocked`)
- `tickets` (integer): Tickets the person is on
- `updatedAt` (string (date-time)): When the requester was last changed

Example 200 answer:

```json
{
  "companyRef": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "contactRef": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-09-14T08:00:00Z",
  "email": "katrin.stadler@alpenhotel-seeblick.example",
  "emailVerifiedAt": "2026-09-14T08:02:00Z",
  "id": "0a7b8c9d-1e2f-4a3b-8c5d-7e8f9a0b1c01",
  "kind": "external",
  "name": "Katrin Stadler",
  "status": "active",
  "tickets": 6,
  "updatedAt": "2026-11-17T07:12:00Z"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/requesters/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"companyRef":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11","name":"Alpenhotel Seeblick GmbH \u0026 Co. KG"},"contactRef":{"id":"6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11","name":"Katrin Stadler"},"name":"Katrin Stadler"}'
```

# AI

## Log of AI calls: feature, model, tokens, latency, outcome – never prompts or answers (desk:admin, KI-016)

`GET /api/desk/v1/ai/calls`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `feature` | query | string |  | (one of `triage`, `subject`, `summary`, `draftReply`) |
| `limit` | query | integer |  | Rows per page (default 50) (default `50`; max 200) |
| `cursor` | query | string |  | The `nextCursor` of the previous page (keyset, bound to the list and its order); anything else is 400 invalid with `field: cursor`. |

### Responses

- **200** Calls (`application/json`)

Fields of the 200 answer:

- `items` (array of object, required)
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page.

Example 200 answer:

```json
{
  "items": [
    {
      "actorRef": "sophie.huber@muster-it.example",
      "confidence": 0.91,
      "createdAt": "2026-11-17T07:12:20Z",
      "customerId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
      "feature": "triage",
      "id": "4b0c1d2e-5f6a-4b7c-9d8e-0f1a2b3c4d02",
      "inputTokens": 1840,
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "latencyMs": 1210,
      "model": "decision",
      "outcome": "succeeded",
      "outputTokens": 96,
      "providerKind": "platform",
      "role": "decision"
    }
  ],
  "nextCursor": "eyJpZCI6IjRiMGMxZDJlIn0"
}
```

### Example request

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

## Suggestions, decisions, ratings and tokens per feature (desk:admin, KI-014)

`GET /api/desk/v1/ai/stats`

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

### Responses

- **200** Stats (`application/json`)

Fields of the 200 answer:

- `items` (array of object, required)
  - `acceptRate` (number, nullable)
  - `avgConfidence` (number, nullable)
  - `byStatus` (object)
  - `feature` (string)
  - `negativeRating` (integer)
  - `positiveRating` (integer)
  - `tokens` (integer)
  - `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "acceptRate": 0.89,
      "avgConfidence": 0.84,
      "byStatus": {
        "accepted": 71,
        "auto_applied": 30,
        "pending": 18,
        "rejected": 9
      },
      "feature": "triage",
      "negativeRating": 3,
      "positiveRating": 22,
      "tokens": 241300,
      "total": 128
    },
    {
      "acceptRate": 0.97,
      "avgConfidence": 0.81,
      "byStatus": {
        "auto_applied": 58,
        "pending": 4,
        "undone": 2
      },
      "feature": "summary",
      "negativeRating": 1,
      "positiveRating": 6,
      "tokens": 98400,
      "total": 64
    }
  ]
}
```

### Example request

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

## Per-customer AI switches (desk:admin, KI-009)

`GET /api/desk/v1/ai/customers`

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

### Responses

- **200** Switches (`application/json`)

Fields of the 200 answer:

- `items` (array of object, required)
  - `customerId` (string)
  - `enabled` (boolean)
  - `feature` (string)

Example 200 answer:

```json
{
  "items": [
    {
      "customerId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12",
      "enabled": false,
      "feature": "draftReply"
    }
  ]
}
```

### Example request

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

## Turn a feature (or * for all) on or off for a customer; enabled null removes the switch (desk:admin)

`PUT /api/desk/v1/ai/customers/{customerId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `customerId` | path | string | yes |  |

### Request body

`application/json` (required)

- `feature` (string, required)
- `customerName` (string): Name shown in the list (kept when empty)
- `enabled` (boolean, nullable)

Example:

```json
{
  "customerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "enabled": false,
  "feature": "draftReply"
}
```

### Responses

- **204** Saved

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/ai/customers/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customerName":"Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB","enabled":false,"feature":"draftReply"}'
```

## Ask for an AI suggestion (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/ai/{feature}`

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

Nothing changes until a person accepts the suggestion, unless the tenant lets triage (each value above a confidence threshold; text read from the ticket never) or subjects apply themselves. A triage run that applied a part answers that suggestion; the rest is a second, pending one. Draft replies are never applied or sent automatically. Confidential items are never sent to AI.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `feature` | path | string | yes | (one of `triage`, `subject`, `summary`, `draftReply`) |

### Responses

- **201** Suggestion (`application/json`)
- **422** The feature does not run for this item

Fields of the 201 answer:

- `appliedChanges` (array of object): Changes the suggestion made to the item
- `confidence` (number, nullable): Lowest confidence of the decisions; null when the suggestion holds none (e.g. only text read from the ticket)
- `createdAt` (string (date-time)): When it was made
- `decidedAt` (string (date-time)): When it was decided
- `decidedBy` (string): Login (e-mail) of who decided
- `editedPayload` (object): What the person accepted when it differs from the proposal
- `feature` (string): AI feature that made it (one of `triage`, `subject`, `summary`, `draftReply`)
- `feedbackNote` (string): Note with the rating
- `feedbackRating` (integer): Rating of the suggestion
- `id` (string): Id of the suggestion
- `itemId` (string): Item the suggestion is for
- `method` (string): How the ai module answered (e.g. chat)
- `model` (string): Model that answered
- `payload` (object): triage: TriagePayload; others: { text }
- `reason` (string): Why the model proposes it
- `status` (string): State of the suggestion (one of `pending`, `accepted`, `rejected`, `auto_applied`, `superseded`, `undone`)

Example 201 answer:

```json
{
  "confidence": 0.82,
  "createdAt": "2026-11-17T08:42:10Z",
  "feature": "summary",
  "id": "6a3b4c5d-7e8f-4a9b-8c1d-3e4f5a6b7c01",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "method": "llm",
  "model": "medium",
  "payload": {
    "text": "WLAN im 2. OG bricht ab: AP-207 startet ständig neu, weil das PoE-Budget des Etagen-Switch überschritten ist. Austausch des Switch heute 14 Uhr vor Ort."
  },
  "reason": "Aus Beschreibung und internen Notizen zusammengefasst",
  "status": "pending"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/ai/triage' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## AI suggestions of an item, newest first (desk:read)

`GET /api/desk/v1/items/{ref}/suggestions`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Suggestions (`application/json`)

Fields of the 200 answer:

- `items` (array of Suggestion, required)
  - `appliedChanges` (array of object): Changes the suggestion made to the item
  - `confidence` (number, nullable): Lowest confidence of the decisions; null when the suggestion holds none (e.g. only text read from the ticket)
  - `createdAt` (string (date-time)): When it was made
  - `decidedAt` (string (date-time)): When it was decided
  - `decidedBy` (string): Login (e-mail) of who decided
  - `editedPayload` (object): What the person accepted when it differs from the proposal
  - `feature` (string): AI feature that made it (one of `triage`, `subject`, `summary`, `draftReply`)
  - `feedbackNote` (string): Note with the rating
  - `feedbackRating` (integer): Rating of the suggestion
  - `id` (string): Id of the suggestion
  - `itemId` (string): Item the suggestion is for
  - `method` (string): How the ai module answered (e.g. chat)
  - `model` (string): Model that answered
  - `payload` (object): triage: TriagePayload; others: { text }
  - `reason` (string): Why the model proposes it
  - `status` (string): State of the suggestion (one of `pending`, `accepted`, `rejected`, `auto_applied`, `superseded`, `undone`)

Example 200 answer:

```json
{
  "items": [
    {
      "confidence": 0.88,
      "createdAt": "2026-11-17T07:12:20Z",
      "decidedAt": "2026-11-17T07:15:00Z",
      "decidedBy": "sophie.huber@muster-it.example",
      "feature": "triage",
      "id": "6a3b4c5d-7e8f-4a9b-8c1d-3e4f5a6b7c02",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "method": "decision",
      "model": "decision",
      "payload": {
        "category": {
          "confidence": 0.93,
          "label": "Netzwerk › WLAN",
          "value": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02"
        },
        "priority": {
          "confidence": 0.91,
          "label": "Hoch",
          "value": "hoch"
        },
        "team": {
          "confidence": 0.88,
          "label": "Technik",
          "value": "second-level"
        }
      },
      "status": "accepted"
    }
  ]
}
```

### Example request

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

## Accept (optionally edited), reject or undo a suggestion (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/suggestions/{sid}/{decision}`

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

Accepting a draftReply only records the acceptance (no entry, no mail; the UI puts the text into the reply box), and a draftReply cannot be undone (400).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `sid` | path | string | yes |  |
| `decision` | path | string | yes | (one of `accept`, `reject`, `undo`) |

### Request body

`application/json`

- `payload` (object): Edited proposal (accept only)

Example:

```json
{
  "payload": {
    "text": "WLAN im 2. OG bricht ab: AP-207 startet ständig neu (PoE-Budget des Etagen-Switch überschritten). Switch wird heute getauscht."
  }
}
```

### Responses

- **200** Suggestion (`application/json`)

Fields of the 200 answer:

- `appliedChanges` (array of object): Changes the suggestion made to the item
- `confidence` (number, nullable): Lowest confidence of the decisions; null when the suggestion holds none (e.g. only text read from the ticket)
- `createdAt` (string (date-time)): When it was made
- `decidedAt` (string (date-time)): When it was decided
- `decidedBy` (string): Login (e-mail) of who decided
- `editedPayload` (object): What the person accepted when it differs from the proposal
- `feature` (string): AI feature that made it (one of `triage`, `subject`, `summary`, `draftReply`)
- `feedbackNote` (string): Note with the rating
- `feedbackRating` (integer): Rating of the suggestion
- `id` (string): Id of the suggestion
- `itemId` (string): Item the suggestion is for
- `method` (string): How the ai module answered (e.g. chat)
- `model` (string): Model that answered
- `payload` (object): triage: TriagePayload; others: { text }
- `reason` (string): Why the model proposes it
- `status` (string): State of the suggestion (one of `pending`, `accepted`, `rejected`, `auto_applied`, `superseded`, `undone`)

Example 200 answer:

```json
{
  "confidence": 0.82,
  "createdAt": "2026-11-17T08:42:10Z",
  "feature": "summary",
  "id": "6a3b4c5d-7e8f-4a9b-8c1d-3e4f5a6b7c01",
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "method": "llm",
  "model": "medium",
  "payload": {
    "text": "WLAN im 2. OG bricht ab: AP-207 startet ständig neu, weil das PoE-Budget des Etagen-Switch überschritten ist. Austausch des Switch heute 14 Uhr vor Ort."
  },
  "reason": "Aus Beschreibung und internen Notizen zusammengefasst",
  "status": "pending"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/suggestions/string/accept' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"payload":{"text":"WLAN im 2. OG bricht ab: AP-207 startet ständig neu (PoE-Budget des Etagen-Switch überschritten). Switch wird heute getauscht."}}'
```

## Rate a suggestion (KI-015) (desk:write)

`POST /api/desk/v1/items/{ref}/suggestions/{sid}/feedback`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `sid` | path | string | yes |  |

### Request body

`application/json` (required)

- `rating` (integer, required): (one of `1`, `-1`)
- `note` (string)

Example:

```json
{
  "note": "Zusammenfassung trifft es genau.",
  "rating": 1
}
```

### Responses

- **204** Saved

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/suggestions/string/feedback' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Zusammenfassung trifft es genau.","rating":1}'
```

# SLA

## SLA policies in matching order (desk:admin)

`GET /api/desk/v1/sla/policies`

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

### Responses

- **200** Policies (`application/json`)

Fields of the 200 answer:

- `items` (array of SLAPolicy, required)
  - `key` (string, required): Key of the policy, unique in the tenant
  - `name` (string, required): Name of the policy
  - `targets` (array of object, required): Targets of the policy
    - `minutes` (integer, required): Target in minutes
    - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
    - `byPriority` (object): Minutes per priority key
    - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
      - `id` (string, required): Key-like id
      - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
      - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
    - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
    - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
  - `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
  - `calendar` (string): Calendar key; empty = the default calendar
  - `description` (string): Description of the policy
  - `enabled` (boolean): Disabled policies never match
  - `id` (string, read-only): Id of the policy
  - `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
  - `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
  - `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
  - `version` (integer): Version of the policy; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "items": [
    {
      "enabled": true,
      "id": "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01",
      "key": "standard",
      "match": "trigger.data.spaceKey == \"SUP\"",
      "name": "Standard",
      "position": 0,
      "targets": [
        {
          "minutes": 240,
          "mode": "business",
          "target": "first_response",
          "warnPercent": 80
        },
        {
          "byPriority": {
            "hoch": 480,
            "kritisch": 240,
            "niedrig": 2880,
            "normal": 1440
          },
          "minutes": 1440,
          "mode": "business",
          "target": "resolution",
          "warnPercent": 80
        }
      ],
      "version": 2
    }
  ]
}
```

### Example request

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

## Create an SLA policy (desk:admin)

`POST /api/desk/v1/sla/policies`

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

Policies are ordered; the first enabled policy whose match condition holds applies to a new item. Running clocks keep the values they started with (SLA-008); see POST /sla/recalculate.

### Request body

`application/json` (required)

- `key` (string, required): Key of the policy, unique in the tenant
- `name` (string, required): Name of the policy
- `targets` (array of object, required): Targets of the policy
  - `minutes` (integer, required): Target in minutes
  - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
  - `byPriority` (object): Minutes per priority key
  - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
    - `id` (string, required): Key-like id
    - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
    - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
  - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
  - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
- `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
- `calendar` (string): Calendar key; empty = the default calendar
- `description` (string): Description of the policy
- `enabled` (boolean): Disabled policies never match
- `id` (string, read-only): Id of the policy
- `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
- `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
- `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
- `version` (integer): Version of the policy; 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
{
  "calendar": "geschaeftszeiten",
  "description": "Kürzere Ziele für Tickets mit dem Label vip",
  "enabled": true,
  "key": "vip",
  "match": "\"vip\" in trigger.data.labels",
  "name": "VIP-Kunden",
  "note": "Eigene Ziele für die Geschäftsführung unserer Kunden",
  "reevaluateOn": [
    "priority"
  ],
  "targets": [
    {
      "minutes": 60,
      "mode": "business",
      "target": "first_response",
      "warnPercent": 75
    },
    {
      "minutes": 480,
      "mode": "business",
      "target": "resolution",
      "warnPercent": 75
    }
  ]
}
```

### Responses

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

Fields of the 201 answer:

- `key` (string, required): Key of the policy, unique in the tenant
- `name` (string, required): Name of the policy
- `targets` (array of object, required): Targets of the policy
  - `minutes` (integer, required): Target in minutes
  - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
  - `byPriority` (object): Minutes per priority key
  - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
    - `id` (string, required): Key-like id
    - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
    - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
  - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
  - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
- `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
- `calendar` (string): Calendar key; empty = the default calendar
- `description` (string): Description of the policy
- `enabled` (boolean): Disabled policies never match
- `id` (string, read-only): Id of the policy
- `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
- `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
- `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
- `version` (integer): Version of the policy; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "archived": false,
  "calendar": "geschaeftszeiten",
  "description": "Erste Reaktion in 4 Stunden, Lösung je nach Priorität (Geschäftszeiten)",
  "enabled": true,
  "id": "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01",
  "key": "standard",
  "match": "trigger.data.spaceKey == \"SUP\"",
  "name": "Standard",
  "position": 0,
  "reevaluateOn": [
    "priority"
  ],
  "targets": [
    {
      "escalations": [
        {
          "id": "reaktion-ueberfaellig",
          "name": "Die erste Reaktion ist überfällig",
          "percent": 100
        }
      ],
      "minutes": 240,
      "mode": "business",
      "target": "first_response",
      "warnPercent": 80
    },
    {
      "byPriority": {
        "hoch": 480,
        "kritisch": 240,
        "niedrig": 2880,
        "normal": 1440
      },
      "escalations": [
        {
          "id": "loesung-ueberfaellig",
          "name": "Die Lösung ist überfällig",
          "percent": 100
        }
      ],
      "minutes": 1440,
      "mode": "business",
      "target": "resolution",
      "warnPercent": 80
    }
  ],
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/sla/policies' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"calendar":"geschaeftszeiten","description":"Kürzere Ziele für Tickets mit dem Label vip","enabled":true,"key":"vip","match":"\"vip\" in trigger.data.labels","name":"VIP-Kunden","note":"Eigene Ziele für die Geschäftsführung unserer Kunden","reevaluateOn":["priority"],"targets":[{"minutes":60,"mode":"business","target":"first_response","warnPercent":75},{"minutes":480,"mode":"business","target":"resolution","warnPercent":75}]}'
```

## Update an SLA policy (needs the current version), or check its impact first with dryRun (desk:admin)

`PUT /api/desk/v1/sla/policies/{id}`

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

With `dryRun=true` nothing is saved: the policy is validated as for saving and the answer is its impact on the
open tickets the admin sees (at most 500, `truncated` when there are more) – how many it matches now and would
match after the change, and up to ten ticket numbers it gains and loses. Running clocks keep their policy until
`POST /sla/recalculate`; new clocks follow the change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `dryRun` | query | boolean |  | Answer the impact, save nothing |

### Request body

`application/json` (required)

- `key` (string, required): Key of the policy, unique in the tenant
- `name` (string, required): Name of the policy
- `targets` (array of object, required): Targets of the policy
  - `minutes` (integer, required): Target in minutes
  - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
  - `byPriority` (object): Minutes per priority key
  - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
    - `id` (string, required): Key-like id
    - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
    - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
  - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
  - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
- `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
- `calendar` (string): Calendar key; empty = the default calendar
- `description` (string): Description of the policy
- `enabled` (boolean): Disabled policies never match
- `id` (string, read-only): Id of the policy
- `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
- `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
- `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
- `version` (integer): Version of the policy; 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
{
  "enabled": true,
  "id": "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01",
  "key": "standard",
  "match": "trigger.data.spaceKey == \"SUP\"",
  "name": "Standard",
  "note": "Erste Reaktion auf drei Stunden verkürzt",
  "targets": [
    {
      "minutes": 180,
      "mode": "business",
      "target": "first_response",
      "warnPercent": 80
    },
    {
      "byPriority": {
        "hoch": 480,
        "kritisch": 240,
        "niedrig": 2880,
        "normal": 1440
      },
      "minutes": 1440,
      "mode": "business",
      "target": "resolution",
      "warnPercent": 80
    }
  ],
  "version": 2
}
```

### Responses

- **200** Saved (the policy), or with dryRun the impact (`application/json`)
- **409** Version conflict

Fields of the 200 answer:

- `key` (string, required): Key of the policy, unique in the tenant
- `name` (string, required): Name of the policy
- `targets` (array of object, required): Targets of the policy
  - `minutes` (integer, required): Target in minutes
  - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
  - `byPriority` (object): Minutes per priority key
  - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
    - `id` (string, required): Key-like id
    - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
    - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
  - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
  - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
- `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
- `calendar` (string): Calendar key; empty = the default calendar
- `description` (string): Description of the policy
- `enabled` (boolean): Disabled policies never match
- `id` (string, read-only): Id of the policy
- `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
- `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
- `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
- `version` (integer): Version of the policy; send it back on change (409 version_conflict when it is outdated)
- `checked` (integer, required): Open tickets evaluated
- `dryRun` (boolean, required): Always true – tells the impact from a saved policy
- `gained` (array of string, required): Up to ten ticket numbers (`#123`) the policy would newly match
- `lost` (array of string, required): Up to ten ticket numbers it would no longer match
- `matchAfter` (integer, required)
- `matchedNow` (integer, required)
- `truncated` (boolean, required): There were more open tickets than evaluated

Example 200 answer:

```json
{
  "checked": 42,
  "dryRun": true,
  "gained": [
    "#37",
    "#41"
  ],
  "lost": [],
  "matchAfter": 33,
  "matchedNow": 31,
  "truncated": false
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/sla/policies/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":true,"id":"9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01","key":"standard","match":"trigger.data.spaceKey == \"SUP\"","name":"Standard","note":"Erste Reaktion auf drei Stunden verkürzt","targets":[{"minutes":180,"mode":"business","target":"first_response","warnPercent":80},{"byPriority":{"hoch":480,"kritisch":240,"niedrig":2880,"normal":1440},"minutes":1440,"mode":"business","target":"resolution","warnPercent":80}],"version":2}'
```

## Set the matching order (desk:admin)

`POST /api/desk/v1/sla/policies/reorder`

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

### Request body

`application/json` (required)

- `ids` (array of string, required)

Example:

```json
{
  "ids": [
    "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f02",
    "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01"
  ]
}
```

### Responses

- **200** Policies in the new order (`application/json`)

Fields of the 200 answer:

- `items` (array of SLAPolicy, required)
  - `key` (string, required): Key of the policy, unique in the tenant
  - `name` (string, required): Name of the policy
  - `targets` (array of object, required): Targets of the policy
    - `minutes` (integer, required): Target in minutes
    - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
    - `byPriority` (object): Minutes per priority key
    - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
      - `id` (string, required): Key-like id
      - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
      - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
    - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
    - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
  - `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
  - `calendar` (string): Calendar key; empty = the default calendar
  - `description` (string): Description of the policy
  - `enabled` (boolean): Disabled policies never match
  - `id` (string, read-only): Id of the policy
  - `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
  - `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
  - `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
  - `version` (integer): Version of the policy; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "items": [
    {
      "enabled": true,
      "id": "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f02",
      "key": "vip",
      "match": "\"vip\" in trigger.data.labels",
      "name": "VIP-Kunden",
      "position": 0,
      "targets": [
        {
          "minutes": 60,
          "mode": "business",
          "target": "first_response"
        }
      ],
      "version": 1
    },
    {
      "enabled": true,
      "id": "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01",
      "key": "standard",
      "match": "trigger.data.spaceKey == \"SUP\"",
      "name": "Standard",
      "position": 1,
      "targets": [
        {
          "minutes": 240,
          "mode": "business",
          "target": "first_response"
        }
      ],
      "version": 3
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/sla/policies/reorder' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f02","9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01"]}'
```

## Which policy applies to an item and when its targets would be due (desk:admin)

`POST /api/desk/v1/sla/policies/test`

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

### Request body

`application/json` (required)

- `itemId` (string, required)

Example:

```json
{
  "itemId": "#1"
}
```

### Responses

- **200** Result (`application/json`)

Fields of the 200 answer:

- `checked` (array of object): Every policy in order with the result of its match
  - `enabled` (boolean, required)
  - `key` (string, required)
  - `match` (string, required): The policy's match expression
  - `matched` (boolean, required)
  - `name` (string, required)
  - `error` (string): Why the match could not be evaluated for the item (such a policy does not apply)
- `policy` (SLAPolicy)
  - `key` (string, required): Key of the policy, unique in the tenant
  - `name` (string, required): Name of the policy
  - `targets` (array of object, required): Targets of the policy
    - `minutes` (integer, required): Target in minutes
    - `target` (string, required): What is measured (one of `first_response`, `resolution`, `next_response`)
    - `byPriority` (object): Minutes per priority key
    - `escalations` (array of object): Levels of the target: when a clock reaches `percent` of it, desk writes the event `desk.sla.escalated` with the level – what happens then is an automation's or a flow's (a level has no actions of its own).
      - `id` (string, required): Key-like id
      - `percent` (integer, required): Share of the target at which the level is reached (max 1000)
      - `name` (string): Name of the level (at most 120 characters), in the event as `escalation.name`
    - `mode` (string): business: service hours of the calendar; wall: wall-clock time (one of `business`, `wall`)
    - `warnPercent` (integer): Share of the target at which the clock warns (default `80`)
  - `archived` (boolean): Archived: the policy is kept for existing data but no longer offered in pickers
  - `calendar` (string): Calendar key; empty = the default calendar
  - `description` (string): Description of the policy
  - `enabled` (boolean): Disabled policies never match
  - `id` (string, read-only): Id of the policy
  - `match` (string): The tickets the policy applies to: a bool expression in the flow language over `trigger.data`, the ticket's event payload (`GET /conditions/catalog`, `item`) – the first enabled policy whose match holds applies. Empty: every ticket. One that cannot be evaluated for a ticket does not hold (logged). (max length 4000)
  - `position` (integer, read-only): Matching order (the first enabled policy that matches applies)
  - `reevaluateOn` (array of string): Item fields whose change re-matches the policy and recalculates running clocks (e.g. priority)
  - `version` (integer): Version of the policy; send it back on change (409 version_conflict when it is outdated)
- `targets` (array of SLAClock)
  - `breachedAt` (string (date-time), nullable): When the target was breached
  - `cycle` (integer): Cycle of the target on the item (a target can run more than once)
  - `dueAt` (string (date-time), nullable): When the target is due
  - `itemId` (string): Item of the clock
  - `metAt` (string (date-time), nullable): When the target was met
  - `mode` (string): business: counts service hours; wall: counts wall-clock time
  - `percent` (integer): Share of the target used (percent)
  - `policyKey` (string): Policy the clock started with
  - `startedAt` (string (date-time)): When the clock started
  - `state` (string): State of the clock (one of `running`, `paused`, `met`, `stopped`)
  - `target` (string): Target the clock measures
  - `targetMinutes` (integer): Target in minutes
  - `usedMinutes` (integer): Minutes used so far
  - `warnAt` (string (date-time), nullable): When the warning is due
  - `warnedAt` (string (date-time), nullable): When the warning was written

Example 200 answer:

```json
{
  "checked": [
    {
      "enabled": true,
      "key": "vip",
      "match": "\"vip\" in trigger.data.labels",
      "matched": false,
      "name": "VIP-Kunden"
    },
    {
      "enabled": true,
      "key": "standard",
      "match": "trigger.data.spaceKey == \"SUP\"",
      "matched": true,
      "name": "Standard"
    }
  ],
  "policy": {
    "enabled": true,
    "id": "9d6e7f8a-0b1c-4d2e-9f4a-6b7c8d9e0f01",
    "key": "standard",
    "match": "trigger.data.spaceKey == \"SUP\"",
    "name": "Standard",
    "targets": [
      {
        "byPriority": {
          "hoch": 480
        },
        "minutes": 1440,
        "mode": "business",
        "target": "resolution"
      }
    ],
    "version": 2
  },
  "targets": [
    {
      "cycle": 1,
      "dueAt": "2026-11-17T11:12:00Z",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "metAt": "2026-11-17T07:20:04Z",
      "mode": "business",
      "percent": 3,
      "policyKey": "standard",
      "startedAt": "2026-11-17T07:12:00Z",
      "state": "met",
      "target": "first_response",
      "targetMinutes": 240,
      "usedMinutes": 8
    },
    {
      "cycle": 1,
      "dueAt": "2026-11-17T15:12:00Z",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "mode": "business",
      "percent": 21,
      "policyKey": "standard",
      "startedAt": "2026-11-17T07:12:00Z",
      "state": "running",
      "target": "resolution",
      "targetMinutes": 480,
      "usedMinutes": 103,
      "warnAt": "2026-11-17T13:36:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/sla/policies/test' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"itemId":"#1"}'
```

## Apply the current policies to open items with running clocks (desk:admin, SLA-008)

`POST /api/desk/v1/sla/recalculate`

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

Every moved deadline is recorded in the item history (sla_recalculated). At most 1000 items per run.

### Request body

`application/json`

- `dryRun` (boolean)
- `policy` (string): Policy id or key; empty = all

Example:

```json
{
  "dryRun": true,
  "policy": "standard"
}
```

### Responses

- **200** Result (`application/json`)

Fields of the 200 answer:

- `changed` (integer)
- `dryRun` (boolean)
- `items` (integer)
- `truncated` (boolean)

Example 200 answer:

```json
{
  "changed": 7,
  "dryRun": true,
  "items": 42,
  "truncated": false
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/sla/recalculate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"dryRun":true,"policy":"standard"}'
```

## SLA clocks of an item with the share of the target used (desk:read)

`GET /api/desk/v1/items/{ref}/sla`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Clocks (`application/json`)

Fields of the 200 answer:

- `items` (array of SLAClock, required)
  - `breachedAt` (string (date-time), nullable): When the target was breached
  - `cycle` (integer): Cycle of the target on the item (a target can run more than once)
  - `dueAt` (string (date-time), nullable): When the target is due
  - `itemId` (string): Item of the clock
  - `metAt` (string (date-time), nullable): When the target was met
  - `mode` (string): business: counts service hours; wall: counts wall-clock time
  - `percent` (integer): Share of the target used (percent)
  - `policyKey` (string): Policy the clock started with
  - `startedAt` (string (date-time)): When the clock started
  - `state` (string): State of the clock (one of `running`, `paused`, `met`, `stopped`)
  - `target` (string): Target the clock measures
  - `targetMinutes` (integer): Target in minutes
  - `usedMinutes` (integer): Minutes used so far
  - `warnAt` (string (date-time), nullable): When the warning is due
  - `warnedAt` (string (date-time), nullable): When the warning was written

Example 200 answer:

```json
{
  "items": [
    {
      "cycle": 1,
      "dueAt": "2026-11-17T11:12:00Z",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "metAt": "2026-11-17T07:20:04Z",
      "mode": "business",
      "percent": 3,
      "policyKey": "standard",
      "startedAt": "2026-11-17T07:12:00Z",
      "state": "met",
      "target": "first_response",
      "targetMinutes": 240,
      "usedMinutes": 8
    },
    {
      "cycle": 1,
      "dueAt": "2026-11-17T15:12:00Z",
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "mode": "business",
      "percent": 21,
      "policyKey": "standard",
      "startedAt": "2026-11-17T07:12:00Z",
      "state": "running",
      "target": "resolution",
      "targetMinutes": 480,
      "usedMinutes": 103,
      "warnAt": "2026-11-17T13:36:00Z"
    }
  ]
}
```

### Example request

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

## Apply the current policy values to the item's clocks (desk:write, space maintainer; recorded in the history)

`POST /api/desk/v1/items/{ref}/sla/recalculate`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** The item (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/sla/recalculate' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Automation

## What the conditions of SLA policies and mail routes can test (desk:admin)

`GET /api/desk/v1/conditions/catalog`

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

The conditions of desk's settings are bool expressions in the flow language over `trigger.data` – the language of an automation trigger's `filter` (ADR 0044). `item` describes `trigger.data` of a condition about a ticket (the `match` of an SLA policy): the ticket's event payload, the schema of desk's ticket events. `mail` describes it for the condition of a mail source route: the facts of the received mail. Each comes with its JSON schema and the fields for a condition editor – `path` (the expression reads `trigger.data.<path>`), `type` (string, number, boolean, list, datetime), `label` (de, en) and, where the field has a known set, `values` (the tenant's keys and names; one field per custom field as `fields.<key>`). `functions` are the functions an expression may call. A condition is checked when it is saved: one that does not compile, reads a field the schema does not have or yields no true/false is 400 `invalid` on `match` / `routes[n].condition` with the message.

### Responses

- **200** The catalogue (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `functions` (array of string, required): Functions an expression may call
- `item` (ConditionSubject, required)
  - `fields` (array of object, required): Fields a condition can test
    - `label` (object, required): Label of the field
      - `de` (string, required): German label
      - `en` (string, required): English label
    - `path` (string, required): Field below `trigger.data` (`priority`, `fields.risiko`)
    - `type` (string, required): Value type of the field (one of `string`, `number`, `boolean`, `list`, `datetime`)
    - `values` (array of object): The values to choose from, when the field has a known set
      - `label` (object, required): Label of the value
        - `de` (string, required): German label
        - `en` (string, required): English label
      - `value` (string, required): A value the field can have
  - `schema` (object, required): JSON schema of `trigger.data`
- `mail` (ConditionSubject, required)
  - `fields` (array of object, required): Fields a condition can test
    - `label` (object, required): Label of the field
      - `de` (string, required): German label
      - `en` (string, required): English label
    - `path` (string, required): Field below `trigger.data` (`priority`, `fields.risiko`)
    - `type` (string, required): Value type of the field (one of `string`, `number`, `boolean`, `list`, `datetime`)
    - `values` (array of object): The values to choose from, when the field has a known set
      - `label` (object, required): Label of the value
        - `de` (string, required): German label
        - `en` (string, required): English label
      - `value` (string, required): A value the field can have
  - `schema` (object, required): JSON schema of `trigger.data`

Example 200 answer:

```json
{
  "functions": [
    "len",
    "any",
    "all",
    "contains",
    "hasPrefix",
    "lower",
    "now"
  ],
  "item": {
    "fields": [
      {
        "label": {
          "de": "Bereich",
          "en": "Space"
        },
        "path": "spaceKey",
        "type": "string",
        "values": [
          {
            "label": {
              "de": "Support",
              "en": "Support"
            },
            "value": "SUP"
          },
          {
            "label": {
              "de": "Kundenprojekte",
              "en": "Kundenprojekte"
            },
            "value": "PRJ"
          }
        ]
      },
      {
        "label": {
          "de": "Priorität",
          "en": "Priority"
        },
        "path": "priority",
        "type": "string",
        "values": [
          {
            "label": {
              "de": "Kritisch",
              "en": "Kritisch"
            },
            "value": "kritisch"
          },
          {
            "label": {
              "de": "Hoch",
              "en": "Hoch"
            },
            "value": "hoch"
          }
        ]
      },
      {
        "label": {
          "de": "Labels",
          "en": "Labels"
        },
        "path": "labels",
        "type": "list"
      },
      {
        "label": {
          "de": "Betroffenes System",
          "en": "Betroffenes System"
        },
        "path": "fields.betroffenes_system",
        "type": "string"
      }
    ],
    "schema": {
      "properties": {
        "labels": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "priority": {
          "type": "string"
        },
        "spaceKey": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "mail": {
    "fields": [
      {
        "label": {
          "de": "Absender-Domain",
          "en": "Sender domain"
        },
        "path": "fromDomain",
        "type": "string"
      },
      {
        "label": {
          "de": "Betreff",
          "en": "Subject"
        },
        "path": "subject",
        "type": "string"
      },
      {
        "label": {
          "de": "Mit Anhang",
          "en": "Has attachments"
        },
        "path": "hasAttachments",
        "type": "boolean"
      }
    ],
    "schema": {
      "properties": {
        "from": {
          "type": "string"
        },
        "fromDomain": {
          "type": "string"
        },
        "subject": {
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}
```

### Example request

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

## List the automations of the tenant or of a space (desk access; a space the caller sees)

`GET /api/desk/v1/automations`

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

Scope `tenant`: everyone with desk access. Scope `space:<id>`: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 `scope`). In position order, each with its newest execution (`lastRun`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Responses

- **200** The automations (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Automation, required)
  - `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
  - `createdAt` (string (date-time), required): When the automation was created
  - `createdBy` (string, required): E-mail of who created it
  - `description` (string, required): The description of the definition
  - `enabled` (boolean, required): Only an enabled automation with a valid definition runs
  - `events` (array of string, required): The event types its triggers listen to
  - `id` (string (uuid), required): Id of the automation
  - `key` (string, required): The key of the definition, unique per scope
  - `manual` (boolean, required): Whether the definition has a manual trigger
  - `name` (string, required): The name of the definition (the actor name of the automation's changes)
  - `position` (integer, required): Automations that listen to the same event run in position order
  - `scope` (string, required): What the automation belongs to: `tenant` or `space:<space id>`
  - `updatedAt` (string (date-time), required): When the automation was last changed
  - `updatedBy` (string, required): E-mail of who changed it last
  - `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
  - `version` (integer, required): Name it when changing or deleting the automation
  - `yaml` (string, required): The definition (YAML of the flow language)
  - `lastRun` (AutomationRun): One execution of an automation in its log.
    - `automationId` (string (uuid), required): Automation that ran
    - `createdAt` (string (date-time), required): When the run happened
    - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
    - `durationMs` (integer, required): Duration of the run in milliseconds
    - `id` (string (uuid), required): Id of the run
    - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
    - `steps` (integer, required): The number of nodes that ran
    - `triggerKind` (string, required): event: started by an event; manual: started by a person on a ticket (one of `event`, `manual`)
    - `version` (integer, required): The version of the automation that ran
    - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
    - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
    - `errorMessage` (string): Why the run failed (only on failure)
    - `event` (string): The event type that started it
    - `node` (string): The id of the node that failed
    - `startedBy` (string): The person or actor behind the triggering change
    - `subject` (string): What the event was about: the item's id
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "blocking": false,
      "createdAt": "2026-10-05T09:00:00Z",
      "createdBy": "elias.gruber@muster-it.example",
      "description": "Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.",
      "enabled": true,
      "events": [
        "desk.item.created"
      ],
      "id": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
      "key": "kritische-stoerung-1st-level",
      "manual": false,
      "name": "Kritische Störung an den Service Desk",
      "position": 1,
      "scope": "tenant",
      "updatedAt": "2026-10-05T09:00:00Z",
      "updatedBy": "elias.gruber@muster-it.example",
      "valid": true,
      "version": 1,
      "yaml": "schemaVersion: 1\nkey: kritische-stoerung-1st-level\nname: Kritische Störung an den Service Desk\ntriggers:\n  - { id: neu, kind: event, event: desk.item.created, filter: 'trigger.data.typeKey == \"stoerung\" \u0026\u0026 trigger.data.priority == \"kritisch\"' }\nnodes:\n  zuweisen:\n    kind: action\n    action: desk.item.assign\n    params: { ref: \"{{ trigger.data.itemId }}\", team: first-level, teamRole: collaborating }\nedges:\n  - neu -\u003e zuweisen\n"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/automations?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an automation (desk:admin, or a maintainer of the space)

`POST /api/desk/v1/automations`

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

Scope `tenant`: `desk:admin`. Scope `space:<id>`: `desk:admin` or a maintainer of the space – the same people who manage the flows scoped to the space; others get 403. An automation is a definition in the flow language (YAML, the format of flows; ADR 0044) that may use desk's ticket events as triggers (`trigger.data` is the event's payload, see `x-flows-events`), a manual trigger (the ticket's „Aktionen“, `GET /items/{ref}/actions`; `trigger.data` is the ticket's event payload, and a `filter` on the trigger says on which tickets the action is offered), the nodes `if`, `switch`, `set`, `end`, `mail` and the actions `desk.item.update`, `desk.item.transition`, `desk.item.create`, `desk.entry.add`, `desk.link.add`, `desk.item.assign`, `desk.item.unassign`, `desk.item.add_label`, `desk.item.remove_label`, `desk.item.set_due`, `desk.item.set_follow_up`, `desk.item.comment_linked` and `desk.item.ai_suggest`. It runs immediately, in the transaction of the ticket change that triggered it – the tenant's automations before the space's, each scope in position order – as an internal writer named after the automation (author kind `rule`, actor kind `automation`; customers see the mailbox, never its name) and through the normal ticket rules (workflow transitions, required fields, SLA, history, outbox). **Scope rule:** an automation of a space acts only on tickets of that space – another space's ticket, another tenant's or an unknown one fails the action with `out_of_scope`; `desk.item.create` creates only in the space, `desk.item.comment_linked` leaves linked tickets of other spaces out. Tenant-wide automations act on every ticket of the tenant. The `mail` node sends the tenant's own text through comms (`tenant.message`, the tenant's default channel or `channel:<id>`); a confidential ticket reaches only the people on it, and a requester gets a mail only about a ticket they are on and can see – other recipients are dropped. Without `yaml` the automation starts from a skeleton named `name`; key and name come from the definition, the key is unique per scope (409 `key_taken`). A definition that cannot be read is 422 `invalid_definition` (`details.diagnostics`); one with errors is stored as a draft (`valid: false`) and cannot be enabled. Everything only a flow in the background can run (wait, human tasks, schedules, other modules' actions, …) is the finding `needs_durable`. An action the ticket rules refuse fails the run: its changes are rolled back and the failure is in the log (`GET /automations/{id}/runs`), the triggering change is kept – unless the automation is `blocking`, then the change is refused with 422 `automation_blocked` (only requests on this API; changes from mail, feeds, timers and the customer portal are never refused). A trigger ignores changes made by automations and the AI unless it says `includeAutomated: true`; then automations start each other at most 4 levels deep, each at most once per ticket per change, at most 20 per event. Nothing starts for the tombstone of a converted ticket.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Request body

`application/json` (required)

- `blocking` (boolean): A failure refuses the triggering change (422 `automation_blocked`) (default `false`)
- `enabled` (boolean): Needs a definition without errors (default `false`)
- `name` (string): Without `yaml`: the name of the new automation (its key is derived from it) (max length 200)
- `yaml` (string): The definition (YAML of the flow language, at most 256 KiB); key and name are read from it

Example:

```json
{
  "blocking": false,
  "enabled": true,
  "yaml": "schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\"vip\" in trigger.data.labels \u0026\u0026 trigger.data.priority in [\"niedrig\", \"normal\"]' }\nnodes:\n  hochstufen:\n    kind: action\n    name: Priorität hoch\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\nedges:\n  - label -\u003e hochstufen\n"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 201 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When the automation was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Id of the automation
- `key` (string, required): The key of the definition, unique per scope
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `tenant` or `space:<space id>`
- `updatedAt` (string (date-time), required): When the automation was last changed
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): Automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration of the run in milliseconds
  - `id` (string (uuid), required): Id of the run
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): event: started by an event; manual: started by a person on a ticket (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Why the run failed (only on failure)
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 201 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-10-05T09:00:00Z",
  "createdBy": "elias.gruber@muster-it.example",
  "description": "Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.",
  "enabled": true,
  "events": [
    "desk.item.created"
  ],
  "id": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
  "key": "kritische-stoerung-1st-level",
  "lastRun": {
    "actorKind": "person",
    "automationId": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
    "createdAt": "2026-11-17T12:05:01Z",
    "depth": 1,
    "durationMs": 21,
    "event": "desk.item.created",
    "id": "9e6f7a8b-0c1d-4e2f-9a4b-6c7d8e9f0a01",
    "outcome": "succeeded",
    "startedBy": "elias.gruber@muster-it.example",
    "steps": 1,
    "subject": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 1
  },
  "manual": false,
  "name": "Kritische Störung an den Service Desk",
  "position": 1,
  "scope": "tenant",
  "updatedAt": "2026-10-05T09:00:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "valid": true,
  "version": 1,
  "yaml": "schemaVersion: 1\nkey: kritische-stoerung-1st-level\nname: Kritische Störung an den Service Desk\ndescription: Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.\ntriggers:\n  - { id: neu, kind: event, event: desk.item.created, filter: 'trigger.data.typeKey == \"stoerung\" \u0026\u0026 trigger.data.priority == \"kritisch\"' }\nnodes:\n  zuweisen:\n    kind: action\n    name: Team Service Desk hinzufügen\n    action: desk.item.assign\n    params: { ref: \"{{ trigger.data.itemId }}\", team: first-level, teamRole: collaborating }\nedges:\n  - neu -\u003e zuweisen\n"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/automations?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"blocking":false,"enabled":true,"yaml":"schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\''\"vip\" in trigger.data.labels \u0026\u0026 trigger.data.priority in [\"niedrig\", \"normal\"]'\'' }\nnodes:\n  hochstufen:\n    kind: action\n    name: Priorität hoch\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\nedges:\n  - label -\u003e hochstufen\n"}'
```

## What desk's automations can use (desk access; a space the caller sees)

`GET /api/desk/v1/automations/catalog`

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

Scope `tenant`: everyone with desk access. Scope `space:<id>`: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 `scope`). The catalogue of the builder – the shape of flows' catalogue, cut down to what runs immediately – desk's events with their payload schemas, the actions with an immediate implementation, the node and trigger kinds of the inline profile (with the manual trigger), the expression namespaces and functions, the limits, and per action the parameters the builder prefills (`defaults`, `ref` ← the event's ticket).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Responses

- **200** The catalogue (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `defaults` (object, required): Per action key, the parameters the builder prefills when the action is added: the ones that address the item the event is about
- `functions` (array of string, required): The functions of the expression language
- `kinds` (array of object, required): The node kinds that run immediately, with their default ports and fields
  - `fields` (array of AutomationField, required): Settings of the node kind
    - `path` (string, required): Dotted below the node or trigger
    - `type` (string, required): Value type of the setting
    - `options` (array of string): Allowed values of the setting
    - `when` (object): The field applies only while the sibling field has one of the values
      - `equals` (array of string): Values of that setting for which this one applies
      - `field` (string): The setting this one depends on
  - `name` (string, required): Name of the node kind
  - `ports` (array of string, required): Output ports of the node kind
  - `retry` (boolean, required): Always false – an immediate automation is not retried
- `limits` (object, required): Limits an automation must stay within
  - `maxDepth` (integer, required): How deep automations start each other
  - `maxNodes` (integer, required): The most nodes of an immediate automation
  - `maxPerEvent` (integer, required): The most automations one event starts
- `modules` (array of object, required): forge's flows manifest, cut down to the actions with an immediate implementation: `nodes` (key, labels, parameter and output schemas) and `events` (type, labels, payload schema)
  - `events` (array of object): Events of the module an automation can start on
  - `module` (string): Module that offers the nodes and events
  - `nodes` (array of object): Action nodes of the module usable in an automation
  - `revision` (string): Revision of the module's flows manifest
  - `version` (integer): Version of the module's flows manifest
- `namespaces` (array of string, required): The names expressions read
- `profile` (string, required): Profile the catalog describes: inline (runs immediately in the transaction of the change) (one of `inline`)
- `retryFields` (array of AutomationField, required): Always empty
  - `path` (string, required): Dotted below the node or trigger
  - `type` (string, required): Value type of the setting
  - `options` (array of string): Allowed values of the setting
  - `when` (object): The field applies only while the sibling field has one of the values
    - `equals` (array of string): Values of that setting for which this one applies
    - `field` (string): The setting this one depends on
- `triggers` (array of object, required): The trigger kinds a definition may use here (forge - event only; nothing starts an automation by hand) with their fields
  - `fields` (array of AutomationField, required): Settings of the trigger kind
    - `path` (string, required): Dotted below the node or trigger
    - `type` (string, required): Value type of the setting
    - `options` (array of string): Allowed values of the setting
    - `when` (object): The field applies only while the sibling field has one of the values
      - `equals` (array of string): Values of that setting for which this one applies
      - `field` (string): The setting this one depends on
  - `name` (string, required): Name of the trigger kind

Example 200 answer:

```json
{
  "defaults": {
    "desk.item.add_label": {
      "ref": "{{ trigger.data.itemId }}"
    },
    "desk.item.assign": {
      "ref": "{{ trigger.data.itemId }}"
    }
  },
  "functions": [
    "len",
    "any",
    "all",
    "contains",
    "hasPrefix",
    "lower",
    "now"
  ],
  "kinds": [
    {
      "fields": [
        {
          "path": "condition",
          "type": "condition"
        }
      ],
      "name": "if",
      "ports": [
        "true",
        "false",
        "error"
      ],
      "retry": false
    },
    {
      "fields": [
        {
          "path": "to",
          "type": "recipients"
        },
        {
          "path": "subject",
          "type": "template"
        },
        {
          "path": "text",
          "type": "template"
        }
      ],
      "name": "mail",
      "ports": [
        "main",
        "error"
      ],
      "retry": false
    }
  ],
  "limits": {
    "maxDepth": 4,
    "maxNodes": 25,
    "maxPerEvent": 20
  },
  "modules": [
    {
      "events": [
        {
          "label": {
            "de": "Ticket angelegt",
            "en": "Ticket created"
          },
          "type": "desk.item.created"
        },
        {
          "label": {
            "de": "SLA eskaliert",
            "en": "SLA escalated"
          },
          "type": "desk.sla.escalated"
        }
      ],
      "module": "desk",
      "nodes": [
        {
          "access": "write",
          "key": "desk.item.assign",
          "label": {
            "de": "Ticket zuweisen",
            "en": "Assign ticket"
          }
        },
        {
          "access": "write",
          "key": "desk.item.add_label",
          "label": {
            "de": "Label hinzufügen",
            "en": "Add label"
          }
        },
        {
          "access": "write",
          "key": "desk.entry.add",
          "label": {
            "de": "Kommentar hinzufügen",
            "en": "Add comment"
          }
        }
      ],
      "revision": "7b1e44c2",
      "version": 1
    }
  ],
  "namespaces": [
    "trigger",
    "nodes",
    "vars",
    "error",
    "run"
  ],
  "profile": "inline",
  "retryFields": [],
  "triggers": [
    {
      "fields": [
        {
          "path": "event",
          "type": "event"
        },
        {
          "path": "filter",
          "type": "condition"
        },
        {
          "path": "includeAutomated",
          "type": "boolean"
        }
      ],
      "name": "event"
    },
    {
      "fields": [
        {
          "path": "filter",
          "type": "condition"
        }
      ],
      "name": "manual"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/automations/catalog?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Check an automation's definition without storing it (desk access; a space the caller sees)

`POST /api/desk/v1/automations/validate`

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

Scope `tenant`: everyone with desk access. Scope `space:<id>`: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 `scope`). Validates the YAML with the inline profile against desk's catalogue and answers the findings (the same codes, paths and positions as flows) and the ports of every node. `needsDurable` says that the definition is fine but for parts only a flow in the background can run.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Request body

`application/json` (required)

- `yaml` (string, required)

Example:

```json
{
  "yaml": "schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\"vip\" in trigger.data.labels' }\nnodes:\n  hochstufen:\n    kind: action\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\n    retry: { attempts: 3 }\nedges:\n  - label -\u003e hochstufen\n"
}
```

### Responses

- **200** The findings (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `diagnostics` (array of AutomationDiagnostic, required): Findings of the check (errors and warnings)
  - `code` (string, required): Stable code, e.g. `unknown_action`, `missing_param`, `expression`, `needs_durable`, `inline_ignored`
  - `message` (string, required): What is wrong
  - `severity` (string, required): Errors keep the automation from being enabled (one of `error`, `warning`)
  - `col` (integer): Column in the YAML definition
  - `line` (integer): Line in the YAML definition
  - `nodeId` (string): Node the finding refers to (empty: the whole definition)
  - `params` (object): `needs_durable`: `reason` (trigger, kind, action, foreign_action, foreign_event, recipient, too_many_nodes)
  - `path` (string): Dotted path in the definition
- `needsDurable` (boolean, required): A finding is `needs_durable`: the definition runs only as a flow in the background
- `permissions` (array of array of string, required): The any-of permission groups a flow with this definition would need
- `ports` (object, required): The output ports of every node that parsed, by node id (the builder's handles)
- `profile` (string, required): The profile the definition was checked with (one of `inline`)
- `valid` (boolean, required): No finding is an error

Example 200 answer:

```json
{
  "diagnostics": [
    {
      "code": "inline_ignored",
      "col": 7,
      "line": 12,
      "message": "Die Option „retry“ gilt nur für Flows im Hintergrund und wird hier ignoriert.",
      "nodeId": "hochstufen",
      "path": "nodes.hochstufen.retry",
      "severity": "warning"
    }
  ],
  "needsDurable": false,
  "permissions": [
    [
      "desk:write"
    ]
  ],
  "ports": {
    "hochstufen": [
      "main",
      "error"
    ]
  },
  "profile": "inline",
  "valid": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/automations/validate?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\''\"vip\" in trigger.data.labels'\'' }\nnodes:\n  hochstufen:\n    kind: action\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\n    retry: { attempts: 3 }\nedges:\n  - label -\u003e hochstufen\n"}'
```

## Set the order of a scope's automations (desk:admin, or a maintainer of the space)

`POST /api/desk/v1/automations/reorder`

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

Scope `tenant`: `desk:admin`. Scope `space:<id>`: `desk:admin` or a maintainer of the space – the same people who manage the flows scoped to the space; others get 403. `ids` names every automation of the scope exactly once (else 400 `ids`). Automations that listen to the same event run in this order, the tenant's before the space's.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Request body

`application/json` (required)

- `ids` (array of string (uuid), required)

Example:

```json
{
  "ids": [
    "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e02",
    "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01"
  ]
}
```

### Responses

- **204** Reordered
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/automations/reorder?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e02","8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01"]}'
```

## Read an automation (desk access; a space the caller sees)

`GET /api/desk/v1/automations/{id}`

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

Scope `tenant`: everyone with desk access. Scope `space:<id>`: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 `scope`). An automation of another scope or tenant is 404.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The automation (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When the automation was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Id of the automation
- `key` (string, required): The key of the definition, unique per scope
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `tenant` or `space:<space id>`
- `updatedAt` (string (date-time), required): When the automation was last changed
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): Automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration of the run in milliseconds
  - `id` (string (uuid), required): Id of the run
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): event: started by an event; manual: started by a person on a ticket (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Why the run failed (only on failure)
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 200 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-10-05T09:00:00Z",
  "createdBy": "elias.gruber@muster-it.example",
  "description": "Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.",
  "enabled": true,
  "events": [
    "desk.item.created"
  ],
  "id": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
  "key": "kritische-stoerung-1st-level",
  "lastRun": {
    "actorKind": "person",
    "automationId": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
    "createdAt": "2026-11-17T12:05:01Z",
    "depth": 1,
    "durationMs": 21,
    "event": "desk.item.created",
    "id": "9e6f7a8b-0c1d-4e2f-9a4b-6c7d8e9f0a01",
    "outcome": "succeeded",
    "startedBy": "elias.gruber@muster-it.example",
    "steps": 1,
    "subject": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 1
  },
  "manual": false,
  "name": "Kritische Störung an den Service Desk",
  "position": 1,
  "scope": "tenant",
  "updatedAt": "2026-10-05T09:00:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "valid": true,
  "version": 1,
  "yaml": "schemaVersion: 1\nkey: kritische-stoerung-1st-level\nname: Kritische Störung an den Service Desk\ndescription: Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.\ntriggers:\n  - { id: neu, kind: event, event: desk.item.created, filter: 'trigger.data.typeKey == \"stoerung\" \u0026\u0026 trigger.data.priority == \"kritisch\"' }\nnodes:\n  zuweisen:\n    kind: action\n    name: Team Service Desk hinzufügen\n    action: desk.item.assign\n    params: { ref: \"{{ trigger.data.itemId }}\", team: first-level, teamRole: collaborating }\nedges:\n  - neu -\u003e zuweisen\n"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete an automation and its log (desk:admin, or a maintainer of the space)

`DELETE /api/desk/v1/automations/{id}`

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

Scope `tenant`: `desk:admin`. Scope `space:<id>`: `desk:admin` or a maintainer of the space – the same people who manage the flows scoped to the space; others get 403. `version` is the version the caller read (400 without, 409 `version_conflict`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `version` | query | integer | yes | The automation's current version |
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/desk/v1/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?version=1&scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an automation (desk:admin, or a maintainer of the space)

`PATCH /api/desk/v1/automations/{id}`

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

Scope `tenant`: `desk:admin`. Scope `space:<id>`: `desk:admin` or a maintainer of the space – the same people who manage the flows scoped to the space; others get 403. Changes what is set: the definition (`yaml`; key and name follow it), `enabled`, `blocking`. `version` is required (409 `version_conflict`). Enabling needs a definition without errors (422 `invalid_definition` with `details.diagnostics`); a definition saved with errors switches the automation off. A key another automation of the scope has is 409 `key_taken`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): The version the caller read
- `blocking` (boolean): Whether the automation may refuse the change it reacts to
- `enabled` (boolean): Switch the automation on or off (on needs a definition without errors)
- `yaml` (string): The new definition

Example:

```json
{
  "enabled": false,
  "version": 1
}
```

### Responses

- **200** Changed (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When the automation was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Id of the automation
- `key` (string, required): The key of the definition, unique per scope
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `tenant` or `space:<space id>`
- `updatedAt` (string (date-time), required): When the automation was last changed
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): Automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration of the run in milliseconds
  - `id` (string (uuid), required): Id of the run
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): event: started by an event; manual: started by a person on a ticket (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Why the run failed (only on failure)
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 200 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-10-05T09:00:00Z",
  "createdBy": "elias.gruber@muster-it.example",
  "description": "Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.",
  "enabled": true,
  "events": [
    "desk.item.created"
  ],
  "id": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
  "key": "kritische-stoerung-1st-level",
  "lastRun": {
    "actorKind": "person",
    "automationId": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
    "createdAt": "2026-11-17T12:05:01Z",
    "depth": 1,
    "durationMs": 21,
    "event": "desk.item.created",
    "id": "9e6f7a8b-0c1d-4e2f-9a4b-6c7d8e9f0a01",
    "outcome": "succeeded",
    "startedBy": "elias.gruber@muster-it.example",
    "steps": 1,
    "subject": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 1
  },
  "manual": false,
  "name": "Kritische Störung an den Service Desk",
  "position": 1,
  "scope": "tenant",
  "updatedAt": "2026-10-05T09:00:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "valid": true,
  "version": 1,
  "yaml": "schemaVersion: 1\nkey: kritische-stoerung-1st-level\nname: Kritische Störung an den Service Desk\ndescription: Eine kritische Störung bekommt sofort das Team Service Desk als mitarbeitendes Team.\ntriggers:\n  - { id: neu, kind: event, event: desk.item.created, filter: 'trigger.data.typeKey == \"stoerung\" \u0026\u0026 trigger.data.priority == \"kritisch\"' }\nnodes:\n  zuweisen:\n    kind: action\n    name: Team Service Desk hinzufügen\n    action: desk.item.assign\n    params: { ref: \"{{ trigger.data.itemId }}\", team: first-level, teamRole: collaborating }\nedges:\n  - neu -\u003e zuweisen\n"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false,"version":1}'
```

## List the last executions of an automation (desk access; a space the caller sees)

`GET /api/desk/v1/automations/{id}/runs`

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

Scope `tenant`: everyone with desk access. Scope `space:<id>`: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 `scope`). Newest first; the log keeps the last 50 executions of an automation – what triggered it (`subject` is the ticket's id), the outcome, the failing node with its error, the duration.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | (default `50`; max 50) |
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The executions (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of AutomationRun, required)
  - `automationId` (string (uuid), required): Automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration of the run in milliseconds
  - `id` (string (uuid), required): Id of the run
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): event: started by an event; manual: started by a person on a ticket (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Why the run failed (only on failure)
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "actorKind": "person",
      "automationId": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e01",
      "createdAt": "2026-11-17T12:05:01Z",
      "depth": 1,
      "durationMs": 21,
      "event": "desk.item.created",
      "id": "9e6f7a8b-0c1d-4e2f-9a4b-6c7d8e9f0a01",
      "outcome": "succeeded",
      "startedBy": "elias.gruber@muster-it.example",
      "steps": 1,
      "subject": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c02",
      "triggerKind": "event",
      "version": 1
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/runs?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The automations an agent can start on the ticket (its „Aktionen“) (desk:read)

`GET /api/desk/v1/items/{ref}/actions`

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

The enabled automations of the tenant and of the ticket's space with a manual trigger whose `filter` holds for the ticket (`trigger.data` is the ticket's event payload). Empty for callers below the agent role and for the tombstone of a converted ticket.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Automations (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of object, required)
  - `id` (string (uuid), required)
  - `key` (string, required)
  - `name` (string, required)
  - `scope` (string, required): `tenant` or `space:<space id>`

Example 200 answer:

```json
{
  "items": [
    {
      "id": "8c5d6e7f-9a0b-4c1d-8e3f-5a6b7c8d9e05",
      "key": "vor-ort-einsatz-planen",
      "name": "Vor-Ort-Einsatz planen",
      "scope": "space:9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00"
    }
  ]
}
```

### Example request

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

## Start an automation on the ticket (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/actions/{actionId}`

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

Runs the automation immediately as the automation's actor, in one transaction. Unlike an event's automations its failure is the answer – 404 for one that is not startable on this ticket (disabled, no manual trigger, another scope), 422 `not_applicable` when its filter does not hold, 422 `automation_failed` (`details.reason`, `details.message`, `details.node`) when it fails; then nothing is changed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |
| `actionId` | path | string (uuid) | yes | Id of the automation |

### Responses

- **200** The ticket after the automation (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

```json
{
  "assignees": [
    {
      "role": "owner",
      "userRef": "lukas.wimmer@muster-it.example"
    },
    {
      "role": "assignee",
      "userRef": "sophie.huber@muster-it.example"
    }
  ],
  "categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
  "checklistDone": 1,
  "checklistTotal": 2,
  "childCount": 0,
  "closedAt": null,
  "confidential": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "createdAt": "2026-11-17T07:12:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "customFields": {
    "betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
  "dueAt": "2026-11-17T11:12:00Z",
  "dueHasTime": true,
  "estimateMinutes": null,
  "followUpAt": null,
  "forwarding": false,
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "impact": "mittel",
  "kbWorthy": false,
  "labelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "lastAgentPublicAt": "2026-11-17T08:55:00Z",
  "lastCustomerAt": "2026-11-17T07:12:00Z",
  "number": 1,
  "parentId": null,
  "pendingSuggestions": 0,
  "phase": "active",
  "priority": "hoch",
  "projectId": null,
  "slaDueAt": "2026-11-17T15:12:00Z",
  "slaState": "running",
  "source": "phone",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "spentMinutes": 45,
  "status": "in_bearbeitung",
  "statusChangedAt": "2026-11-17T07:21:00Z",
  "summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
  "summarySource": "auto",
  "teams": [
    {
      "role": "responsible",
      "teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
    }
  ],
  "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-17T08:55:00Z",
  "updatedBy": "lukas.wimmer@muster-it.example",
  "urgency": "hoch",
  "version": 6
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/actions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

