> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/calendar/calendars.md).

# Calendars

## Introduction

`Calendars` categorize [CalendarEvents](/api-reference/calendar/calendar-events.md) and provide the color used to display their events.

## Model Definition

**Relations**

| Key      | Relation                                                     | Type     | Relation Field(s)             |
| -------- | ------------------------------------------------------------ | -------- | ----------------------------- |
| `events` | [CalendarEvents](/api-reference/calendar/calendar-events.md) | Has many | `calendar_events.calendar_id` |

## List

List all calendars ordered by `sort_number` by default.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/calendars`

**Request Keys**

| Key               | Type      | Default       | Description                                                              |
| ----------------- | --------- | ------------- | ------------------------------------------------------------------------ |
| `selects`         | `string`  | All fields    | Comma-separated fields to return.                                        |
| `relations`       | `string`  | No relations  | Pipe-separated relations to include. An empty value suppresses defaults. |
| `limit`           | `integer` | No limit      | Maximum number of calendars. Minimum `1`.                                |
| `order_field`     | `string`  | `sort_number` | Field used for ordering.                                                 |
| `order_direction` | `string`  | `asc`         | `asc` or `desc`.                                                         |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/calendars', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'order_field' => 'sort_number',
        'order_direction' => 'asc',
        'limit' => 2
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 1,
    "name": "Company Events",
    "color": "#2196F3",
    "sort_number": 1,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00"
  },
  {
    "id": 2,
    "name": "Absences",
    "color": "#8BC34A",
    "sort_number": 2,
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:05:00"
  }
]
```

## Show

Show one calendar.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/calendars/{idOrHash}`

**Route Parameters**

| Parameter  | Type      | Description  |
| ---------- | --------- | ------------ |
| `idOrHash` | `integer` | Calendar ID. |

**Request Keys**

| Key         | Type     | Default      | Description                          |
| ----------- | -------- | ------------ | ------------------------------------ |
| `selects`   | `string` | All fields   | Comma-separated fields to return.    |
| `relations` | `string` | No relations | Pipe-separated relations to include. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/calendars/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "name": "Company Events",
  "color": "#2196F3",
  "sort_number": 1,
  "created_at": "2026-08-06 09:00:00",
  "updated_at": "2026-08-06 09:00:00"
}
```

## Create

Create a calendar.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/calendars`

**Request Keys**

| Key           | Type      | Default          | Description                                         |
| ------------- | --------- | ---------------- | --------------------------------------------------- |
| `name`\*      | `string`  | -                | Calendar name.                                      |
| `color`\*     | `string`  | -                | Calendar color, normally a hexadecimal color value. |
| `sort_number` | `integer` | Next sort number | Calendar position.                                  |

Keys with `*` are required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/calendars', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Training Sessions',
        'color' => '#FF9800',
        'sort_number' => 3
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "name": "Training Sessions",
    "color": "#FF9800",
    "sort_number": 3,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:00:00"
  }
}
```

## Update

Update a calendar.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/calendars/{id}`

**Route Parameters**

| Parameter | Type      | Description  |
| --------- | --------- | ------------ |
| `id`      | `integer` | Calendar ID. |

**Request Keys**

| Key           | Type      | Description         |
| ------------- | --------- | ------------------- |
| `name`        | `string`  | New calendar name.  |
| `color`       | `string`  | New calendar color. |
| `sort_number` | `integer` | New position.       |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/calendars/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Mandatory Training',
        'color' => '#F57C00'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "name": "Mandatory Training",
    "color": "#F57C00",
    "sort_number": 3,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:15:00"
  }
}
```

## Delete

Delete a calendar permanently.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/calendars/{id}`

**Route Parameters**

| Parameter | Type      | Description  |
| --------- | --------- | ------------ |
| `id`      | `integer` | Calendar ID. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/calendars/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": []
}
```