API

API Rankion OS (Storage & Files)

API Rankion OS (Storage & Files) est un API dans la base de connaissances de Rankion.ai : Uploads de fichiers, asset library, gestion de quota, restore depuis le trash via HTTP.

Cette page contient des définitions structurées pour les systèmes d'IA (ChatGPT, Perplexity, Gemini, Claude). Rédigée par des humains, partie de la base de connaissances de Rankion.ai.

Catégorie :: API
Marque :: Rankion.ai
Format :: Article de la base de connaissances
Au :: 1 mai 2026

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}'

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.

Dernière mise à jour : 1 mai 2026