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 calendarskey(string, required): Key of the calendar, unique in the tenantname(string, required): Name of the calendararchived(boolean): Archived: the calendar is kept for existing data but no longer offered in pickersdescription(string): Description of the calendarexceptions(array of object): Days that differ from the week (holidays, special hours)closed(boolean): Closed all daydate(string (date)): Dayhours(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 codeid(string, read-only): Id of the calendarisDefault(boolean): Calendar of policies that name noneonCall(object): On-call windows by weekday keytimeZone(string): IANA zone, default Europe/Berlinversion(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): Categoriesname(string, required): Name of the categoryarchived(boolean): Archived: the category is kept for existing data but no longer offered in pickersid(string): Id of the categoryparentId(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 definitionskey(string, required): Key of the field; item values are cf.kind(string, required): Value kind of the field (one oftext,longtext,number,date,datetime,bool,select,multiselect,user,url)label(string, required): Display labelaiFill(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 personarchived(boolean): Archived: kept on items, no longer offereddescription(string): Help text of the fieldid(string, read-only): Id of the custom fieldkbRole(string): Field holds the cause (one of ``,cause,solution,workaround)options(array of object): Choices of a select or multiselect fieldcolor(string): Display color of the choicelabel(string): Display label of the choicevalue(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_unavailablelabels(array of Label): Labelsname(string, required): Name of the labelarchived(boolean): Archived: the label is kept for existing data but no longer offered in pickerscolor(string): Display color of the labeldescription(string): Description of the labelid(string): Id of the labelspaceId(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): Prioritieskey(string, required): Key of the priority, unique in the tenantlabel(string, required): Display label of the priorityarchived(boolean): Archived: the priority is kept for existing data but no longer offered in pickerscolor(string): Display color of the priorityid(string): Id of the priorityisDefault(boolean): Priority of new items without onerank(integer): Sort order of the priorities (ascending)
projectTemplates(array of ProjectTemplate): Project templateskey(string, required): Key of the template, unique in the tenantname(string, required): Name of the template (max length 200)typeId(string, required): Project type (id or key on input); fixedarchived(boolean): Archived: the template is kept for existing data but no longer offered in pickersblueprint(object): What a project made from the template getsdependencies(array of object): Finish-to-start between tasks (keys); no cyclesfrom(string, required): Key of the task that has to end firstto(string, required): Key of the task that starts after itlagDays(integer): Days between the end of from and the start of to (max 365)
fields(object): Custom field values of new projectsmilestones(array of object): Milestones of the new projectkey(string, required): Key of the milestone in the templatetitle(string, required): Title of the milestonecompletion(string): manual: achieved by hand; items: reached once all its items are done (one ofmanual,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 ofinterim,final)title(string, required): Title of the paymentamountKind(string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one offixed,percent)milestoneKey(string): A milestone of the template that makes it duetaxRate(number): VAT rate in percent
tasks(array of BlueprintTask): Tasks: items of the new project
description(string): Description of the templateid(string, read-only): Id of the templateversion(integer): Version of the template; send it back on change (409 version_conflict when it is outdated)
projectTypes(array of ProjectType): Project typeskey(string, required): Lower-case letters, digits, - or _; fixedname(string, required): Name of the project type (max length 200)workflowId(string, required): A workflow of scope projectarchived(boolean): Archived: the project type is kept for existing data but no longer offered in pickerscolor(string): Display color of the project typedescription(string): Description of the project typeicon(string): Icon of the project typeid(string, read-only): Id of the project typelayout(array of LayoutField): Custom fields ("cf.") of the project record; sections facts, main, asidekey(string, required): System field (priority, dueAt, customer, …) or "cf."required(boolean): The field must be filledsection(string): Section of the record page the field is shown in (one offacts,main,aside,closure)
settings(object): Settings of the project typebilling(object): Project billingautoDraft(boolean): Request a payment (hand its draft to trade) as soon as it is due; default offhourUnit(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 changesettings(Settings)ai(object): AI features of the desk (triage, subject, summary, draftReply). Triage withautoApplyapplies each proposed value that reachesthresholdand 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); withautoApplyit 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.mailTextsandstatusMail: absent = the defaults (a manual mail text for the statusnot_reached, while that status exists),[]= none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the modeauto.fields(array of object): Custom fields of the callback form in orderkey(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 _; uniquename(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 (422note_rejectedwith a hint); an unavailable AI accepts the noteminLength(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 ofmanual,auto)status(string, required): Key of a callbackStatus entry, oncetext(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 aiThresholdaiThreshold(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 scriptsbulkPolicy(string): Newsletters and bulk mail: drop (default) or make a ticket (one ofdrop,ticket)foreignSubjectMatch(boolean): A [#N] subject token appends mail of senders who are no participantfromName(string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one ofagentWithMailbox,agent,mailbox)maxAttachmentBytes(integer): Per file, default 20 MB, max. 40 MBmaxTotalBytes(integer): Per mail, default 35 MB, max. 40 MBperSender10min(integer): Above: appended quietly (default 10)perSenderHour(integer): Above: held in the mail log (default 30)
priorityMatrix(object): Priority from impact and urgencycells(object): "|" → priority keyimpacts(array of object): Impact levelskey(string): Key of the levellabel(string): Label of the level
urgencies(array of object): Urgency levelskey(string): Key of the levellabel(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 farappliedAt(string (date-time)): When it was appliedappliedBy(string): Login (e-mail) of who applied itid(string): Id of the applicationname(string): Name of the applied templateprefix(string): Key prefix used for keys that already existedtemplate(string): Key of the applied template
needed(boolean): The tenant has not applied a configuration template yet
spaces(array of Space): Spaces the caller seeskey(string, required): 2–10 upper-case letters or digitsname(string, required): Name of the spacearchived(boolean): Archived: the space is kept for existing data but no longer offered in pickerscolor(string): Display color of the spacedefaultTypeId(string): Type of new items without onedescription(string): Description of the spaceicon(string): Icon of the spaceid(string, read-only): Id of the spacemembers(array of object): Members and their space rolesrole(string): Space role (one ofviewer,reporter,agent,maintainer)userRef(string): Login (e-mail) of the member
settings(object): Space settings;mail(reply mailbox, reopen policies) andhandoff(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 (400invalid; leaving only work types in a space that mail or a portal form still delivers into is refused with fieldtypeIds). Code settings are forge's (a sentscmis dropped).dueOnReceipt(object): Due date on receipt: a new ticket of this space withoutdueAtgets one after the offset of its channel (dueHasTimetrue); work-focus types never. The channel comes from the ticket'ssource:email→ mail;portal,form,platform→ portal;phone,nfon→ phone;api→ api;manual, none,teamviewer,teams→ manual; other sources (automation, handoff, …) get none. API clients sendsource: api, otherwise their tickets count as manual.businessHourscounts 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;nullremoves the setting. Invalid values are 400 with fieldsettings.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 tostatus/ the first status ofstage(new, active, waiting) unless it is in that phase already. Moves ignore transitions and required fields. Invalid values are 400 with fieldsettings.handoff….originOnReturn(object): What happens to a ticket of this space when its handoff comes backaction(string): none (default) or move it to a status (one ofnone,status)stage(string): Stage whose first status it moves to (status) (one ofnew,active,waiting)status(string): Status it moves to (status)
receiverOnReturn(object): What happens to a ticket of this space that is handed backaction(string): close (default) or keep it open (one ofclose,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 fieldtypeId; a project that keeps its type and space is not asked again. An unknown project type is 400 with fieldsettings.projectTypeIds. Bundles do not carry it.
typeIds(array of string): Allowed types; empty = allversion(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 oftenant,members)
teams(array of Team): Teamskey(string, required): Key of the team, unique in the tenantname(string, required): Name of the teamarchived(boolean): Archived: the team is kept for existing data but no longer offered in pickersdescription(string): Description of the teamid(string): Id of the teammembers(array of object): Members of the teamrole(string): member or lead (one ofmember,lead)userRef(string): Login (e-mail) of the member
types(array of ItemType): Item typeskey(string, required): Key of the type, unique in the tenantname(string, required): Name of the item typeworkflowId(string, required): Workflow of the typearchived(boolean): Archived: the item type is kept for existing data but no longer offered in pickerscloseRequired(array of string): Fields that must be filled before the item can be closedcolor(string): Display color of the item typeconfidential(boolean): Items of the type are confidentialdescription(string): Description of the item typefocus(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 typeid(string, read-only): Id of the item typelayout(array of LayoutField): Custom fields of the record and their sectionskey(string, required): System field (priority, dueAt, customer, …) or "cf."required(boolean): The field must be filledsection(string): Section of the record page the field is shown in (one offacts,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): Workflowskey(string, required): Key of the workflow, unique in the tenantname(string, required): Name of the workflowstatuses(array of Status, required): Statuses of the workflowkey(string, required): Key of the status, unique in the workflowlabel(string, required): Display labelphase(Phase, required)closed(boolean): The item counts as closed in this statuscolor(string): Display colordescription(string): Description of the statuspausesSla(boolean): SLA clocks pause in this status
archived(boolean): Archived: the workflow is kept for existing data but no longer offered in pickersdescription(string): Description of the workflowid(string, read-only): Id of the workflowscope(string): Serves item types (item, default) or project types (project); fixed after creation (one ofitem,project)transitions(array of Transition): Empty = free workflowfrom(array of string, required): Source statuses; "*" = anyid(string, required): Id of the transitionto(string, required): Target statusallowedRoles(array of string): Space roles allowed (at least one of them); empty: agent and abovelabel(string): Label of the actionrequireComment(boolean): A comment is requiredrequiredFields(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"