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

# Folders

## Introduction

`Folders` organize supported resources into a hierarchy. A folder type determines which resource it can contain and which module permission controls access.

## Model Definition

**Types**

* `department` - Organizes [Departments](/api-reference/departments.md).
* `form` - Organizes [Forms](/api-reference/forms/forms.md).
* `infoboardChannel` - Organizes [InfoboardChannels](/api-reference/infoboard/infoboard-channels.md).
* `report` - Organizes reports.
* `reportDefinition` - Organizes report definitions.
* `role` - Organizes [Roles](/api-reference/roles.md).
* `survey` - Organizes [Surveys](/api-reference/surveys/surveys.md).
* `taskAssignment` - Organizes [TaskAssignments](/api-reference/tasks-2/task-assignments.md).
* `taskTemplate` - Organizes [TaskTemplates](/api-reference/tasks-2/task-templates.md).

**Capabilities**

* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Folders own direct grants; the Restricted Scope controls which folders are returned or accessible for the relevant module operation.
* [Translations](/introduction/resource-capabilities/translations.md) - Localizes `name`; examples use `en-US`.

## List

List folders visible to the authenticated user.

**Definition**

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

**Request Keys**

| Key      | Type      | Default          | Description                                     |
| -------- | --------- | ---------------- | ----------------------------------------------- |
| `limit`  | `integer` | No limit         | Maximum number of folders.                      |
| `filter` | `object`  | No filters       | Value filters applied before permission checks. |
| `sort`   | `string`  | Repository order | Sort expression.                                |

**Behavior**

The response excludes folders for which the current user lacks the folder type's view permission or effective Entity Permission.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 41,
    "user_id": 7,
    "parent_id": null,
    "lang_id": "en-US",
    "icon_id": 210,
    "type": "report",
    "name": "Management Reports",
    "show_on_menu": true,
    "sort_number": 1,
    "created_at": "2026-07-01 09:00:00",
    "updated_at": "2026-07-01 09:00:00",
    "deleted_at": null
  },
  {
    "id": 42,
    "user_id": 19,
    "parent_id": 40,
    "lang_id": "en-US",
    "icon_id": 211,
    "type": "form",
    "name": "Onboarding Forms",
    "show_on_menu": false,
    "sort_number": 3,
    "created_at": "2026-07-02 10:30:00",
    "updated_at": "2026-07-03 08:15:00",
    "deleted_at": null
  }
]
```

## Show

Show one visible folder.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `folder`  | `integer` | Folder ID.  |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 41,
  "user_id": 7,
  "parent_id": null,
  "lang_id": "en-US",
  "icon_id": 210,
  "type": "report",
  "name": "Management Reports",
  "show_on_menu": true,
  "sort_number": 1,
  "created_at": "2026-07-01 09:00:00",
  "updated_at": "2026-07-01 09:00:00",
  "deleted_at": null
}
```

## Create

Create a folder.

**Definition**

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

**Request Keys**

| Key                  | Type                | Default             | Description                                                                          |
| -------------------- | ------------------- | ------------------- | ------------------------------------------------------------------------------------ |
| `parent_id`          | `integer` \| `null` | `null`              | Parent folder ID.                                                                    |
| `lang_id`            | `string`            | System language     | Language key for `name`.                                                             |
| `icon_id`            | `integer`           | Default folder icon | Existing [Icon](/api-reference/icons.md) ID.                                         |
| `type`\*             | `string`            | -                   | Selects one of the supported [Types](#types).                                        |
| `name`\*             | `string`            | -                   | Folder name.                                                                         |
| `show_on_menu`       | `boolean`           | `false`             | Show this folder in module navigation.                                               |
| `entity_permissions` | `object[]`          | No direct grants    | Complete direct [Entity Permission](/api-reference/entity-permissions.md) grant set. |

Keys with `*` are required.

**Behavior**

The authenticated user is stored as `user_id`. Submitted Entity Permissions are attached to the new folder after creation.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/folders', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'parent_id' => null,
        'lang_id' => 'en-US',
        'icon_id' => 210,
        'type' => 'report',
        'name' => 'Management Reports',
        'show_on_menu' => true,
        'entity_permissions' => [
            [
                'key' => 'view',
                'permission_entity' => 'department',
                'permission_entity_id' => 6
            ]
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 41,
    "user_id": 7,
    "parent_id": null,
    "lang_id": "en-US",
    "icon_id": 210,
    "type": "report",
    "name": "Management Reports",
    "show_on_menu": true,
    "sort_number": 1,
    "created_at": "2026-08-06 13:00:00",
    "updated_at": "2026-08-06 13:00:00",
    "deleted_at": null
  }
}
```

## Update

Update a folder.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `folder`  | `integer` | Folder ID.  |

**Request Keys**

| Key                  | Type                | Description                                   |
| -------------------- | ------------------- | --------------------------------------------- |
| `parent_id`          | `integer` \| `null` | Updated parent folder ID.                     |
| `lang_id`            | `string`            | Updated language key.                         |
| `icon_id`            | `integer`           | Updated icon ID.                              |
| `type`               | `string`            | Selects one of the supported [Types](#types). |
| `name`               | `string`            | Updated folder name.                          |
| `show_on_menu`       | `boolean`           | Updated menu visibility.                      |
| `entity_permissions` | `object[]`          | Complete replacement set of direct grants.    |

**Behavior**

When `entity_permissions` is submitted, the folder's direct grants are synchronized to that complete array. The authenticated user becomes the stored `user_id` for the update.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/folders/41', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'parent_id' => 40,
        'lang_id' => 'en-US',
        'icon_id' => 212,
        'type' => 'report',
        'name' => 'Executive Reports',
        'show_on_menu' => false,
        'entity_permissions' => [
            [
                'key' => 'view',
                'permission_entity' => 'role',
                'permission_entity_id' => 12
            ]
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 41,
    "user_id": 7,
    "parent_id": 40,
    "lang_id": "en-US",
    "icon_id": 212,
    "type": "report",
    "name": "Executive Reports",
    "show_on_menu": false,
    "sort_number": 1,
    "created_at": "2026-08-06 13:00:00",
    "updated_at": "2026-08-06 13:15:00",
    "deleted_at": null
  }
}
```

## Delete

Delete a folder.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `folder`  | `integer` | Folder ID.  |

**Behavior**

Deletion also deletes child folders recursively and detaches contained resources by setting their folder reference to `null`.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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