> 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/tasks-2/task-template-compositions.md).

# TaskTemplateCompositions

## Introduction

`TaskTemplateCompositions` combine multiple [TaskTemplates](/api-reference/tasks-2/task-templates.md). A [TaskAssignment](/api-reference/tasks-2/task-assignments.md) can use a composition to create one execution for each included template.

The `description` field uses the shared [Rich Text](/introduction/rich-text.md) HTML format.

## Model Definition

**Alias**

`taskTemplateComposition`

**Capabilities**

* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Direct grants can allow permitted users to view, update, or delete a composition in administration.
* [Translations](/introduction/resource-capabilities/translations.md) - The `title` and `description` fields are translatable.

## Admin: List

List all accessible compositions, including soft-deleted records.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/templates/compositions`

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 12,
    "user_id": 3,
    "lang_id": "en-US",
    "folder_id": null,
    "title": "Opening Checklist",
    "description": "<p>Complete both opening tasks.</p>",
    "sort_number": 1,
    "deleted_at": null
  },
  {
    "id": 13,
    "user_id": 4,
    "lang_id": "en-US",
    "folder_id": 8,
    "title": "Closing Checklist",
    "description": "<p>Finish the closing and security tasks.</p>",
    "sort_number": 2,
    "deleted_at": null
  }
]
```

## Admin: Show

Show one composition, including a soft-deleted record.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/templates/compositions/{taskTemplateComposition}`

**Route Parameters**

| Parameter                 | Type      | Description     |
| ------------------------- | --------- | --------------- |
| `taskTemplateComposition` | `integer` | Composition ID. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 12,
  "user_id": 3,
  "lang_id": "en-US",
  "folder_id": null,
  "title": "Opening Checklist",
  "description": "<p>Complete both opening tasks.</p>",
  "sort_number": 1,
  "deleted_at": null
}
```

## Admin: Create

Create a composition and optionally attach templates.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/templates/compositions`

**Request Keys**

| Key                  | Type                | Default         | Description                                                                             |
| -------------------- | ------------------- | --------------- | --------------------------------------------------------------------------------------- |
| `lang_id`            | `string`            | System language | Language key. Use `en-US` for this example.                                             |
| `folder_id`          | `integer` \| `null` | `null`          | Related [Folder](/api-reference/folders.md) ID.                                         |
| `title`\*            | `string`            | -               | Composition title.                                                                      |
| `description`        | `string` \| `null`  | `null`          | HTML description.                                                                       |
| `sort_number`        | `integer`           | Auto            | Position within the folder.                                                             |
| `task_template_ids`  | `integer[]`         | `[]`            | Templates to attach.                                                                    |
| `entity_permissions` | `object[]`          | `[]`            | Direct [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md). |

Keys with `*` are required.

**Behavior**

* `user_id` is set to the authenticated user; a request-body value cannot select another owner.
* Supplying `task_template_ids` synchronizes the composition's template relations.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/tasks-2/templates/compositions', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'lang_id' => 'en-US',
        'title' => 'Opening Checklist',
        'description' => '<p>Complete both opening tasks.</p>',
        'sort_number' => 1,
        'task_template_ids' => [21, 22]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 12,
    "user_id": 3,
    "lang_id": "en-US",
    "folder_id": null,
    "title": "Opening Checklist",
    "description": "<p>Complete both opening tasks.</p>",
    "sort_number": 1
  }
}
```

## Admin: Update

Update a composition and optionally replace its attached templates.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/tasks-2/templates/compositions/{taskTemplateComposition}`

**Route Parameters**

| Parameter                 | Type      | Description     |
| ------------------------- | --------- | --------------- |
| `taskTemplateComposition` | `integer` | Composition ID. |

**Request Keys**

| Key                  | Type                | Description                                                      |
| -------------------- | ------------------- | ---------------------------------------------------------------- |
| `lang_id`            | `string`            | Language key.                                                    |
| `folder_id`          | `integer` \| `null` | Related folder ID, or `null`.                                    |
| `title`              | `string`            | Composition title.                                               |
| `description`        | `string` \| `null`  | HTML description.                                                |
| `sort_number`        | `integer`           | Position within the folder.                                      |
| `task_template_ids`  | `integer[]`         | Complete replacement set; an empty array detaches all templates. |
| `entity_permissions` | `object[]`          | Direct Entity Permissions.                                       |

**Behavior**

* `user_id` is replaced with the authenticated user.
* `task_template_ids` is synchronized only when the key is present.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/tasks-2/templates/compositions/12', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Opening and Safety Checklist',
        'task_template_ids' => [21, 22, 23]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 12,
    "user_id": 3,
    "lang_id": "en-US",
    "folder_id": null,
    "title": "Opening and Safety Checklist",
    "description": "<p>Complete both opening tasks.</p>",
    "sort_number": 1
  }
}
```

## Admin: Delete

Soft-delete a composition.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/tasks-2/templates/compositions/{taskTemplateComposition}`

**Route Parameters**

| Parameter                 | Type      | Description     |
| ------------------------- | --------- | --------------- |
| `taskTemplateComposition` | `integer` | Composition ID. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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