L'endpoint de recherche de documents

Interroger vos bases de connaissances

Jusqu’ici vous avez construit le contenant : des collections, des documents indexés, des métadonnées. Rien de tout cela ne sert tant que vous ne savez pas poser une question. C’est le rôle de POST /v1/documents/search, qui prend une requête en langage naturel et vous renvoie les passages de vos documents qui y répondent le mieux. Imaginez un support client qui reçoit « quel est le délai de rétractation ? » : au lieu de faire lire les conditions générales à un agent, vous envoyez la question à l’endpoint et vous récupérez les trois paragraphes utiles, avec leur score et leur origine.

Structure de la requête

Première chose à retenir, et c’est une source d’erreur classique : cet endpoint vit sur l’API standard (api.x.ai), pas sur la Management API que vous utilisiez pour créer les collections. Vous vous authentifiez donc avec votre clé d’API habituelle. La requête minimale tient en trois champs.

curl -X POST https://api.x.ai/v1/documents/search \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Comment configurer l'\''authentification OAuth ?",
    "source": {
      "collection_ids": ["col_xyz789"]
    },
    "retrieval_mode": {
      "type": "hybrid"
    }
  }'

Paramètres principaux

• query : votre question en langage naturel. Plus la question est spécifique, plus les résultats seront pertinents
• source.collection_ids : un tableau d’identifiants de collections à interroger. Vous pouvez chercher dans plusieurs collections en une seule requête
• retrieval_mode.type : le mode de recherche à utiliser (keyword, semantic ou hybrid)

Lire la réponse

L’API ne vous renvoie pas des documents entiers mais des fragments, les chunks découpés lors de l’indexation, classés du plus pertinent au moins pertinent.

{
  "results": [
    {
      "content": "Pour configurer OAuth, commencez par...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "guide-securite.pdf",
        "page": 12
      }
    },
    {
      "content": "Le flux OAuth 2.0 utilise...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "reference-api.pdf",
        "page": 45
      }
    }
  ]
}

Chaque entrée porte quatre informations :

• content : l’extrait textuel du document
• score : un score de pertinence entre 0 et 1
• document_id : l’identifiant du fichier source
• metadata : les métadonnées du document (nom, page, champs personnalisés)

Dans l’exemple ci-dessus, le premier extrait vient de la page 12 de guide-securite.pdf avec un score de 0,92, le second de la page 45 d’un autre fichier à 0,87. Ces deux valeurs vous suffisent pour construire une interface qui affiche la réponse et, juste en dessous, un lien « voir le passage d’origine, page 12 ». Le score, lui, sert de seuil : beaucoup d’équipes écartent tout résultat sous 0,5 plutôt que de laisser le modèle raisonner sur du bruit.

Croiser plusieurs collections

Si collection_ids est un tableau, ce n’est pas un hasard. Une question de client mêle souvent plusieurs univers documentaires, et vous n’avez aucune envie de faire trois appels puis de fusionner les résultats à la main.

{
  "query": "Politique de remboursement",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Ici, la documentation produit, la FAQ et les conditions générales sont interrogées ensemble. Les résultats reviennent fusionnés et triés par score, indépendamment de leur collection d’origine : un extrait de la FAQ à 0,94 passera devant un extrait des CGV à 0,71. Vous croisez donc des sources hétérogènes en un seul aller-retour réseau.

Ce que cela coûte

La recherche dans les collections est facturée 2,50 $ par 1 000 appels, et ce tarif ne bouge pas selon le nombre de collections interrogées ni la taille des documents indexés. Comparez avec les file attachments, ces fichiers individuels passés via input_file, facturés 10 $ par 1 000 appels : dès que vous interrogez les mêmes documents de façon répétée, la collection revient quatre fois moins cher. Un assistant interne qui traite 20 000 questions par mois paie 50 $ en collections là où il paierait 200 $ en pièces jointes — pour un résultat en prime plus rapide, puisque l’index existe déjà.

Tarifs relevés le 5 août 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille en vigueur sur la page officielle des modèles et tarifs xAI.

Points clés à retenir

• L’endpoint POST /v1/documents/search interroge vos collections en langage naturel
• Trois modes de recherche disponibles : keyword, semantic, hybrid
• Vous pouvez chercher dans plusieurs collections simultanément
• Les résultats sont classés par score de pertinence avec le contenu source
• Le coût est de $2.50 par 1 000 appels, quatre fois moins cher que les file attachments