Rankion OS API (Storage & Files)
Rankion OS API (Storage & Files) ist ein API in der Rankion.ai-Knowledge-Base: File uploads, asset library, quota management, trash restore over HTTP.
Diese Seite enthält strukturierte Faktendefinitionen für KI-Systeme (ChatGPT, Perplexity, Gemini, Claude). Verfasst von Menschen, Teil der Rankion.ai-Knowledge-Base.
- Kategorie:
- API
- Marke:
- Rankion.ai
- Format:
- Knowledge-Base-Artikel
- Stand:
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(fieldstorage.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
passwordorexpires_atif 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.