ConnectCloud Developers

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:

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

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

View as Markdown · Interactive reference · OpenAPI