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

# FilemanagerDirectories

## Introduction

`FilemanagerDirectories` form a persisted directory hierarchy. Each directory stores its `parent_id`, `name`, and normalized absolute `path`; access assignments on parent directories affect visibility throughout the path.

## Model Definition

**Alias**

`filemanagerDirectory`

**Relations**

| Key                | Relation                                                                        | Type            | Relation Field(s)                  |
| ------------------ | ------------------------------------------------------------------------------- | --------------- | ---------------------------------- |
| `user`             | [User](/api-reference/users.md)                                                 | Belongs to      | `user_id`                          |
| `parent`           | [FilemanagerDirectory](/api-reference/filemanager/filemanager-directories.md)   | Belongs to      | `parent_id`                        |
| `children`         | [FilemanagerDirectories](/api-reference/filemanager/filemanager-directories.md) | Has many        | `parent_id`                        |
| `filemanagerFiles` | [FilemanagerFiles](/api-reference/filemanager/filemanager-files.md)             | Has many        | `filemanager_directory_id`         |
| `users`            | [Users](/api-reference/users.md)                                                | Belongs to many | `user_filemanager_directory`       |
| `departments`      | [Departments](/api-reference/departments.md)                                    | Belongs to many | `department_filemanager_directory` |

**Computed Properties**

* `hash` - Hashed representation of the directory `id`.
* `url` and `static_url` - Link to the directory page.

**Capabilities**

* [Targetables](/introduction/resource-capabilities/targetables.md) - `user_ids` or `department_ids` restrict directory access; an empty assignment is public to users with Filemanager access, while visibility through a nested path also depends on its ancestors.
* [URL Context](/introduction/resource-capabilities/url-context.md) - Directory URLs resolve to access-checked context containing the directory name, parent path, and last update time.

## List

List all directories visible to the authenticated user.

**Definition**

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

**Request Keys**

| Key       | Type     | Default     | Description                                                                                                           |
| --------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `filter`  | `object` | `{}`        | [Result Control](/introduction/query-manipulation/result-control.md) filters, including the Filemanager path filters. |
| `sort`    | `string` | API default | Result Control sort expression.                                                                                       |
| `include` | `string` | API default | Relations to include.                                                                                                 |
| `appends` | `string` | API default | Computed properties to append.                                                                                        |

**Behavior**

* Recursive path filtering can be more expensive than the direct [List by Path](#list-by-path) endpoint.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/filemanager/directories', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'filter' => ['path' => ['matches_path' => '/Projects/']],
        'sort' => 'name'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 11,
    "user_id": 3,
    "parent_id": 10,
    "path": "/Projects/Reports/",
    "name": "Reports",
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 12,
    "user_id": 4,
    "parent_id": 10,
    "path": "/Projects/Media/",
    "name": "Media",
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:05:00",
    "deleted_at": null,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]
```

## List by Path

List direct child directories of a normalized path. Omitting `path` lists the root.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/directories/path/{path?}`

**Route Parameters**

| Parameter | Type     | Description                                                                             |
| --------- | -------- | --------------------------------------------------------------------------------------- |
| `path`    | `string` | Optional. Directory path without a required leading or trailing slash. Defaults to `/`. |

**Request Keys**

| Key      | Type     | Default     | Description                                                     |
| -------- | -------- | ----------- | --------------------------------------------------------------- |
| `filter` | `object` | `{}`        | Optional Result Control filters applied to the direct children. |
| `sort`   | `string` | API default | Result Control sort expression.                                 |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 12,
    "user_id": 4,
    "parent_id": 10,
    "path": "/Projects/Media/",
    "name": "Media",
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  },
  {
    "id": 11,
    "user_id": 3,
    "parent_id": 10,
    "path": "/Projects/Reports/",
    "name": "Reports",
    "hash": "zn7m24owk63qolxryge8pj05"
  }
]
```

## Count

Count directories visible to the authenticated user after Result Control filters are applied.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/directories/count`

**Request Keys**

| Key      | Type     | Default | Description                                     |
| -------- | -------- | ------- | ----------------------------------------------- |
| `filter` | `object` | `{}`    | Result Control filters applied before counting. |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/filemanager/directories/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => ['filter' => ['path' => ['matches_path_recursive' => '/Projects/']]]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
3
```

## List by Directory

List direct child directories of one visible directory.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/directories/{filemanagerDirectory}/directories`

**Route Parameters**

| Parameter              | Type                  | Description                  |
| ---------------------- | --------------------- | ---------------------------- |
| `filemanagerDirectory` | `integer` \| `string` | Parent directory ID or hash. |

**Request Keys**

| Key      | Type     | Default     | Description                                                     |
| -------- | -------- | ----------- | --------------------------------------------------------------- |
| `filter` | `object` | `{}`        | Optional Result Control filters applied to the direct children. |
| `sort`   | `string` | API default | Result Control sort expression.                                 |

**Behavior**

* The parent directory must be visible to the authenticated user. The response contains only its direct visible children.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 12,
    "user_id": 4,
    "parent_id": 10,
    "path": "/Projects/Media/",
    "name": "Media",
    "created_at": "2026-08-06 09:10:00",
    "updated_at": "2026-08-06 09:10:00",
    "deleted_at": null,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  },
  {
    "id": 11,
    "user_id": 3,
    "parent_id": 10,
    "path": "/Projects/Reports/",
    "name": "Reports",
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null,
    "hash": "zn7m24owk63qolxryge8pj05"
  }
]
```

## Show

Show one visible directory.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/directories/{filemanagerDirectory}`

**Route Parameters**

| Parameter              | Type                  | Description           |
| ---------------------- | --------------------- | --------------------- |
| `filemanagerDirectory` | `integer` \| `string` | Directory ID or hash. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 11,
  "user_id": 3,
  "parent_id": 10,
  "path": "/Projects/Reports/",
  "name": "Reports",
  "created_at": "2026-08-06 09:00:00",
  "updated_at": "2026-08-06 09:00:00",
  "deleted_at": null,
  "hash": "zn7m24owk63qolxryge8pj05"
}
```

## Show Information

Return the number and total byte size of all visible files in a directory and its descendants.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/directories/{filemanagerDirectory}/information`

**Route Parameters**

| Parameter              | Type                  | Description           |
| ---------------------- | --------------------- | --------------------- |
| `filemanagerDirectory` | `integer` \| `string` | Directory ID or hash. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "files": 8,
  "size": 2748430
}
```

## Create

Create a physical directory and its metadata record.

**Definition**

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

**Request Keys**

| Key              | Type                    | Default             | Description                                                                                             |
| ---------------- | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------- |
| `path`\*         | `string`                | -                   | Directory path. The backend normalizes leading and trailing slashes and derives `parent_id` and `name`. |
| `parent_id`      | `integer` \| `null`     | Derived from `path` | Parent directory. When supplied, `name` is used to build `path`.                                        |
| `name`           | `string`                | Derived from `path` | Directory name when `parent_id` is supplied.                                                            |
| `user_ids`       | `integer[]` \| `string` | `[]`                | Users allowed to access the directory.                                                                  |
| `department_ids` | `integer[]` \| `string` | `[]`                | Departments allowed to access the directory.                                                            |

Keys with `*` are required unless `parent_id` and `name` provide the hierarchy.

**Behavior**

* `user_id` is set to the authenticated user.
* When `parent_id` is present, `parent_id` and `name` determine the hierarchy and take precedence over a conflicting `path`. A `null` parent creates a root directory.
* When both assignment arrays are non-empty, user assignments take precedence and department assignments are cleared. When both are empty, the directory is public to users with Filemanager access.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/filemanager/directories', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'parent_id' => 10,
        'name' => 'Archive',
        'user_ids' => [3, 8]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 13,
    "user_id": 3,
    "parent_id": 10,
    "path": "/Projects/Archive/",
    "name": "Archive",
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:00:00",
    "deleted_at": null,
    "hash": "8q0o2mbzay32zzsrt1g6xzl4"
  }
}
```

## Update

Rename or move a directory and optionally replace its assignments.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/filemanager/directories/{filemanagerDirectory}`

**Route Parameters**

| Parameter              | Type                  | Description           |
| ---------------------- | --------------------- | --------------------- |
| `filemanagerDirectory` | `integer` \| `string` | Directory ID or hash. |

**Request Keys**

| Key              | Type                              | Description                         |
| ---------------- | --------------------------------- | ----------------------------------- |
| `path`           | `string`                          | New normalized directory path.      |
| `parent_id`      | `integer` \| `null`               | New parent directory.               |
| `name`           | `string`                          | New directory name.                 |
| `user_ids`       | `integer[]` \| `string` \| `null` | Replacement user assignments.       |
| `department_ids` | `integer[]` \| `string` \| `null` | Replacement department assignments. |

**Behavior**

* `user_id` remains the authenticated user. Reserved directory paths cannot be moved or renamed.
* When `parent_id` or `name` is present, those hierarchy fields take precedence over a conflicting `path`; omitted hierarchy fields retain their current values. A `null` parent moves the directory to the root.
* A path change moves the directory, its descendants, and stored files. Assignment relations are synchronized only for keys present in the request.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/filemanager/directories/13', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Archived Reports',
        'department_ids' => [2, 4]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 13,
    "user_id": 3,
    "parent_id": 10,
    "path": "/Projects/Archived Reports/",
    "name": "Archived Reports",
    "created_at": "2026-08-06 10:00:00",
    "updated_at": "2026-08-06 10:15:00",
    "deleted_at": null,
    "hash": "8q0o2mbzay32zzsrt1g6xzl4"
  }
}
```

## Delete

Delete a directory, its storage content, and its descendant directory and file records.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/filemanager/directories/{filemanagerDirectory}`

**Route Parameters**

| Parameter              | Type                  | Description           |
| ---------------------- | --------------------- | --------------------- |
| `filemanagerDirectory` | `integer` \| `string` | Directory ID or hash. |

**Behavior**

* The root directory cannot be deleted.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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