Aller au contenu

Référence

API de recherche

Découvrez les 30 opérations de recherche : rôle, entrées, résultats, exemples métier.

14 min

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é

BesoinAPI à privilégier
Rechercher sur plusieurs surfaces métierretrieval/search, avec capabilities et explain
Retrouver une définition métiersearch, ontology/search, search/global
Recommander ou comparer des définitionsretrieval/recommend, ontology/structure/similar
Retrouver des pièces documentairesdocumentation/search, similarité documentaire et liens entité–documents
Retrouver un objet opérationnel et son contexteRecherche d’instances, contexte, relations et voisinage
Explorer les relationsVoisins, parcours, chemins, expansion, impact et recherche contrainte du graphe
Compter des distributions exactesretrieval/facets
Examiner la complétude des données ou une évolution de modèleComparaison et profil d’instances, impact, validation et comparaison de modèles

Éléments et contrats

Surfaces et modes de recherche

SurfaceContenu
processesDéfinitions métier (ObjectTypes et LinkTypes), actions et workflows, selon l’API choisie
recordsInstances canoniques et enregistrements connectés autorisés, selon le lecteur
documentsContenu 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.

ModeRôle
deterministicRetrouver des identifiants, champs lisibles et filtres selon des règles définies
lexicalRetrouver des ressources par leurs mots et correspondances textuelles
semanticRetrouver des ressources par leur sens grâce à la similarité vectorielle
hybridCombiner recherche lexicale et sémantique
hybrid_graphEnrichir une recherche documentaire par des éléments de graphe autorisés, lorsque la surface le prend en charge
autoLaisser 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éeModes déclarésScopes requis pour la composition
processesauto, deterministic, lexical, semantic, hybridnodes.read, actions.read, workflow.read
recordsauto, deterministicnodes.read, livedata.read ; pipelines.read en plus si un dataset est sélectionné
documentsauto, lexical, semantic, hybrid, hybrid_graphknowledge.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/context est dépréciée. graphBoost, le contexte graphe facultatif et le mode documentaire hybrid_graph ont des contrats distincts ; vérifiez le mode exécuté et les éléments retournés.

Liens vers les tâches

Cette page vous a-t-elle permis d’atteindre votre objectif ?