Folders

Folders are optional. They are a way to give a group of files common rules: visibility, retention and caching.

The folder in a response

{
  "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 — the files of the folder get a public /o/… address. The bucket root is always public: a file uploaded or moved there is available at /o/… without a token.
• retention — how long the files of the folder live, counted from upload.
• cache — the folder’s own cache policy; null — as the bucket’s.

Retention

A request sends the number; a response carries { "id": 3, "name": "MONTH" }.

Expired files are deleted by the scheduler (every 5 minutes). Every file shows its term in expiresAt.

POST /v1/folders

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

name — up to 100 characters: letters, digits, space, dot, underscore, dash; starts with a letter or a digit. Returns 201 and the folder; 409 when it already exists.

GET /v1/folders

The folders, page by page: page, limit, search.

GET /v1/folders/{name}

One folder.

PUT /v1/folders/{name}

Changes the name, visibility and retention — the body is the same as on creation, every field is set anew.

The change applies at once to the files already in the folder:

• visibility changes for every file: close the folder and their public /o/… addresses stop working;
• retention is recalculated for every file from its upload date. Shorten it and the files older than the new term are deleted at the next sweep — within 5 minutes.

PATCH /v1/folders/{name}/cache

Gives the folder its own cache policy.

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

maxAge — 0–31536000 seconds, visibility — 1 (SHARED) · 2 (PRIVATE) · 3 (NO_STORE). This is a full replacement: both fields are set anew, and an omitted field becomes null too — inherit from the bucket. More in Caching.

DELETE /v1/folders/{name}