Папки

Папки необязательны. Это способ задать группе файлов общие правила: видимость, срок хранения и кэш.

Папка в ответе

{
  "name": "avatars",
  "public": true,
  "retention": { "id": 3, "name": "MONTH" },
  "cache": { "maxAge": null, "visibility": null },
  "createdAt": "2026-11-07T17:10:44+00:00",
  "updatedAt": "2026-11-07T17:10:44+00:00"
}

• public — файлы папки получают публичный адрес /o/…. Корень бакета всегда публичный: файл, загруженный или перенесённый туда, доступен по /o/… без токена.
• retention — сколько живут файлы папки, считая от загрузки.
• cache — своя политика кэша; null — как у бакета.

Срок хранения

В запросе передаётся число, в ответе приходит { "id": 3, "name": "MONTH" }.

Истёкшие файлы удаляет планировщик (раз в 5 минут). Срок видно у каждого файла в expiresAt.

POST /v1/folders

{ "name": "avatars", "public": true, "retention": 3 }

name — до 100 символов: буквы, цифры, пробел, точка, подчёркивание, дефис; начинается с буквы или цифры. Возвращает 201 и папку; если такая уже есть — 409.

GET /v1/folders

Список папок, постранично: page, limit, search.

GET /v1/folders/{name}

Одна папка.

PUT /v1/folders/{name}

Меняет имя, видимость и срок хранения — тело как у создания, все поля задаются заново.

Изменения сразу касаются файлов, которые уже лежат в папке:

• видимость меняется у всех файлов: закрыли папку — их публичные адреса /o/… перестают работать;
• срок хранения пересчитывается у всех файлов от даты их загрузки. Если сократить срок, файлы старше нового срока удалятся при ближайшей очистке — в течение 5 минут.

PATCH /v1/folders/{name}/cache

Задаёт папке свою политику кэша.

{ "maxAge": 604800, "visibility": 1 }

maxAge — 0–31536000 секунд, visibility — 1 (SHARED) · 2 (PRIVATE) · 3 (NO_STORE). Это полная замена: оба поля задаются заново, и пропущенное поле тоже становится null — наследовать от бакета. Подробнее — Кэширование.

DELETE /v1/folders/{name}