# TagGroups

## Introduction

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

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

## Model Definition

### Alias

`tagGroup`

### Relations

| Key                          | Relation                                                                              | Type            | Relation Field(s)                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `user`                       | [User](https://docs.api.intratool.de/api-reference/users)                             | Belongs to      | `user_id`                                                                                        |
| `parent`                     | [TagGroup](https://docs.api.intratool.de/api-reference/tags/tag-groups)               | Belongs to      | `parent_id`                                                                                      |
| `children`                   | [TagGroup](https://docs.api.intratool.de/api-reference/tags/tag-groups)               | Has many        | `tag_groups.parent_id`                                                                           |
| `tags`                       | [Tag](https://docs.api.intratool.de/api-reference/tags/tags)                          | Belongs to many | `tag_tag_group.tag_group_id`                                                                     |
| `taggableSections`           | [TaggableSection](https://docs.api.intratool.de/api-reference/tags/taggable-sections) | Has many        | `taggable_sections.default_tag_group_id`                                                         |
| `restrictedTaggableSections` | [TaggableSection](https://docs.api.intratool.de/api-reference/tags/taggable-sections) | Morph to many   | `taggable_section_restrictbale.restrictable_type, taggable_section_restrictbale.restrictable_id` |

## List by section

Get a list of all `TagGroups` by [TaggableSection](https://docs.api.intratool.de/api-reference/tags/taggable-sections).

**Definition**

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

**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": 1,
    "user_id": 2,
    "title": "General",
    "parent_id": null,
    "sort_number": 1,
    "created_at": "2019-06-15 12:00:00",
    "updated_at": "2019-06-15 12:00:00",
    "deleted_at": null
  },
  {
    "id": 2,
    "user_id": 2,
    "title": "Important",
    "parent_id": 1,
    "sort_number": 2,
    "created_at": "2019-06-15 13:00:00",
    "updated_at": "2019-06-15 13:00:00",
    "deleted_at": null
  }
]
```

## \[Adm.] List

Get a list of all `TagGroups`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tags/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": 1,
    "user_id": 2,
    "title": "General",
    "parent_id": null,
    "sort_number": 1,
    "created_at": "2019-06-15 12:00:00",
    "updated_at": "2019-06-15 12:00:00",
    "deleted_at": null
  },
  {
    "id": 2,
    "user_id": 2,
    "title": "Important",
    "parent_id": null,
    "sort_number": 2,
    "created_at": "2019-06-15 13:00:00",
    "updated_at": "2019-06-15 13:00:00",
    "deleted_at": null
  }
]
```

## \[Adm.] Show

Show a single `TagGroup` by `id`.

**Definition**

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

**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/1', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "user_id": 2,
  "title": "General",
  "parent_id": null,
  "sort_number": 1,
  "created_at": "2019-06-15 12:00:00",
  "updated_at": "2019-06-15 12:00:00",
  "deleted_at": null
}
```

## 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](https://docs.api.intratool.de/api-reference/tags/tags) 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' => 'Common',
        'tag_ids' => [5, 6]
    ],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 2,
    "title": "Common",
    "parent_id": null,
    "sort_number": 3,
    "created_at": "2019-06-15 14:00:00",
    "updated_at": "2019-06-15 14:00:00",
    "deleted_at": null
  }
}
```

## Update

Update an existing `TagGroup` by `id`.

**Definition**

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

**Request Keys**

| Key           | Type   | Description                                                                                        |
| ------------- | ------ | -------------------------------------------------------------------------------------------------- |
| `title`       | string | The name of the `TagGroup`.                                                                        |
| `parent_id`   | int    | The ID of the parent `TagGroup`.                                                                   |
| `sort_number` | int    | The index of the `TagGroup` related to the parent `TagGroup`.                                      |
| `tag_ids`     | array  | Array of [Tag](https://docs.api.intratool.de/api-reference/tags/tags) IDs to assign to this group. |

**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/3', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
    'json' => [
        'tag_ids' => [5, 6, 7]
    ],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 2,
    "title": "Common",
    "parent_id": null,
    "sort_number": 3,
    "created_at": "2019-06-15 14:00:00",
    "updated_at": "2019-06-15 14:30:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `TagGroup` by `id`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/tags/groups/{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/3', [
    'headers' => ['Authorization' => 'Bearer {accessToken}'],
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

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