Gerer vos fichiers : lister, consulter, supprimer — Collections, RAG & fichiers

Au-dela de l’upload

Uploader un fichier n’est que la premiere etape. La Files API expose des endpoints pour lister, consulter et supprimer vos fichiers. Ces operations sont essentielles pour gerer votre espace de stockage, retrouver des identifiants et nettoyer les fichiers obsoletes.

Lister tous vos fichiers

L’endpoint GET /v1/files retourne la liste de tous les fichiers uploades sur votre compte :

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

La reponse est une liste paginee :

{
  "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": "donnees-clients.csv",
      "purpose": "assistants"
    }
  ]
}

Cette vue d’ensemble vous permet de retrouver un file_id quand vous ne l’avez pas note, de verifier la taille de vos fichiers ou d’identifier les fichiers a supprimer.

Consulter un fichier specifique

Pour obtenir les metadonnees d’un fichier precis, utilisez GET /v1/files/{file_id} :

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

La reponse contient les memes informations que lors de l’upload : identifiant, nom, taille, date de creation et purpose. Cet endpoint est utile pour verifier qu’un fichier existe toujours avant de l’utiliser dans une requete.

Supprimer un fichier

Quand un fichier n’est plus necessaire, supprimez-le avec DELETE /v1/files/{file_id} :

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

La reponse confirme la suppression :

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

Precautions avant suppression

Avant de supprimer un fichier, verifiez qu’il n’est pas :

Reference dans une collection : si le fichier a ete ajoute a une collection (que vous verrez dans les lecons suivantes), sa suppression via la Files API ne le retire pas automatiquement de la collection. Supprimez-le d’abord de la collection
Utilise dans des workflows actifs : si vos applications referencent ce file_id, elles recevront des erreurs apres la suppression

Bonnes pratiques de gestion

Nommage coherent

Donnez des noms explicites a vos fichiers avant l’upload. Le nom original est conserve dans les metadonnees et vous aidera a retrouver vos fichiers :

rapport-q1-2026.pdf plutot que document.pdf
api-specs-v2.json plutot que data.json

Nettoyage regulier

Les fichiers uploades restent stockes indefiniment. Mettez en place une routine de nettoyage :

Listez vos fichiers avec GET /v1/files
Identifiez ceux qui ne sont plus utilises (par date ou par nom)
Supprimez-les avec DELETE /v1/files/{file_id}

Gestion des erreurs

Les erreurs courantes lors de la gestion de fichiers :

404 : le fichier n’existe pas ou a deja ete supprime
401 : cle API invalide ou manquante
413 : fichier trop volumineux (depasse 48 MB)

Points cles a retenir

GET /v1/files liste tous vos fichiers avec leurs metadonnees
GET /v1/files/{id} consulte un fichier specifique
DELETE /v1/files/{id} supprime definitivement un fichier
Nommez vos fichiers de maniere explicite pour faciliter la gestion
Verifiez les dependances (collections, workflows) avant de supprimer