API

Rankion-OS-API (Storage & Files)

Datei-Uploads, Asset-Library, Quota-Verwaltung, Trash-Restore per HTTP.

Die Rankion-OS-API ist die HTTP-Schicht der internen Asset-Library — sie verwaltet Files, Folders, Sharing und User-Preferences. Alle Endpoints liegen unter /v1/os/..., sind team-scoped und benoetigen Authorization: Bearer <token>. Volle Modul-Doku: Rankion OS.

Mode & Preferences

Method	Endpoint	Beschreibung	Credits
PUT	`/v1/os/mode`	OS-Mode toggeln (z.B. `desktop`/`mobile`/`compact`)	—
GET	`/v1/os/preferences`	Aktuelle Layout-/UX-Preferences des Users	—
POST	`/v1/os/preferences`	Preferences setzen — Body als 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 und Share-Link-Verwaltung. Files sind immer einem Folder zugeordnet (Root = folder_id: null).

Method	Endpoint	Beschreibung	Credits
GET	`/v1/os/files`	Paginiert (`?folder_id=&search=&sort=`)	—
POST	`/v1/os/files`	Multipart-Upload `file` + Felder `{folder_id?, title?, tags[]?}`	—
GET	`/v1/os/files/{id}`	Detail inkl. Public-URL, Mime, Size, Owner	—
PUT	`/v1/os/files/{id}`	Metadaten updaten `{title?, tags[]?}`	—
DELETE	`/v1/os/files/{id}`	Soft-Delete in Trash	—
POST	`/v1/os/files/{id}/move`	Body `{folder_id}` — Datei in anderen Ordner schieben	—
POST	`/v1/os/files/{id}/share`	Public-Link erzeugen, optional `{expires_at, password}`	—
DELETE	`/v1/os/files/{id}/share`	Share-Link widerrufen	—

# 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"

Antwort 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	Beschreibung
GET	`/v1/os/folders`	Tree-Liste, Filter `?parent_id=`
POST	`/v1/os/folders`	Body `{name, parent_id?}`
GET	`/v1/os/folders/{id}`	Detail mit Children-Count
PUT	`/v1/os/folders/{id}`	Rename `{name}`
DELETE	`/v1/os/folders/{id}`	Soft-Delete inkl. enthaltener Files
POST	`/v1/os/folders/{id}/move`	Body `{parent_id}`

Desktop & Spotlight

Zwei Convenience-Endpoints fuer das Frontend.

Method	Endpoint	Beschreibung
GET	`/v1/os/desktop`	Aggregiertes Desktop-Payload — gepinnte Files, letzte Folders, Shortcuts
GET	`/v1/os/spotlight`	Globale Suche `?q=...` ueber Files + Folders + Tags

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

Sharing — Public-Link Lifecycle

Nach POST /v1/os/files/{id}/share enthaelt die Response ein share_url-Feld. Der Link funktioniert ohne Login (mit optionalem Password-Gate). DELETE /share widerruft sofort — der Link liefert dann 410 Gone.

# Share-Link erzeugen mit Ablauf
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":"geheim"}'

Quota & Trash

Trash-Restore: PUT /v1/os/files/{id} mit {deleted_at: null} reaktiviert die Datei innerhalb der 30-Tage-Retention.
Quota-Status: ueber GET /v1/os/desktop (Feld storage.usage_bytes / storage.quota_bytes).
Mime-Whitelist und Max-Size: serverseitig konfigurierbar — ueberschrittene Uploads liefern 422.

Pitfalls

Folder-Move ist transaktional. Beim Verschieben eines Folders inkl. Children laeuft der Move in einer DB-Transaktion — bei Fehler bleibt der Originalpfad erhalten.
Share ohne Password ist oeffentlich indizierbar. Setze password oder expires_at, wenn du sensible Files teilst.
Soft-Delete ist nicht final. Files sind 30 Tage restorebar; ein nightly Prune-Job loescht endgueltig.

Verwandt: Rankion OS · Auth · Projekte-API.

Letzte Aktualisierung: 1. Mai 2026