API

API Rankion OS (Storage & Files)

Uploads de fichiers, asset library, gestion de quota, restore depuis le trash via HTTP.

L'API Rankion OS est la couche HTTP de la bibliothèque d'assets interne — elle gère les fichiers, dossiers, partage et préférences utilisateur. Tous les endpoints sont sous /v1/os/..., team-scoped et nécessitent Authorization: Bearer <token>. Doc module complète : Rankion OS.

Mode & préférences

Méthode	Endpoint	Description	Crédits
PUT	`/v1/os/mode`	Toggle du mode OS (par ex. `desktop`/`mobile`/`compact`)	—
GET	`/v1/os/preferences`	Préférences layout/UX courantes de l'utilisateur	—
POST	`/v1/os/preferences`	Définir des préférences — Body sous forme de map clé-valeur	—

curl -X PUT "$BASE/os/mode" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"desktop"}'

Files

CRUD plus déplacement et gestion des liens de partage. Les fichiers sont toujours rattachés à un dossier (racine = folder_id: null).

Méthode	Endpoint	Description	Crédits
GET	`/v1/os/files`	Paginé (`?folder_id=&search=&sort=`)	—
POST	`/v1/os/files`	Upload multipart `file` + champs `{folder_id?, title?, tags[]?}`	—
GET	`/v1/os/files/{id}`	Détail incl. URL publique, mime, taille, owner	—
PUT	`/v1/os/files/{id}`	Mettre à jour les métadonnées `{title?, tags[]?}`	—
DELETE	`/v1/os/files/{id}`	Soft-delete vers le trash	—
POST	`/v1/os/files/{id}/move`	Body `{folder_id}` — déplacer le fichier dans un autre dossier	—
POST	`/v1/os/files/{id}/share`	Créer un lien public, optionnellement `{expires_at, password}`	—
DELETE	`/v1/os/files/{id}/share`	Révoquer le lien de partage	—

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

Réponse 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

Méthode	Endpoint	Description
GET	`/v1/os/folders`	Liste arborescente, filtre `?parent_id=`
POST	`/v1/os/folders`	Body `{name, parent_id?}`
GET	`/v1/os/folders/{id}`	Détail avec children-count
PUT	`/v1/os/folders/{id}`	Renommer `{name}`
DELETE	`/v1/os/folders/{id}`	Soft-delete incl. fichiers contenus
POST	`/v1/os/folders/{id}/move`	Body `{parent_id}`

Desktop & Spotlight

Deux endpoints de commodité pour le frontend.

Méthode	Endpoint	Description
GET	`/v1/os/desktop`	Payload Desktop agrégé — fichiers épinglés, derniers dossiers, raccourcis
GET	`/v1/os/spotlight`	Recherche globale `?q=...` sur fichiers + dossiers + tags

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

Sharing — cycle de vie du lien public

Après POST /v1/os/files/{id}/share, la réponse contient un champ share_url. Le lien fonctionne sans login (avec password gate optionnel). DELETE /share révoque immédiatement — le lien renvoie alors 410 Gone.

# Créer un lien de partage avec expiration
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} avec {deleted_at: null} réactive le fichier dans la fenêtre de rétention de 30 jours.
Statut quota : via GET /v1/os/desktop (champ storage.usage_bytes / storage.quota_bytes).
Whitelist mime et taille max : configurables côté serveur — les uploads dépassant les limites renvoient 422.

Pièges

Folder-Move est transactionnel. Lors du déplacement d'un dossier avec ses children, le move tourne dans une transaction DB — en cas d'erreur, le chemin original est conservé.
Un share sans password est indexable publiquement. Définis password ou expires_at quand tu partages des fichiers sensibles.
Le soft-delete n'est pas définitif. Les fichiers sont restaurables 30 jours ; un job nightly de prune les supprime définitivement.

Voir aussi : Rankion OS · Auth · API Projets.

Letzte Aktualisierung: 1 mai 2026