---
title: "File and folder actions"
description: "Browse, upload, copy, rename, move and delete the files and folders of the file storages through the REST API."
canonical: files.html
navigation-title: "Files"
---

<a id="usage-files"></a>

<a id="file-and-folder-actions"></a>

# File and folder actions

- [Storages](#storages)
- [Files](#files)
- [Folders](#folders)
- [Conflicts](#conflicts)
- [Permissions](#permissions)

You can read and manage files and folders of the file storages (FAL). All paths
are below `/typo3/api/v1/`. The API uses two identifiers:

- **Folders** use their combined identifier, for example `1:/user_upload/`.
  The `folders` endpoints get it in the query parameter `identifier`.
- **Files** use their uid (`sys_file`). The uid does not change when you
  rename, move or replace a file.

<a id="storages"></a>

## Storages

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `storages` | Lists the file storages of the user with their entry folders (file mounts). |

<a id="files"></a>

## Files

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `files/{uid}` | Gets a file: identifier, folder, name, extension, MIME type, size, dates, public URL, a reference to its metadata record and the permissions of the user. |
| `POST` | `files?folder=…&name=…` | Uploads a file. The request body is the content of the file. |
| `PUT` | `files/{uid}?name=…` | Replaces the content of a file with the request body. `name` also renames the file, for example if its file type changes. |
| `PATCH` | `files/{uid}` | Renames a file (`name`), moves it to another folder (`folder`), or both. |
| `DELETE` | `files/{uid}` | Deletes a file. |

Upload an image

```bash
curl -X POST \
    'https://example.org/typo3/api/v1/files?folder=1:/&name=logo.png' \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: image/png' \
    --data-binary @logo.png
```

<a id="folders"></a>

## Folders

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `folders?identifier=…` | Gets a folder and its content. Subfolders come first, and both are in the order of their names. Use `limit` (1 to 200, default 50) and `cursor` for pagination. `cursor` takes the `next` value of the previous page. `name` returns only the file or subfolder with exactly this name, so you can check if it exists. |
| `POST` | `folders?identifier=…` | Creates a folder (`type: folder`) or a file with the given `content` (`type: file`) with the name `name` in the folder. With `copyFrom`, it copies a file (`{"file": <uid>}`) or a folder (`{"folder": "<identifier>"}`) into the folder. |
| `PATCH` | `folders?identifier=…` | Renames a folder (`name`), moves it into another folder (`parent`), or both. The identifier of the folder changes. The response contains the new identifier. |
| `DELETE` | `folders?identifier=…` | Deletes a folder. To delete a folder that is not empty, use `recursive=1`. |

<a id="conflicts"></a>

## Conflicts

If a file or folder with the same name exists, the request fails with status
`409`. To prevent this, send the parameter `conflictMode` when you copy, move,
rename or upload:

- **`rename`**

  Adds a number to the new name.
- **`replace`**

  Overwrites the existing file.

The API does not delete files and folders if records use the files. The request
then fails with status `409`.

<a id="permissions"></a>

## Permissions

The file permissions and file mounts of the backend user apply when you read.
To create, change and delete, the user must also have access to the backend
module Media. TYPO3 logs all changes, as in the backend.