File and folder actions

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.

Storages#

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

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

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`.

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.

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.