## 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"
```
