API · s5w

Файлы

Загрузка одним запросом и управление файлами бакета. Все методы требуют токен FULL.

Путь /v1/filesДоступ FULL

Файл в ответе

Все методы, которые возвращают файл, отдают его в одном виде:

json

{
  "id": "Xk3f9QaLm2Pw",
  "name": "photo.webp",
  "folder": "avatars",
  "content": {
    "size": 444,
    "mime": "image/webp",
    "extension": "webp",
    "hash": "57faddf4ac10468a87ad4e986af5da30d519785f908184284526e3d9ccda3645"
  },
  "public": true,
  "deduplicated": false,
  "processed": { "applied": true, "operations": ["resize:300x200", "encode:webp@82"], … },
  "expiresAt": null,
  "privateUrl": "https://s5.example.com/p/Xk3f9QaLm2Pw",
  "publicUrl": "https://s5.example.com/o/b554eae9-…/Xk3f9QaLm2Pw",
  "createdAt": "2026-11-07T17:10:44+00:00",
  "updatedAt": "2026-11-07T17:10:44+00:00"
}

id — короткий идентификатор файла, он же часть адресов раздачи.
content.hash — SHA-256 хранимого содержимого.
deduplicated — только в ответе загрузки: true, если такое содержимое в бакете уже было и место на диске не потрачено. В остальных ответах всегда false.
processed — только в ответе загрузки: что сделала обработка картинки; без опций это { "applied": false, "reason": "no options" }. В остальных ответах всегда null.
publicUrl — есть только у публичного файла.
expiresAt — когда файл удалится по сроку хранения папки; null — бессрочно.

`POST /v1/files`

Загружает файл одним запросом multipart/form-data. Для больших файлов используйте загрузку частями.

Поля формы

Поле	Тип	Описание
`file`	файл	Обязательно. Содержимое.
`folder`	строка	Имя папки. Без него — корень бакета.
`name`	строка	Имя файла. Без него — имя загруженного файла.
`format`	`ORIGINAL` · `WEBP` · `JPEG` · `PNG` · `AVIF`	Перекодировать картинку.
`quality`	1–100	Качество кодирования.
`maxWidth`	16–10000	Уменьшить, если шире.
`maxHeight`	16–10000	Уменьшить, если выше.

bash

curl -H "Authorization: Bearer <токен>" \
  -F file=@photo.png -F folder=avatars -F format=WEBP -F maxWidth=300 \
  http://<хост>:9090/v1/files

Возвращает 201 и файл.

Имя файла уникально в пределах папки (корень бакета — отдельное пространство имён): если оно занято, к нему добавляется номер — photo (1).png. Имя очищается: /, \ и управляющие символы заменяются на -. Если при перекодировании меняется формат, меняется и расширение: photo.png → photo.webp.

`GET /v1/files`

Список файлов бакета, постранично.

Параметр	По умолчанию	Описание
`page`, `limit`	`1`, `25`	Страница и размер (до 100).
`search`	—	Поиск по имени, без учёта регистра.
`folder`	—	Имя папки. Пустая строка — только корень. Без параметра — все файлы.
`sort`	`created`	`created` · `name` · `type` · `size`.
`dir`	`desc`	`asc` · `desc`.

`GET /v1/files/{id}`

Возвращает один файл.

`PUT /v1/files/{id}`

Переименовывает и/или переносит файл.

json

{ "name": "avatar.webp", "folder": "users" }

name обязателен и очищается так же, как при загрузке: a/b.txt сохранится как a-b.txt. Расширение при переименовании не подгоняется — каким задали, таким и будет. Если имя в папке назначения занято — 409. folder — имя папки назначения; без него файл попадает в корень.

При переносе файл получает видимость папки назначения, а также её срок хранения — срок считается от момента переноса.

Корень бакета всегда публичный

Перенос в корень делает файл публичным: у него появляется publicUrl, и он открывается по /o/{bucketId}/{id} без токена. Приватный документ из приватной папки после такого переноса станет доступен всем, у кого есть адрес. Держите приватные файлы в приватных папках.

`DELETE /v1/files/{id}`

Удаляет файл. Возвращает 204. Выданные на файл временные ссылки перестают работать.

Дедупликация

Одинаковое содержимое хранится в бакете один раз (по SHA-256). Копия стоит строку в базе, а не место на диске; удаление одной копии не трогает остальные.