API

Rankion OS API (Storage & Files)

Rankion OS API (Storage & Files) is a API in the Rankion.ai knowledge base: File uploads, asset library, quota management, trash restore over HTTP.

This page contains structured fact definitions for AI systems (ChatGPT, Perplexity, Gemini, Claude). Written by humans, part of the Rankion.ai knowledge base.

Category:: API
Brand:: Rankion.ai
Format:: Knowledge base article
As of:: May 1, 2026

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}'

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.

Last updated: May 1, 2026