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

# TagGroups

## Introduction

`TagGroups` are used to organize and group [Tags](/api-reference/tags/tags.md) within the system. They allow for hierarchical structuring of [Tags](/api-reference/tags/tags.md), assignment of [Tags](/api-reference/tags/tags.md) to groups, and restriction of [Tag](/api-reference/tags/tags.md) usage in specific [TaggableSections](/api-reference/tags/taggable-sections.md).

A `TagGroup` can have a parent group, child groups, and can be assigned to one or more [TaggableSections](/api-reference/tags/taggable-sections.md).

## Model Definition

**Alias**

`tagGroup`

**Relations**

| Key                          | Relation                                                    | Type            | Relation Field(s)                                                                                |
| ---------------------------- | ----------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `user`                       | [User](/api-reference/users.md)                             | Belongs to      | `user_id`                                                                                        |
| `parent`                     | [TagGroup](/api-reference/tags/tag-groups.md)               | Belongs to      | `parent_id`                                                                                      |
| `children`                   | [TagGroup](/api-reference/tags/tag-groups.md)               | Has many        | `tag_groups.parent_id`                                                                           |
| `tags`                       | [Tag](/api-reference/tags/tags.md)                          | Belongs to many | `tag_tag_group.tag_group_id`                                                                     |
| `taggableSections`           | [TaggableSection](/api-reference/tags/taggable-sections.md) | Has many        | `taggable_sections.default_tag_group_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 `TagGroups` for one taggable section.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tags/groups/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/groups/allowed/infoboard', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 31,
    "user_id": 7,
    "title": "Content type",
    "parent_id": null,
    "sort_number": 1,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  },
  {
    "id": 32,
    "user_id": 19,
    "title": "Priority",
    "parent_id": 31,
    "sort_number": 2,
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:15:00",
    "deleted_at": null
  }
]
```

## Admin: List

List all `TagGroups` in administration scope.

**Definition**

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

**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 groups. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 31,
    "user_id": 7,
    "title": "Content type",
    "parent_id": null,
    "sort_number": 1,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  },
  {
    "id": 32,
    "user_id": 19,
    "title": "Priority",
    "parent_id": 31,
    "sort_number": 2,
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:15:00",
    "deleted_at": null
  }
]
```

## Admin: Show

Show one `TagGroup` in administration scope.

**Definition**

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

**Route Parameters**

| Parameter  | Type      | Description                               |
| ---------- | --------- | ----------------------------------------- |
| `tagGroup` | `integer` | TagGroup ID; deleted groups 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/groups/31', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 31,
  "user_id": 7,
  "title": "Content type",
  "parent_id": null,
  "sort_number": 1,
  "created_at": "2026-08-06 09:00:00",
  "updated_at": "2026-08-06 09:00:00",
  "deleted_at": null
}
```

## Admin: Create

Create a new `TagGroup`.

**Definition**

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

**Request Keys**

| Key           | Type      | Default            | Description                                                              |
| ------------- | --------- | ------------------ | ------------------------------------------------------------------------ |
| `title` \*    | `string`  | -                  | The name of the `TagGroup`.                                              |
| `parent_id`   | `int`     | -                  | The ID of the parent `TagGroup`.                                         |
| `sort_number` | `integer` | Current highest +1 | The index of the `TagGroup` related to the parent `TagGroup`.            |
| `tag_ids`     | `array`   | -                  | Array of [Tag](/api-reference/tags/tags.md) IDs to assign to this group. |

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/groups', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
    'json' => [
        'title' => 'Audience',
        'parent_id' => 31,
        'sort_number' => 3,
        'tag_ids' => [21, 22]
    ],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "user_id": 7,
    "title": "Audience",
    "parent_id": 31,
    "sort_number": 3,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:00:00",
    "deleted_at": null
  }
}
```

## Admin: Update

Update an existing `TagGroup`.

**Definition**

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

**Route Parameters**

| Parameter  | Type      | Description  |
| ---------- | --------- | ------------ |
| `tagGroup` | `integer` | TagGroup ID. |

**Request Keys**

| Key           | Type                | Default             | Description                                                  |
| ------------- | ------------------- | ------------------- | ------------------------------------------------------------ |
| `title`       | `string`            | Current value       | TagGroup title.                                              |
| `parent_id`   | `integer` \| `null` | Current value       | Parent TagGroup ID.                                          |
| `sort_number` | `integer`           | Current value       | Sort order among siblings.                                   |
| `tag_ids`     | `array` \| `null`   | Current assignments | [Tag](/api-reference/tags/tags.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/groups/33', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
    'json' => [
        'sort_number' => 4,
        'tag_ids' => [21, 22, 25]
    ],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "user_id": 7,
    "title": "Audience",
    "parent_id": 31,
    "sort_number": 4,
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:30:00",
    "deleted_at": null
  }
}
```

## Admin: Delete

Delete an existing `TagGroup`.

**Definition**

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

**Route Parameters**

| Parameter  | Type      | Description  |
| ---------- | --------- | ------------ |
| `tagGroup` | `integer` | TagGroup 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/groups/33', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

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