> 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-files.md).

# FilemanagerFiles

## Introduction

`FilemanagerFiles` store metadata for files in Filemanager storage. Each file stores its nullable `filemanager_directory_id`, `name`, and normalized `path`; nested files belong to their direct [FilemanagerDirectory](/api-reference/filemanager/filemanager-directories.md), while root files use a `null` directory ID. Missing directory records are created when necessary during upload or movement.

## Model Definition

**Alias**

`filemanagerFile`

**Relations**

| Key                    | Relation                                                                      | Type       | Relation Field(s)          |
| ---------------------- | ----------------------------------------------------------------------------- | ---------- | -------------------------- |
| `user`                 | [User](/api-reference/users.md)                                               | Belongs to | `user_id`                  |
| `filemanagerDirectory` | [FilemanagerDirectory](/api-reference/filemanager/filemanager-directories.md) | Belongs to | `filemanager_directory_id` |

**Computed Properties**

* `hash` - Hashed representation of the file `id`.
* `url` and `static_url` - Link to the Filemanager metadata page.
* `show_file_content_url` - Access-checked URL that displays the stored content.
* `download_file_content_url` - Content URL with download disposition.

**Capabilities**

* [URL Context](/introduction/resource-capabilities/url-context.md) - Metadata and content URLs resolve to access-checked context containing filename, MIME type, extension, byte size, location, icon, and image preview information where available.

## List

List files visible to the authenticated user.

**Definition**

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

**Request Keys**

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

**Behavior**

* File visibility is derived from the accessible directory path. Expensive relations are not included by list endpoints even when requested.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 31,
    "user_id": 3,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/quarterly-report.pdf",
    "name": "quarterly-report.pdf",
    "extension": "pdf",
    "mime_type": "application/pdf",
    "size": 87236,
    "created_at": "2026-08-06 09:20:00",
    "updated_at": "2026-08-06 09:20:00",
    "deleted_at": null,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 32,
    "user_id": 4,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/site-photo.jpg",
    "name": "site-photo.jpg",
    "extension": "jpg",
    "mime_type": "image/jpeg",
    "size": 187607,
    "created_at": "2026-08-06 09:25:00",
    "updated_at": "2026-08-06 09:25:00",
    "deleted_at": null,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]
```

## List by Path

List direct child files of a normalized directory path. Omitting `path` lists root files.

**Definition**

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

**Route Parameters**

| Parameter | Type     | Description                                |
| --------- | -------- | ------------------------------------------ |
| `path`    | `string` | Optional. Directory path. Defaults to `/`. |

**Request Keys**

| Key      | Type     | Default     | Description                      |
| -------- | -------- | ----------- | -------------------------------- |
| `filter` | `object` | `{}`        | Optional Result Control filters. |
| `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/files/path/Projects%2FReports', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => ['sort' => 'name']
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 31,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/quarterly-report.pdf",
    "name": "quarterly-report.pdf",
    "extension": "pdf",
    "mime_type": "application/pdf",
    "size": 87236,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 32,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/site-photo.jpg",
    "name": "site-photo.jpg",
    "extension": "jpg",
    "mime_type": "image/jpeg",
    "size": 187607,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]
```

## List by Directory

List direct child files of one visible directory.

**Definition**

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

**Route Parameters**

| Parameter              | Type                  | Description           |
| ---------------------- | --------------------- | --------------------- |
| `filemanagerDirectory` | `integer` \| `string` | 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 directory must be visible to the authenticated user. The response contains only its direct visible files.

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 31,
    "user_id": 3,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/quarterly-report.pdf",
    "name": "quarterly-report.pdf",
    "extension": "pdf",
    "mime_type": "application/pdf",
    "size": 87236,
    "created_at": "2026-08-06 09:20:00",
    "updated_at": "2026-08-06 09:20:00",
    "deleted_at": null,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 32,
    "user_id": 4,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/site-photo.jpg",
    "name": "site-photo.jpg",
    "extension": "jpg",
    "mime_type": "image/jpeg",
    "size": 187607,
    "created_at": "2026-08-06 09:25:00",
    "updated_at": "2026-08-06 09:25:00",
    "deleted_at": null,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]
```

## Count

Count visible files after Result Control filters are applied.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/files/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/files/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => ['filter' => ['path' => ['matches_path_recursive' => '/Projects/']]]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
8
```

## Show

Show one visible file.

**Definition**

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

**Route Parameters**

| Parameter         | Type                  | Description      |
| ----------------- | --------------------- | ---------------- |
| `filemanagerFile` | `integer` \| `string` | File 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/files/31', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 31,
  "user_id": 3,
  "filemanager_directory_id": 11,
  "path": "/Projects/Reports/quarterly-report.pdf",
  "name": "quarterly-report.pdf",
  "extension": "pdf",
  "mime_type": "application/pdf",
  "size": 87236,
  "created_at": "2026-08-06 09:20:00",
  "updated_at": "2026-08-06 09:20:00",
  "deleted_at": null,
  "hash": "zn7m24owk63qolxryge8pj05"
}
```

## Show EXIF Data

Return normalized metadata for a JPEG, PNG, or TIFF file.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/filemanager/files/{filemanagerFile}/exif`

**Route Parameters**

| Parameter         | Type                  | Description            |
| ----------------- | --------------------- | ---------------------- |
| `filemanagerFile` | `integer` \| `string` | Image file ID or hash. |

**Behavior**

* Metadata is read from a bounded file prefix. Unsupported formats return an error; supported files without readable metadata return an empty object.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "DateTimeOriginal": "2026:08:05 14:32:10",
  "ImageHeight": 3024,
  "ImageWidth": 4032,
  "Make": "Example Camera",
  "Model": "XC-10",
  "Orientation": 1
}
```

## Create

Upload a file and create its metadata record.

**Definition**

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

**Request Keys**

| Key                        | Type                | Default             | Description                                                                     |
| -------------------------- | ------------------- | ------------------- | ------------------------------------------------------------------------------- |
| `file`\*                   | `file`              | -                   | Uploaded file. Filename and content type determine `extension` and `mime_type`. |
| `path`\*                   | `string`            | -                   | Complete target path. Normalized with a leading slash.                          |
| `filemanager_directory_id` | `integer` \| `null` | Derived from `path` | Direct target directory. When supplied, `name` builds the path.                 |
| `name`                     | `string`            | Derived from `path` | Target filename when a directory ID is supplied.                                |

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

**Behavior**

* `user_id` is set to the authenticated user. Missing directory records in the supplied path are created before the file relation is resolved.
* When `filemanager_directory_id` is present, it and `name` determine the hierarchy and take precedence over a conflicting `path`. A `null` directory ID creates a root file.
* The upload fails when the tenant's configured available storage is insufficient.

**Example Request**

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

```php
$pdf = "%PDF-1.4\n1 0 obj<</Type/Catalog>>endobj\n%%EOF";

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/filemanager/files', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'multipart' => [
        [
            'name' => 'file',
            'contents' => $pdf,
            'filename' => 'safety-guidelines.pdf',
            'headers' => ['Content-Type' => 'application/pdf']
        ],
        ['name' => 'filemanager_directory_id', 'contents' => '11'],
        ['name' => 'name', 'contents' => 'safety-guidelines.pdf']
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "user_id": 3,
    "filemanager_directory_id": 11,
    "path": "/Projects/Reports/safety-guidelines.pdf",
    "name": "safety-guidelines.pdf",
    "extension": "pdf",
    "mime_type": "application/pdf",
    "size": 45,
    "created_at": "2026-08-06 10:30:00",
    "updated_at": "2026-08-06 10:30:00",
    "deleted_at": null,
    "hash": "8q0o2mbzay32zzsrt1g6xzl4"
  }
}
```

## Update

Replace file content, move the file, or rename it.

**Definition**

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

**Route Parameters**

| Parameter         | Type                  | Description      |
| ----------------- | --------------------- | ---------------- |
| `filemanagerFile` | `integer` \| `string` | File ID or hash. |

**Request Keys**

| Key                        | Type                | Description           |
| -------------------------- | ------------------- | --------------------- |
| `file`                     | `file`              | Replacement content.  |
| `path`                     | `string`            | Complete target path. |
| `filemanager_directory_id` | `integer` \| `null` | New direct directory. |
| `name`                     | `string`            | New filename.         |

**Behavior**

* `user_id` remains the authenticated user. The backend rebuilds `path`, `name`, and `filemanager_directory_id` as a consistent hierarchy.
* When `filemanager_directory_id` or `name` is present, those hierarchy fields take precedence over a conflicting `path`; omitted hierarchy fields retain their current values. A `null` directory ID moves the file to the root.
* Replacing content updates the extension, MIME type, and byte size. Moving or replacing a file regenerates its thumbnail or media poster where supported.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/filemanager/files/33', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'filemanager_directory_id' => 12,
        'name' => 'safety-guidelines-2026.pdf'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "user_id": 3,
    "filemanager_directory_id": 12,
    "path": "/Projects/Media/safety-guidelines-2026.pdf",
    "name": "safety-guidelines-2026.pdf",
    "extension": "pdf",
    "mime_type": "application/pdf",
    "size": 45,
    "created_at": "2026-08-06 10:30:00",
    "updated_at": "2026-08-06 10:40:00",
    "deleted_at": null,
    "hash": "8q0o2mbzay32zzsrt1g6xzl4"
  }
}
```

## Delete

Delete the metadata record, stored content, and generated thumbnail.

**Definition**

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

**Route Parameters**

| Parameter         | Type                  | Description      |
| ----------------- | --------------------- | ---------------- |
| `filemanagerFile` | `integer` \| `string` | File ID or hash. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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