API de Rankion OS (Storage & Files)
API de Rankion OS (Storage & Files) es un API en la base de conocimientos de Rankion.ai: File uploads, asset library, gestión de cuota y restore de trash por HTTP.
Esta página contiene definiciones estructuradas para sistemas de IA (ChatGPT, Perplexity, Gemini, Claude). Redactada por humanos, parte de la base de conocimientos de Rankion.ai.
- Categoría:
- API
- Marca:
- Rankion.ai
- Formato:
- Artículo de la base de conocimientos
- A fecha de:
La API de Rankion OS es la capa HTTP de la asset library interna — gestiona files, folders, sharing y user preferences. Todos los endpoints viven bajo /v1/os/..., están scope al team y requieren Authorization: Bearer <token>. Documentación completa del módulo: Rankion OS.
Mode y preferences
| Method | Endpoint | Descripción | Créditos |
|---|---|---|---|
| PUT | /v1/os/mode |
Toggle del OS mode (p. ej. desktop/mobile/compact) |
— |
| GET | /v1/os/preferences |
Preferencias actuales de layout/UX del usuario | — |
| POST | /v1/os/preferences |
Setear preferencias — body como mapa key-value | — |
curl -X PUT "$BASE/os/mode" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mode":"desktop"}'
Files
CRUD más move y gestión de share links. Los files siempre pertenecen a un folder (root = folder_id: null).
| Method | Endpoint | Descripción | Créditos |
|---|---|---|---|
| GET | /v1/os/files |
Paginado (?folder_id=&search=&sort=) |
— |
| POST | /v1/os/files |
Multipart upload file + campos {folder_id?, title?, tags[]?} |
— |
| GET | /v1/os/files/{id} |
Detalle con public URL, mime, size, owner | — |
| PUT | /v1/os/files/{id} |
Update de metadatos {title?, tags[]?} |
— |
| DELETE | /v1/os/files/{id} |
Soft-delete a trash | — |
| POST | /v1/os/files/{id}/move |
Body {folder_id} — mover el file a otro folder |
— |
| POST | /v1/os/files/{id}/share |
Crear public link, opcional {expires_at, password} |
— |
| DELETE | /v1/os/files/{id}/share |
Revocar 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 | Descripción |
|---|---|---|
| GET | /v1/os/folders |
Lista en árbol, filtro ?parent_id= |
| POST | /v1/os/folders |
Body {name, parent_id?} |
| GET | /v1/os/folders/{id} |
Detalle con children count |
| PUT | /v1/os/folders/{id} |
Rename {name} |
| DELETE | /v1/os/folders/{id} |
Soft-delete con files contenidos |
| POST | /v1/os/folders/{id}/move |
Body {parent_id} |
Desktop y Spotlight
Dos endpoints de conveniencia para el frontend.
| Method | Endpoint | Descripción |
|---|---|---|
| GET | /v1/os/desktop |
Payload agregado del desktop — files pinned, últimos folders, shortcuts |
| GET | /v1/os/spotlight |
Búsqueda global ?q=... sobre files + folders + tags |
curl "$BASE/os/spotlight?q=audit" \
-H "Authorization: Bearer $TOKEN" | jq '.data[] | {type, id, title}'
Sharing — lifecycle del public link
Tras un POST /v1/os/files/{id}/share, la response incluye un campo share_url. El link funciona sin login (con password gate opcional). DELETE /share revoca al instante — el link devuelve entonces 410 Gone.
# Crear share link con expiración
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 y trash
- Trash restore:
PUT /v1/os/files/{id}con{deleted_at: null}reactiva el file dentro de los 30 días de retención. - Estado de cuota: vía
GET /v1/os/desktop(campostorage.usage_bytes/storage.quota_bytes). - Whitelist de mime y max size: configurables en servidor — los uploads que las superen devuelven
422.
Pitfalls
- El folder move es transaccional. Mover un folder con sus children corre dentro de una transacción de BD — ante error, el path original queda intacto.
- Un share sin password es indexable públicamente. Pon
passwordoexpires_atcuando compartas archivos sensibles. - El soft-delete no es definitivo. Los files son restaurables 30 días; un job nightly de prune los borra definitivamente.
Relacionado: Rankion OS · Auth · API de Proyectos.