ConnectCloud Developers

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.
    • 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: /help//)
  • 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.") of the project record; sections facts, main, aside
      • key (string, required): System field (priority, dueAt, customer, …) or "cf."
      • 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): "|" → 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."
      • 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:

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

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

View as Markdown · Interactive reference · OpenAPI