Ontologie permet de rechercher dans les définitions métier, les données opérationnelles et les documents. Ces API donnent aux applications et aux assistants les moyens de retrouver une ressource, réunir des pièces justificatives, explorer des relations et comprendre le déroulement d’une recherche.
Cette référence présente 30 opérations de recherche, regroupées par capacité, avec leurs entrées, leurs résultats et des exemples métier.
Choisir une API selon la capacité
| Besoin | API à privilégier |
|---|---|
| Rechercher sur plusieurs surfaces métier | retrieval/search, avec capabilities et explain |
| Retrouver une définition métier | search, ontology/search, search/global |
| Recommander ou comparer des définitions | retrieval/recommend, ontology/structure/similar |
| Retrouver des pièces documentaires | documentation/search, similarité documentaire et liens entité–documents |
| Retrouver un objet opérationnel et son contexte | Recherche d’instances, contexte, relations et voisinage |
| Explorer les relations | Voisins, parcours, chemins, expansion, impact et recherche contrainte du graphe |
| Compter des distributions exactes | retrieval/facets |
| Examiner la complétude des données ou une évolution de modèle | Comparaison et profil d’instances, impact, validation et comparaison de modèles |
Éléments et contrats
Surfaces et modes de recherche
| Surface | Contenu |
|---|---|
processes | Définitions métier (ObjectTypes et LinkTypes), actions et workflows, selon l’API choisie |
records | Instances canoniques et enregistrements connectés autorisés, selon le lecteur |
documents | Contenu de la GED et passages citables ; images lorsque le mode est pris en charge |
Un ObjectType définit un type d’objet métier, par exemple un client ou une commande. Une instance représente un objet individuel de ce type. Un LinkType définit une relation métier.
| Mode | Rôle |
|---|---|
deterministic | Retrouver des identifiants, champs lisibles et filtres selon des règles définies |
lexical | Retrouver des ressources par leurs mots et correspondances textuelles |
semantic | Retrouver des ressources par leur sens grâce à la similarité vectorielle |
hybrid | Combiner recherche lexicale et sémantique |
hybrid_graph | Enrichir une recherche documentaire par des éléments de graphe autorisés, lorsque la surface le prend en charge |
auto | Laisser l’orchestration sélectionner une stratégie disponible |
Les modes varient selon l’API et la surface. Consultez retrieval/capabilities et le mode effectivement exécuté. La présence d’une recherche sémantique sur une surface ne l’étend pas automatiquement aux enregistrements.
Les contrats de composition exposent les combinaisons suivantes :
| Surface demandée | Modes déclarés | Scopes requis pour la composition |
|---|---|---|
processes | auto, deterministic, lexical, semantic, hybrid | nodes.read, actions.read, workflow.read |
records | auto, deterministic | nodes.read, livedata.read ; pipelines.read en plus si un dataset est sélectionné |
documents | auto, lexical, semantic, hybrid, hybrid_graph | knowledge.read ; les éléments de graphe demandent aussi les droits associés |
Les autres API ont leurs propres contrats : graph_traversal désigne les parcours de graphe dans le catalogue et rag_context l’assemblage de contexte RAG. Ces deux libellés ne sont pas des valeurs du paramètre modes de la composition.
Composition et exploration des résultats
1. Découvrir les capacités disponibles
GET /api/v1/retrieval/capabilities
Liste les surfaces de recherche, leurs modes, les limites et les scopes requis. Sert à configurer un client selon les capacités déclarées par le workspace.
Entrées : Aucun corps de requête.
Résultat : Capacités déclarées et raisons de disponibilité ; la réponse ne teste pas la santé des index.
Exemple métier : Adapter le sélecteur de recherche d’une application aux modes disponibles.
2. Rechercher sur plusieurs surfaces métier
POST /api/v1/retrieval/search
Compose une recherche sur les processus, les enregistrements et les documents. Chaque surface conserve ses résultats, sa provenance et le mode effectivement exécuté. Peut produire un contexte cité.
Entrées : query, surfaces, modes ; options filters, limit, includeContext, contextBudget.
Résultat : Résultats regroupés par surface, citations et diagnostics d’exécution ; une réponse peut être explicitement partielle.
Exemple métier : Retrouver les données, procédures et définitions accessibles autour du terme « client ».
3. Comprendre une recherche exécutée
POST /api/v1/retrieval/explain
Exécute la même recherche que retrieval/search puis expose son déroulement : modes demandés et exécutés, replis, couverture et compteurs.
Entrées : Même corps que retrieval/search.
Résultat : Provenance et statistiques, sans texte de requête, titres, extraits ni contenu du contexte. L’appel consomme une recherche réelle.
Exemple métier : Expliquer pourquoi une recherche a utilisé le mode lexical plutôt que sémantique.
4. Compter et filtrer une population
POST /api/v1/retrieval/facets
Calcule des distributions exactes sur une population explicitement sélectionnée : instances canoniques, enregistrements Live Data courants, dataset publié, documents courants ou catalogue de processus.
Entrées : surface, population, facets ; cible selon la population (objectTypeId ou targetId), filtres et maxValues.
Résultat : Valeurs, effectifs et comptes distincts pour valeurs absentes ou invalides. Les totaux portent sur la population autorisée, sans somme implicite entre sources.
Exemple métier : Présenter la répartition des documents par langue ou des instances par statut.
Définitions et navigation métier
5. Rechercher les définitions par mots ou par sens
GET /api/v1/search
Recherche les ObjectTypes et LinkTypes lisibles avec une stratégie déterministe, lexicale, sémantique ou hybride. Propose reclassement, diversification et explication des scores.
Entrées : q ; options types, mode, limit, espace_id, rerank, graphBoost, explain, mmr.
Résultat : Définitions classées, scores et informations sur la stratégie exécutée. graphBoost utilise la connectivité pour le classement.
Exemple métier : Retrouver le type métier « fournisseur » à partir d’une formulation proche de son sens.
6. Naviguer dans les ressources du workspace
GET /api/v1/search/global
Fédère une recherche lexicale dans les définitions, instances, workflows, actions et vues enregistrées accessibles.
Entrées : q ; options types, objectTypeId, limit.
Résultat : Résultats regroupés par type de ressource, destinés à la navigation.
Exemple métier : Alimenter une barre de recherche globale avec les ressources liées à « contrat ».
7. Rechercher dans les métadonnées de l’ontologie
GET /api/v1/ontology/search
Recherche lexicale paginée dans le nom, les alias, la description et les propriétés des ObjectTypes et LinkTypes actifs.
Entrées : q ; options types, includeProperties, espaceId, limit, offset.
Résultat : Définitions correspondantes, champs de correspondance et propriétés si demandées.
Exemple métier : Proposer une autocomplétion lors du choix d’un type dans un formulaire.
8. Recommander des définitions par exemples
POST /api/v1/retrieval/recommend
Classe des définitions à partir d’exemples positifs et, facultativement, négatifs. Le mode lexical ou sémantique est choisi explicitement ; les exemples sont exclus des suggestions.
Entrées : population: "current_definitions", mode, positiveIds ; options negativeIds, types, limit.
Résultat : Définitions recommandées et scores de proximité. Le score ne représente pas une probabilité.
Exemple métier : Explorer des définitions proches de types déjà jugés pertinents par un utilisateur.
9. Comparer la structure de types d’objets
POST /api/v1/ontology/structure/similar
Compare les propriétés déclarées ou les formes de relations de types d’objets actifs. Le choix porte sur les propriétés nommées, les formes de propriétés ou les formes de relations.
Entrées : population, objectTypeId, comparison ; options limit, minScore.
Résultat : Types proches, scores et éléments de comparaison explicables. Les scores de propriétés et de relations restent séparés.
Exemple métier : Repérer des modèles aux structures proches avant d’étudier leur harmonisation.
Documents et contexte RAG
10. Rechercher dans la bibliothèque documentaire
POST /api/documentation/search
Recherche spécialisée dans la GED, avec modes de retrieval et filtres documentaires. La modalité image utilise l’index visuel du workspace lorsqu’il est disponible.
Entrées : query ; options retrievalMode, modality, espaceId, tags, fileTypes, category, limit, includeImages.
Résultat : Passages ou images pertinents, citations et diagnostics. includeImages enrichit les résultats textuels ; modality: "image" sélectionne la recherche visuelle.
Exemple métier : Retrouver une clause de contrat ou une page visuelle pertinente dans les documents accessibles.
11. Assembler un contexte RAG (compatibilité)
POST /api/v1/rag/context
Assemble des sources documentaires lisibles et, sur demande et sous droits, des relations de graphe pour le modèle appelé par le client.
Entrées : query ; options limit, includeGraph, format.
Résultat : Contexte documentaire. Ce contrat est déprécié ; le contrat recommande une migration vers le Context Pack v2.
Exemple métier : Maintenir une intégration RAG existante pendant sa migration.
12. Trouver des documents proches d’un document
GET /api/v1/knowledge/documents/{id}/similar
Utilise un document autorisé comme référence pour retrouver des documents proches par similarité vectorielle.
Entrées : id dans le chemin ; options limit, minScore, includeChunks.
Résultat : Documents proches, scores et passages si demandés.
Exemple métier : Proposer des documents complémentaires à celui que consulte l’utilisateur.
13. Trouver des documents proches d’un texte
POST /api/v1/knowledge/similar
Recherche des documents sémantiquement proches d’un texte fourni sans nécessiter un document de référence déjà enregistré.
Entrées : content ; paramètres facultatifs dans options.
Résultat : Documents proches du contenu soumis, dans le workspace actif.
Exemple métier : Retrouver les procédures correspondant à la description d’un incident.
14. Retrouver les documents liés à une entité
GET /api/v1/knowledge/entities/{entityId}/documents
Lit les documents rattachés à une entité de l’ontologie. Peut élargir la sélection aux entités reliées.
Entrées : entityId dans le chemin ; options includeLinked, linkTypes, limit.
Résultat : Documents liés accessibles à l’appelant.
Exemple métier : Afficher les pièces documentaires rattachées à une entité métier.
15. Rechercher des entités avec leurs documents
POST /api/v1/knowledge/entities/search
Recherche lexicalement des entités puis enrichit les correspondances avec le nombre et un aperçu de leurs documents liés.
Entrées : query ; options entityTypes, includeLinkedEntities, limit.
Résultat : Entités correspondantes accompagnées de leurs informations documentaires.
Exemple métier : Naviguer d’un terme métier vers les entités et les pièces qui les documentent.
Instances et dossiers métier
16. Rechercher les instances d’un type métier
POST /api/v1/object-types/{id}/instances/search
Recherche déterministe sur l’identifiant externe, le titre et les propriétés scalaires autorisées d’instances actives. Les correspondances exactes et les préfixes passent avant les correspondances partielles.
Entrées : id du type dans le chemin ; query, options filters, sort, page, limit.
Résultat : Instances paginées avec leurs données lisibles et gouvernées.
Exemple métier : Retrouver une commande par numéro ou un client par nom.
17. Construire le dossier de faits d’une instance
POST /api/v1/instances/{id}/context
Assemble les champs explicitement demandés d’une instance canonique. Peut ajouter ses relations directes, des faits de voisins sélectionnés et des citations issues des collections documentaires associées.
Entrées : id dans le chemin ; population, fields ; options relations, documents avec une requête explicite.
Résultat : Faits typés, références, couverture et pièces citables. Les champs sont sélectionnés explicitement ; aucune synthèse LLM n’est produite automatiquement.
Exemple métier : Préparer les faits et pièces qu’un assistant pourra utiliser pour répondre sur un dossier client.
18. Lire les relations directes d’une instance
GET /api/v1/instances/{id}/edges
Retourne une page de liens métier actifs autorisés attachés à une instance.
Entrées : id dans le chemin ; options direction, linkTypeId, limit, offset.
Résultat : Relations, propriétés de liens lisibles, total et couverture de la population filtrée.
Exemple métier : Lister les relations entre une commande et ses objets associés.
19. Explorer le voisinage métier d’une instance
GET /api/v1/instances/{id}/neighborhood
Parcourt plusieurs niveaux du graphe d’instances, selon des bornes explicites de profondeur, de nœuds et de relations.
Entrées : id dans le chemin ; options maxDepth, direction, linkTypeId, maxNodes, maxEdges.
Résultat : Instances et liens autorisés, propriétés lisibles et indication de troncature.
Exemple métier : Explorer les objets reliés à un incident sur deux niveaux de relations.
Exploration du graphe
Ces API explorent les nœuds du graphe du workspace. Les relations entre instances disposent des contrats dédiés de la section précédente.
20. Voir les voisins d’un nœud de graphe
GET /api/v1/graph/neighbors/{entityId}
Lit le voisinage d’un nœud du graphe du workspace, avec filtres de direction, de relation et de type de voisin.
Entrées : entityId dans le chemin ; options direction, depth, relationTypes, types, limit.
Résultat : Nœuds voisins et relations dans le périmètre autorisé.
Exemple métier : Afficher les connexions d’un nœud sélectionné dans une vue graphe.
21. Parcourir le graphe depuis un point de départ
POST /api/v1/graph/traverse
Explore un graphe depuis un nœud, jusqu’à la profondeur et aux limites demandées.
Entrées : startNodeId ; options maxDepth, direction, edgeTypes, maxResults, timeoutSeconds.
Résultat : Nœuds, relations, chemins et diagnostics du parcours borné.
Exemple métier : Explorer les dépendances accessibles à partir d’un élément du graphe.
22. Trouver un chemin entre deux nœuds
POST /api/v1/graph/paths
Recherche le plus court chemin entre deux nœuds dans un nombre maximal de sauts.
Entrées : sourceId, targetId ; options maxHops, edgeTypes, timeoutSeconds.
Résultat : Chemin composé de nœuds et de relations, dans les bornes du parcours.
Exemple métier : Montrer par quelles relations deux éléments métier sont connectés.
23. Étendre une recherche sémantique au graphe
POST /api/v1/graph/expand
Sélectionne des nœuds d’ancrage par proximité sémantique avec la requête, puis explore leur voisinage.
Entrées : query ; options topK, maxDepth, maxResults, entityTypes, direction, edgeTypes, minAnchorScore.
Résultat : Ancrages sémantiques et sous-graphe autorisé issu de l’expansion.
Exemple métier : Passer d’une question en langage naturel aux concepts proches et à leurs connexions.
24. Explorer un rayon d’impact dans le graphe
POST /api/v1/graph/impact
Explore les relations amont ou aval d’un nœud pour décrire un périmètre d’impact borné.
Entrées : startNodeId ; options maxDepth, maxResults, edgeTypes, direction, timeoutSeconds.
Résultat : Nœuds et relations atteints, avec les limites et diagnostics de couverture.
Exemple métier : Inspecter les éléments reliés en aval d’un nœud avant une analyse de changement.
25. Rechercher dans un voisinage de graphe
POST /api/v1/graph/constrained-search
Construit le voisinage borné d’un nœud, limite la recherche vectorielle à ce périmètre puis reclasse les correspondances.
Entrées : startNodeId, query ; options scopeDepth, scopeLimit, topK, entityTypes, edgeTypes, direction.
Résultat : Entités pertinentes à l’intérieur du voisinage autorisé.
Exemple métier : Chercher un concept lié aux paiements uniquement dans le voisinage d’un processus donné.
Analyse des populations et des modèles
26. Comparer deux populations d’instances
POST /api/v1/object-types/{id}/instances/compare
Calcule les mêmes métriques sur deux populations filtrées d’un même ObjectType, dans une lecture cohérente.
Entrées : id du type ; population, leftFilters, rightFilters, metrics.
Résultat : Mesures comparables et effectifs exacts des instances canoniques autorisées. Aucune conclusion causale n’est inférée.
Exemple métier : Comparer les indicateurs de deux groupes d’instances sélectionnés par filtres.
27. Mesurer la complétude des instances
POST /api/v1/object-types/{id}/instances/profile
Compte les valeurs présentes, absentes et invalides des champs demandés sur l’ensemble d’une population canonique autorisée.
Entrées : id du type ; population, fields ; option filters.
Résultat : Profil de complétude avec dénominateur exact ; la mesure ne se limite pas à une page de résultats.
Exemple métier : Identifier les champs les moins renseignés avant une opération de qualité des données.
28. Consulter l’impact connu d’un type ontologique
POST /api/v1/ontology/impact
Compose les relations directes du schéma courant et, sur demande et sous droits, les consommateurs enregistrés d’un ObjectType ou LinkType.
Entrées : elementType, elementId ; options maxResults, includeRegisteredConsumers.
Résultat : Structure et consommateurs avec des couvertures séparées. L’accès aux consommateurs nécessite settings.admin.
Exemple métier : Consulter les usages enregistrés d’un type avant de préparer une évolution de modèle.
29. Valider une proposition de modèle
POST /api/v1/ontology/models/validate
Recompile une proposition ontologique identifiée et vérifie ses règles avec le compilateur canonique.
Entrées : proposalId.
Résultat : Règles satisfaites, violées ou nécessitant une revue humaine. L’appel ne publie ni ne modifie le modèle.
Exemple métier : Contrôler une proposition avant sa revue et sa publication.
30. Comparer deux versions immuables d’un modèle
POST /api/v1/ontology/models/diff
Compare deux releases de la même ligne ontologique et du même workspace à partir de leurs empreintes exactes.
Entrées : fromReleaseDigest, toReleaseDigest.
Résultat : Ressources ajoutées, supprimées ou modifiées et champs changés. Le signal potentiallyBreaking demande une analyse de compatibilité.
Exemple métier : Préparer la revue des changements entre deux versions d’un modèle.
Exemples d’appels
Utilisez l’URL de votre API, une clé active et l’UUID du workspace. Les scopes de la clé et les permissions actuelles de l’appelant s’appliquent conjointement. Ces requêtes illustrent les contrats ; elles n’ont pas été exécutées sur un workspace réel.
export API_URL="https://api.ontologie-growthsystemes.com"
export API_KEY="df_..."
export WORKSPACE_ID="UUID_DU_WORKSPACE"
1. Découvrir les capacités
curl "$API_URL/api/v1/retrieval/capabilities" \
-H "X-API-Key: $API_KEY" \
-H "x-workspace-id: $WORKSPACE_ID"
2. Rechercher une définition par mots
curl --get "$API_URL/api/v1/search" \
-H "X-API-Key: $API_KEY" \
-H "x-workspace-id: $WORKSPACE_ID" \
--data-urlencode "q=client" \
--data-urlencode "types=ObjectType,LinkType" \
--data-urlencode "mode=lexical" \
--data-urlencode "limit=10"
3. Rechercher des documents par composition
curl "$API_URL/api/v1/retrieval/search" \
-H "X-API-Key: $API_KEY" \
-H "x-workspace-id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
--data '{"query":"procédure de paiement","surfaces":["documents"],"modes":{"documents":"lexical"},"limit":5,"includeContext":true}'
Limites
- Accès : les résultats, champs, documents et relations dépendent des permissions du workspace et des scopes de la clé. Une requête sur plusieurs surfaces exige les scopes de chacune des surfaces sélectionnées.
- Couverture : recherches bornées, voisinages et chemins peuvent être tronqués. Consultez les diagnostics de couverture, de résultat partiel, de repli et de troncature avant d’interpréter une réponse vide.
- Scores : les scores lexicaux, vectoriels, de recommandation et de structure mesurent des choses différentes. Ils ne constituent pas une probabilité de confiance ni une preuve de compatibilité entre modèles.
- Contexte : ces API retrouvent des faits et des sources. Une recherche n’exécute pas une action ou un workflow trouvé. L’assemblage d’un contexte ne génère pas à lui seul une réponse de modèle.
- Compatibilité RAG :
rag/contextest dépréciée.graphBoost, le contexte graphe facultatif et le mode documentairehybrid_graphont des contrats distincts ; vérifiez le mode exécuté et les éléments retournés.
