> 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/tags/tags.md).

# Tags

## Introduction

`Tags` are used to categorize and organize various entities within the system. They help in filtering, searching, and managing content efficiently across modules.

`Tags` can be grouped into [TagGroups](/api-reference/tags/tag-groups.md) and are assignable to different [TaggableSections](/api-reference/tags/taggable-sections.md).

## Model Definition

**Alias**

`tag`

**Relations**

| Key                          | Relation                                                    | Type            | Relation Field(s)                                                                                |
| ---------------------------- | ----------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `user`                       | [User](/api-reference/users.md)                             | Belongs to      | `user_id`                                                                                        |
| `tagGroups`                  | [TagGroup](/api-reference/tags/tag-groups.md)               | Belongs to many | `tag_tag_group.tag_id`                                                                           |
| `restrictedTaggableSections` | [TaggableSection](/api-reference/tags/taggable-sections.md) | Morph to many   | `taggable_section_restrictbale.restrictable_type, taggable_section_restrictbale.restrictable_id` |

## List by Section

List visible `Tags` for one taggable section.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tags/allowed/{taggableSection}`

**Route Parameters**

| Parameter         | Type     | Description                                                              |
| ----------------- | -------- | ------------------------------------------------------------------------ |
| `taggableSection` | `string` | Existing [TaggableSection](/api-reference/tags/taggable-sections.md) ID. |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default 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/tags/allowed/infoboard', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 21,
    "user_id": 7,
    "title": "Announcement",
    "color": "#2563eb",
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  },
  {
    "id": 22,
    "user_id": 19,
    "title": "Action required",
    "color": "#dc2626",
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:15:00",
    "deleted_at": null
  }
]
```

## Admin: List

List all `Tags` in administration scope.

**Definition**

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

**Request Keys**

| Key         | Type      | Default           | Description                                |
| ----------- | --------- | ----------------- | ------------------------------------------ |
| `selects`   | `string`  | All fields        | Comma-separated fields to return.          |
| `relations` | `string`  | Default relations | Pipe-separated relations to include.       |
| `limit`     | `integer` | No limit          | Maximum number of active and deleted tags. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 21,
    "title": "Announcement",
    "color": "#2563eb",
    "user_id": 7,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  },
  {
    "id": 24,
    "title": "Archived campaign",
    "color": "#6b7280",
    "user_id": 19,
    "created_at": "2026-07-01 10:00:00",
    "updated_at": "2026-08-01 12:00:00",
    "deleted_at": "2026-08-01 12:00:00"
  }
]
```

## Admin: Show

Show one `Tag` in administration scope.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tags/{tag}`

**Route Parameters**

| Parameter | Type      | Description                        |
| --------- | --------- | ---------------------------------- |
| `tag`     | `integer` | Tag ID; deleted tags are included. |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default 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/administration/tags/21', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 21,
  "title": "Announcement",
  "color": "#2563eb",
  "user_id": 7,
  "created_at": "2026-08-06 09:00:00",
  "updated_at": "2026-08-06 09:00:00",
  "deleted_at": null
}
```

## Admin: Create

Create a new `Tag`.

**Definition**

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

**Request Keys**

| Key                   | Type      | Default | Description                                                                                       |
| --------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------- |
| `title` \*            | `string`  | –       | The name of the `Tag`.                                                                            |
| `color` \*            | `string`  | –       | The color code (HEX) for the `Tag`.                                                               |
| `tag_group_ids`       | `array`   | –       | Array of [TagGroup](/api-reference/tags/tag-groups.md) IDs to assign the `Tag` to.                |
| `taggable_section_id` | `integer` | –       | The ID of the [TaggableSection](/api-reference/tags/taggable-sections.md) to assign the `Tag` to. |

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/administration/tags', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
    'json' => [
        'title' => 'Urgent',
        'color' => '#ffa500',
        'tag_group_ids' => [31, 32],
        'taggable_section_id' => 'infoboard'
    ],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 25,
    "title": "Urgent",
    "color": "#ffa500",
    "user_id": 7,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:00:00",
    "deleted_at": null
  }
}
```

## Admin: Update

Update an existing `Tag`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/tags/{tag}`

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `tag`     | `integer` | Tag ID.     |

**Request Keys**

| Key             | Type              | Default             | Description                                                             |
| --------------- | ----------------- | ------------------- | ----------------------------------------------------------------------- |
| `title`         | `string`          | Current value       | Tag title.                                                              |
| `color`         | `string`          | Current value       | Tag color.                                                              |
| `tag_group_ids` | `array` \| `null` | Current assignments | [TagGroup](/api-reference/tags/tag-groups.md) IDs; `null` detaches all. |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/tags/25', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
    'json' => [
        'color' => '#ffb700'
    ],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 25,
    "title": "Urgent",
    "color": "#ffb700",
    "user_id": 7,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:30:00",
    "deleted_at": null
  }
}
```

## Admin: Delete

Delete an existing `Tag`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/tags/{tag}`

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `tag`     | `integer` | Tag ID.     |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```