Gérer vos fichiers : lister, consulter, supprimer

Ce qui se passe après le centième upload

Uploader un fichier prend trois secondes ; retrouver celui que vous avez envoyé il y a six semaines en prend beaucoup plus si vous n’avez rien prévu. Passé les premiers essais, un compte accumule des dizaines puis des centaines de documents, dont une partie est périmée, une autre dupliquée, et une troisième référencée par des applications qui tournent encore. La Files API expose trois opérations pour tenir cet inventaire : lister, consulter, supprimer. Elles paraissent secondaires tant que le volume est faible, et deviennent indispensables ensuite.

Faire l’inventaire

GET /v1/files retourne l’ensemble des fichiers uploadés sur votre compte :

curl https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY"

La réponse est une liste paginée, chaque entrée reprenant les métadonnées vues à l’upload :

{
  "object": "list",
  "data": [
    {
      "id": "file_abc123",
      "object": "file",
      "bytes": 2458901,
      "created_at": 1710000000,
      "filename": "rapport-annuel.pdf",
      "purpose": "assistants"
    },
    {
      "id": "file_def456",
      "object": "file",
      "bytes": 15230,
      "created_at": 1710100000,
      "filename": "données-clients.csv",
      "purpose": "assistants"
    }
  ]
}

Cette vue résout trois situations très concrètes : retrouver un file_id que vous n’avez pas conservé au moment de l’upload, vérifier le poids réel d’un document qui vous semble anormalement lourd, et repérer les candidats à la suppression en triant sur created_at. C’est aussi le seul endroit où vous verrez d’un coup d’œil que le même rapport a été envoyé trois fois sous trois noms différents.

Vérifier un fichier précis

Quand vous connaissez déjà l’identifiant, GET /v1/files/{file_id} interroge un document unique :

curl https://api.x.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"

Vous récupérez les mêmes informations qu’à l’upload : identifiant, nom, taille, date de création et purpose. L’usage le plus utile de cet appel est défensif. Avant de lancer un traitement qui référence un file_id stocké depuis longtemps dans votre base, une vérification à quelques millisecondes vous évite une erreur en plein milieu d’une chaîne de requêtes facturées.

Supprimer, et ce qu’il faut regarder avant

La suppression se fait avec DELETE /v1/files/{file_id} et la réponse confirme l’opération :

curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"

{
  "id": "file_abc123",
  "object": "file",
  "deleted": true
}

Deux vérifications s’imposent avant d’appuyer sur la détente. D’abord, le fichier peut être référencé dans une collection — la notion que nous détaillerons dans les prochaines leçons. Le supprimer via la Files API ne le retire pas automatiquement de la collection, et vous vous retrouvez avec une référence morte dans votre index : retirez-le d’abord de la collection, ensuite seulement du stockage. Ensuite, le fichier peut être utilisé par des workflows actifs ; toute application qui garde ce file_id en base recevra des erreurs dès la suppression effectuée, souvent en production et rarement au moment où vous surveillez les logs.

Tenir son stock proprement

Le nommage est votre premier outil de gestion, parce que le nom d’origine est conservé dans les métadonnées et constitue l’unique repère lisible dans une liste de cent entrées. rapport-q1-2026.pdf vous dira quelque chose dans huit mois ; document.pdf ne vous dira jamais rien. Le même raisonnement vaut pour api-specs-v2.json face à data.json. Prenez cette habitude au moment où vous préparez le fichier sur votre disque, pas au moment de l’upload : c’est le nom local qui est transmis.

Les fichiers uploadés restent stockés indéfiniment, sans expiration automatique. Une routine de nettoyage trimestrielle suffit à éviter la dérive, en trois temps :

1. Listez vos fichiers avec GET /v1/files
2. Identifiez ceux qui ne sont plus utilisés, par date de création ou par nom
3. Supprimez-les avec DELETE /v1/files/{file_id}

Trois codes d’erreur reviennent dans ces manipulations et se diagnostiquent immédiatement. Un 404 signale un fichier inexistant ou déjà supprimé, cas typique d’un script de nettoyage rejoué deux fois. Un 401 vient d’une clé API absente ou invalide, souvent une variable d’environnement non chargée dans le shell courant. Un 413 indique que le fichier dépasse les 48 MB autorisés et se produit à l’upload, pas à la gestion.

Points clés à retenir

• GET /v1/files liste tous vos fichiers avec leurs métadonnées
• GET /v1/files/{id} consulte un fichier spécifique
• DELETE /v1/files/{id} supprime définitivement un fichier
• Nommez vos fichiers de manière explicite pour faciliter la gestion
• Vérifiez les dépendances (collections, workflows) avant de supprimer