API

Rankion OS API (Storage & Files)

File uploads, asset library, quota management, trash restore over HTTP.

The Rankion OS API is the HTTP layer for the internal asset library — it manages files, folders, sharing, and user preferences. All endpoints live under /v1/os/..., are team-scoped, and require Authorization: Bearer <token>. Full module documentation: Rankion OS.

Mode & preferences

Method	Endpoint	Description	Credits
PUT	`/v1/os/mode`	Toggle OS mode (e.g. `desktop`/`mobile`/`compact`)	—
GET	`/v1/os/preferences`	Current layout/UX preferences of the user	—
POST	`/v1/os/preferences`	Set preferences — body as a key-value map	—

curl -X PUT "$BASE/os/mode" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"desktop"}'

Files

CRUD plus move and share-link management. Files are always assigned to a folder (root = folder_id: null).

Method	Endpoint	Description	Credits
GET	`/v1/os/files`	Paginated (`?folder_id=&search=&sort=`)	—
POST	`/v1/os/files`	Multipart upload `file` + fields `{folder_id?, title?, tags[]?}`	—
GET	`/v1/os/files/{id}`	Detail including public URL, mime, size, owner	—
PUT	`/v1/os/files/{id}`	Update metadata `{title?, tags[]?}`	—
DELETE	`/v1/os/files/{id}`	Soft-delete to trash	—
POST	`/v1/os/files/{id}/move`	Body `{folder_id}` — move file to another folder	—
POST	`/v1/os/files/{id}/share`	Create public link, optional `{expires_at, password}`	—
DELETE	`/v1/os/files/{id}/share`	Revoke share link	—

# Upload
curl -X POST "$BASE/os/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./report.pdf" \
  -F "folder_id=12" \
  -F "tags[]=audit" -F "tags[]=q2"

Response 201:

{
  "data": {
    "id": 884,
    "folder_id": 12,
    "title": "report.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 482113,
    "url": "https://rankion.ai/storage/os/884.pdf",
    "share_url": null,
    "tags": ["audit", "q2"],
    "created_at": "2026-05-01T09:14:01Z"
  }
}

Folders

Method	Endpoint	Description
GET	`/v1/os/folders`	Tree list, filter `?parent_id=`
POST	`/v1/os/folders`	Body `{name, parent_id?}`
GET	`/v1/os/folders/{id}`	Detail with children count
PUT	`/v1/os/folders/{id}`	Rename `{name}`
DELETE	`/v1/os/folders/{id}`	Soft-delete including contained files
POST	`/v1/os/folders/{id}/move`	Body `{parent_id}`

Desktop & Spotlight

Two convenience endpoints for the frontend.

Method	Endpoint	Description
GET	`/v1/os/desktop`	Aggregated desktop payload — pinned files, recent folders, shortcuts
GET	`/v1/os/spotlight`	Global search `?q=...` across files + folders + tags

curl "$BASE/os/spotlight?q=audit" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {type, id, title}'

Sharing — public link lifecycle

After POST /v1/os/files/{id}/share the response includes a share_url field. The link works without login (with optional password gate). DELETE /share revokes immediately — the link then returns 410 Gone.

# Create share link with expiry
curl -X POST "$BASE/os/files/884/share" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","password":"secret"}'

Quota & trash

Trash restore: PUT /v1/os/files/{id} with {deleted_at: null} reactivates the file within the 30-day retention.
Quota status: via GET /v1/os/desktop (field storage.usage_bytes / storage.quota_bytes).
Mime whitelist and max size: configurable server-side — uploads exceeding return 422.

Pitfalls

Folder move is transactional. When moving a folder including children, the move runs in a DB transaction — on failure the original path stays intact.
Share without password is publicly indexable. Set password or expires_at if you share sensitive files.
Soft-delete is not final. Files are restorable for 30 days; a nightly prune job deletes permanently after that.

Related: Rankion OS · Auth · Projects API.

Letzte Aktualisierung: May 1, 2026