Routes des ressources

Ce chapitre décrit les ressources que votre organisation gère par l'API : les document stores (base de connaissances vectorielle), les outils, les variables, les identifiants, les statistiques et la conformité. Toutes les routes sont sous /api/v1, exigent un jeton (Authorization: Bearer <token>) sauf mention contraire, et sont cloisonnées par organisation. <hote-api> est défini dans Swagger.

Document Store (Qdrant)

Un document store est une collection vectorielle (Qdrant) cloisonnée par organisation, utilisée pour la recherche sémantique. L'identifiant du store sert de nom de collection.

Créer un store

Corps : name et workspace_id obligatoires, description facultatif.

curl -X POST "https://<hote-api>/api/v1/document-store/store" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Base juridique","workspace_id":"<uuid-espace>"}'

Réponse 201 : le nouveau store, avec id (c'est le <store-id> des commandes suivantes), name, description, status, workspace_id et created_date.

Indexer un texte

POST /api/v1/document-store/upsert/{id} : {id} est l'identifiant du store. Corps : content (le texte), source_id et metadata facultatifs. La réponse est {"store_id", "source_id", "chunks_ingested"}. L'ingestion est soumise au quota de vecteurs du plan (refus 402, ou 503 si le décompte n'est pas possible).

curl -X POST "https://<hote-api>/api/v1/document-store/upsert/<store-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"content":"Le droit a l oubli est prevu par l article 17 du RGPD.","source_id":"rgpd-art-17"}'

Interroger

curl -X POST "https://<hote-api>/api/v1/document-store/vectorstore/query" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query":"droit a l oubli","store_id":"<store-id>"}'

Réponse : {"query", "store_id", "results": [...], "total": N}.

Récupérer et crawler une page

POST .../scrape/page prend url et, pour indexer le résultat, store_id. POST .../crawl prend url et store_id et répond 202 avec un crawl_id à suivre sur GET .../crawl-progress/{crawl_id}.

Ce qui n'existe pas, ou ne fonctionne pas encore

• Il n'y a pas de route .../store/{id}/upload (téléversement multipart), ni .../store/{id}/crawl, ni .../store/{id}/chunks. L'indexation de texte passe par upsert/{id}. Un chunk se modifie (PUT) et se supprime (DELETE) sur /api/v1/document-store/chunks/{store_id}/{loader_id}/{chunk_id}. Ses métadonnées se modifient (PATCH) sur le même chemin suivi de /metadata. Il n'y a pas de lecture (GET) sur ce chemin : les chunks se lisent par GET /api/v1/documents/{doc_id}/chunks et GET /api/v1/doc-chunks/{id}.
• Trois routes de loader répondent 503 FEATURE_PENDING (capacité en sommeil, la réponse l'annonce au lieu de simuler un succès) : POST /api/v1/document-store/loader/process/{loader_id}, POST /api/v1/document-store/loader/upload-url et POST /api/v1/document-store/loader/upload-table.
• POST /api/v1/document-store/refresh et .../refresh/{store_id} accusent réception ("status": "queued") sans lancer de traitement.
• Pour les documents bruts (fichiers), voir aussi /api/v1/documents et /api/v1/attachments.

Outils personnalisés

Corps de création, en camelCase : name, description, color, iconSrc, schema (chaîne), func (chaîne), workspaceId.

Variables

Corps de création : name, workspace_id obligatoires ; value et type facultatifs.

Identifiants

curl -X POST "https://<hote-api>/api/v1/credentials" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ma cle de service","value":"<secret>"}'

Pour brancher un connecteur, envoyez credentialName et plainDataObj (un objet de champs) à la place de value, comme à l'étape 1 de Connecter Odoo à la passerelle MCP. workspaceId est facultatif (par défaut, le premier espace accessible). La réponse est 201, avec la fiche : id, name, credential_name, masked_value, workspace_id, created_at et updated_at.

La valeur est chiffrée au repos (AES-256-GCM, clé dérivée par identifiant) et n'est jamais renvoyée en clair : les réponses portent une valeur masquée. PUT et DELETE sur /api/v1/credentials sans identifiant sont refusés par conception (412).

Statistiques

/api/v1/stats/dashboard est un autre chemin vers le même tableau de bord. La famille /api/v1/stats/* compte plus de vingt autres routes de lecture (leads, workflows, security, latency, ollama, entre autres). La liste complète est dans le contrat de routes de router.rs.

Conformité et audit

/api/v1/compliance/status rend des statuts gradués (par exemple "gdpr": {"status": "partial", ...} et "ai_act": {"status": "in_progress", ...}), dérivés de signaux réels, jamais une affirmation figée de conformité totale.

Il n'existe pas de sous-route rgpd ni audit-log sous compliance (d'anciennes versions de ce livre les citaient). Le journal d'audit se lit sur /api/v1/admin/audit. La route GET /api/v1/audit/events existe mais répond 501 : elle n'est pas branchée sur le registre, et sa réponse nomme la route canonique.

Voir aussi

• Routes des gateways et de la prédiction : gateways, prédiction, retours utilisateur et historique des conversations
• Routes MCP : transport MCP par session, pour appeler les outils des connecteurs
• Documentation Swagger : obtention du jeton, format des erreurs et limites de débit
• OpenBao et secrets : coffre optionnel pour les secrets des connecteurs, prioritaire sur la base
• Analytique : la page Conformité EU qui affiche le rapport de l'API