API

API de Rankion OS (Storage & Files)

File uploads, asset library, gestión de cuota y restore de trash por HTTP.

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 (campo storage.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 password o expires_at cuando 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.

Letzte Aktualisierung: 1 de mayo de 2026