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 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)in(string, required): Offset from receipt like rule durations:90m,4h,2d; 1 minute to 365 daysbusinessHours(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 daysbusinessHours(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 daysbusinessHours(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 daysbusinessHours(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 daysbusinessHours(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 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)note(string): Why the configuration changes (trimmed, at most 500 characters, line breaks allowed; empty = no note) (max length 500)
Example:
{
"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 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)in(string, required): Offset from receipt like rule durations:90m,4h,2d; 1 minute to 365 daysbusinessHours(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 daysbusinessHours(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 daysbusinessHours(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 daysbusinessHours(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 daysbusinessHours(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 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)
Example 201 answer:
{
"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
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"}'