## Create a service calendar (desk:admin)

`POST /api/desk/v1/calendars`

Module: Desk · operationId: `createCalendar` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `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)
    - `from` (string): Start time (HH:MM)
    - `to` (string): End time (HH:MM)
  - `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)

Example:

```json
{
  "description": "Erweiterte Zeiten mit Rufbereitschaft am Wochenende",
  "key": "bereitschaft",
  "name": "Bereitschaft",
  "onCall": {
    "sat": [
      {
        "from": "09:00",
        "to": "13:00"
      }
    ]
  },
  "timeZone": "Europe/Berlin",
  "weekly": {
    "fri": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "mon": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "thu": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "tue": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ],
    "wed": [
      {
        "from": "07:00",
        "to": "19:00"
      }
    ]
  }
}
```

### Responses

- **201** Created (`application/json`)

Fields of the 201 answer:

- `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)
    - `from` (string): Start time (HH:MM)
    - `to` (string): End time (HH:MM)
  - `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)

Example 201 answer:

```json
{
  "archived": false,
  "description": "Montag bis Freitag, 8 bis 17 Uhr",
  "exceptions": [
    {
      "closed": true,
      "date": "2026-12-24",
      "hours": [],
      "note": "Heiligabend"
    },
    {
      "closed": false,
      "date": "2026-12-31",
      "hours": [
        {
          "from": "08:00",
          "to": "12:00"
        }
      ],
      "note": "Silvester nur vormittags"
    }
  ],
  "holidayRegion": "",
  "id": "2e9f0a1b-3c4d-4e5f-8a7b-9c0d1e2f3a01",
  "isDefault": true,
  "key": "geschaeftszeiten",
  "name": "Geschäftszeiten",
  "onCall": {},
  "timeZone": "Europe/Berlin",
  "version": 2,
  "weekly": {
    "fri": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "mon": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "thu": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "tue": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ],
    "wed": [
      {
        "from": "08:00",
        "to": "17:00"
      }
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/calendars' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Erweiterte Zeiten mit Rufbereitschaft am Wochenende","key":"bereitschaft","name":"Bereitschaft","onCall":{"sat":[{"from":"09:00","to":"13:00"}]},"timeZone":"Europe/Berlin","weekly":{"fri":[{"from":"07:00","to":"19:00"}],"mon":[{"from":"07:00","to":"19:00"}],"thu":[{"from":"07:00","to":"19:00"}],"tue":[{"from":"07:00","to":"19:00"}],"wed":[{"from":"07:00","to":"19:00"}]}}'
```
