## 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:

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

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

```bash
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"}'
```
