RUEN
API · s5w

Client API

Everything a client application does: uploads, files, folders and temporary links. Every request works in one bucket — the one the token was issued for.

Address http://<host>:9090/v1Authorization Bearer tokenFormat JSON

Spec and Postman

The whole client API in two ready-made files — in Russian and in English. They live in the S5W repository (docs/) and are pulled in on every build of this documentation, so this is always the latest version.

Import by link

Postman (Import → Link), Swagger Editor (File → Import URL) and SDK generators accept a file by its address — “Import link” copies the direct address in the repository.

Sections

/v1/files
Files

Single-request upload, listing, renaming, moving, deleting.

/v1/uploads
Chunked upload

Large files that resume after a break, with deduplication by hash.

/v1/folders
Folders

Visibility, retention and cache policy per folder.

/v1/…/link
Temporary links

Signed links with an expiry and a download limit.

/o · /p · /t
Delivery

Three ways files are served, Range, ETag, ?download=1.

Image processing

Size, format and quality — right at upload time.

PHP SDK

There is a ready-made PHP client — S5W SDK (composer require flytachi/winter-sdk-s5w). It picks between a single-request and a chunked upload by itself, retries broken chunks, turns responses into objects and errors into exceptions by status.

Tokens

A token is issued in the panel (or through the admin API) for a specific bucket and sent in a header:

http
Authorization: Bearer s5w_…

A token has one of two access levels:

Level In the panel What it allows
BASIC delivery only GET /v1/check and downloading with the token, GET /p/{id}
FULL full access everything: files, uploads, folders, links

A token can be limited in time, disabled or reissued (rotated) — after a rotation the old value stops working at once.

Token check

GET /v1/check

Checks the token and returns its bucket, access level and space. Available to any active token.

bash
curl -H "Authorization: Bearer <token>" http://<host>:9090/v1/check

Result

json
{
  "bucket": { "id": "b554eae9-f8de-453f-8614-612069231234", "name": "media" },
  "access": { "id": 2, "name": "FULL" },
  "expiresAt": null,
  "bytes": { "quota": 104857600, "used": 3937, "free": 104853663 }
}

Errors

An error is an HTTP status and JSON with the code and message fields:

json
{ "code": 422, "message": "Uploaded data does not match the declared checksum" }

When validation fails, errors is added — messages per field:

json
{
  "code": 422,
  "message": "Validation failed",
  "errors": { "name": ["may contain letters, digits, space, dot, underscore, dash"] }
}
Code When
400 No file sent; an empty or too small upload chunk
401 No token, or the token is unknown
403 The token is disabled, expired, or its level is too low
404 No such file, upload or link; on /v1/folders/{name} requests — no such folder
409 Conflict: the folder already exists, the chunk offset does not match, the upload is not finished, the bucket is not active
413 Over the bucket quota, a chunk over 16 MiB, a body over 32 MiB (that answer has no body: the server cuts it off)
416 A Range outside the file
422 Validation failed, the folder given in folder does not exist, the hash does not match, the image cannot be processed
501 The server has no image processing or no encoder for the requested format
507 No space left on the server disk

Pagination

Lists take page (from 1) and limit (up to 100, 25 by default) and answer like this:

json
{
  "meta": { "current": 1, "size": 25, "total": 42, "pages": 2, "previous": null, "next": 2 },
  "data": [ … ]
}

The exception is GET /v1/files/{id}/links: it answers an array without pagination.

Deleting

Deleting answers 204 with no body. The exception is DELETE /v1/links: 200 and { "epoch": … }.

Time

Every timestamp in responses is RFC 3339 (ISO 8601) with a time zone: 2026-11-08T17:10:44+00:00. The format is the same in every response; the standard libraries of any language parse it as is.

Enumeration values

In requests, enumerations are sent as numbers: "retention": 3, "disposition": 1, "visibility": 1. The exception is format: it is a string, "format": "WEBP". In responses, enumerations come as an object { "id": 3, "name": "MONTH" }.