Ontologie searches across business definitions, operational data and documents. These APIs let applications and assistants find resources, assemble supporting facts, explore relationships and inspect retrieval behavior.
This reference presents 30 search operations, grouped by capability, with inputs, results and business examples.
Choose an API by capability
| Need | APIs to consider |
|---|---|
| Search several business surfaces | retrieval/search, with capabilities and explain |
| Search business definitions | search, ontology/search, search/global |
| Recommend or compare definitions | retrieval/recommend, ontology/structure/similar |
| Retrieve documentary evidence | documentation/search, knowledge similarity and entity-document APIs |
| Find an operational object and its context | Instance search, context, edges and neighborhood APIs |
| Explore relationships | Graph neighbors, traversal, paths, expansion, impact and constrained search |
| Count exact distributions | retrieval/facets |
| Review data completeness or model changes | Instance comparison and profiling, impact, model validation and model comparison |
Elements and contracts
Search surfaces and modes
| Surface | Content |
|---|---|
processes | Business definitions (ObjectTypes and LinkTypes), actions and workflows, according to the selected API |
records | Canonical instances and authorized connected records, according to the reader |
documents | Document-library content and citable passages; images when supported |
An ObjectType defines a business object type, such as a customer or order. An instance is an individual object of that type. A LinkType defines a business relation.
| Mode | Purpose |
|---|---|
deterministic | Match identifiers, readable fields and filters with defined rules |
lexical | Retrieve resources through words and text matches |
semantic | Retrieve resources by meaning using vector similarity |
hybrid | Combine lexical and semantic retrieval |
hybrid_graph | Enrich document retrieval through authorized graph evidence when the surface supports it |
auto | Let the orchestration select an available strategy |
Supported modes vary by API and surface. Inspect retrieval/capabilities and the executed mode. In particular, records do not gain semantic search just because another surface supports it.
Composed retrieval declares the following combinations:
| Requested surface | Declared modes | Scopes required for composition |
|---|---|---|
processes | auto, deterministic, lexical, semantic, hybrid | nodes.read, actions.read, workflow.read |
records | auto, deterministic | nodes.read, livedata.read; additionally pipelines.read when selecting a dataset |
documents | auto, lexical, semantic, hybrid, hybrid_graph | knowledge.read; graph evidence also requires related permissions |
Other APIs have their own contracts: graph_traversal identifies graph traversal in the catalog and rag_context identifies RAG context assembly. These labels are not values of the composition request’s modes parameter.
Composition and result inspection
1. Discover available capabilities
GET /api/v1/retrieval/capabilities
Lists search surfaces, modes, limits and required scopes so a client can select the capabilities declared by its workspace.
Inputs: No request body.
Result: Declared capabilities and availability reasons; the response does not probe index health.
Example: Adapt an application’s search selector to available modes.
2. Search across business surfaces
POST /api/v1/retrieval/search
Combines searches over processes, records and documents. Each surface retains its results, provenance and executed mode. Can also build cited context.
Inputs: query, surfaces, modes; optional filters, limit, includeContext, contextBudget.
Result: Results grouped by surface, citations and execution diagnostics; a response may be explicitly partial.
Example: Find accessible data, procedures and definitions around the term “customer”.
3. Explain an executed search
POST /api/v1/retrieval/explain
Runs the same search as retrieval/search and reports requested and executed modes, fallbacks, coverage and counts.
Inputs: Same body as retrieval/search.
Result: Provenance and statistics without query text, titles, excerpts or context content. The call performs an actual search.
Example: Explain why a search used lexical retrieval instead of semantic retrieval.
4. Count and filter a population
POST /api/v1/retrieval/facets
Computes exact distributions over one explicitly selected population: canonical instances, current Live Data records, a published dataset, current documents or the process catalog.
Inputs: surface, population, facets; population-specific target (objectTypeId or targetId), filters and maxValues.
Result: Values, counts and separate missing or invalid counts. Totals describe the authorized population with no implicit cross-source sum.
Example: Show documents by language or instances by status.
Definitions and business navigation
5. Search definitions by words or meaning
GET /api/v1/search
Searches readable ObjectTypes and LinkTypes using deterministic, lexical, semantic or hybrid retrieval, with optional reranking, diversification and score explanations.
Inputs: q; optional types, mode, limit, espace_id, rerank, graphBoost, explain, mmr.
Result: Ranked definitions, scores and executed strategy. graphBoost uses connectivity as a ranking signal.
Example: Find the “supplier” business type from a related natural-language phrase.
6. Navigate workspace resources
GET /api/v1/search/global
Federates lexical navigation across accessible definitions, instances, workflows, actions and saved views.
Inputs: q; optional types, objectTypeId, limit.
Result: Results grouped by resource type for navigation.
Example: Power a global search bar with resources related to “contract”.
7. Search ontology metadata
GET /api/v1/ontology/search
Performs paginated lexical search over the names, aliases, descriptions and properties of active ObjectTypes and LinkTypes.
Inputs: q; optional types, includeProperties, espaceId, limit, offset.
Result: Matching definitions, match locations and properties when requested.
Example: Offer autocomplete when selecting a type in a form.
8. Recommend definitions from examples
POST /api/v1/retrieval/recommend
Ranks definitions from positive and optional negative examples. Lexical or semantic mode is selected explicitly; the examples are excluded from suggestions.
Inputs: population: "current_definitions", mode, positiveIds; optional negativeIds, types, limit.
Result: Recommended definitions and similarity scores. A score is not a probability.
Example: Explore definitions similar to types a user already considers relevant.
9. Compare object type structures
POST /api/v1/ontology/structure/similar
Compares declared properties or relation shapes of active object types using named properties, property shapes or relation shapes.
Inputs: population, objectTypeId, comparison; optional limit, minScore.
Result: Similar types, scores and explainable comparison evidence. Property and relation scores remain separate.
Example: Identify structurally similar models before considering harmonization.
Documents and RAG context
10. Search the document library
POST /api/documentation/search
Provides specialized document-library search with retrieval modes and document filters. Image modality uses the workspace’s visual index when available.
Inputs: query; optional retrievalMode, modality, espaceId, tags, fileTypes, category, limit, includeImages.
Result: Relevant passages or images, citations and diagnostics. includeImages enriches text results; modality: "image" selects visual retrieval.
Example: Find a contract clause or a relevant visual page in accessible documents.
11. Build RAG context (compatibility)
POST /api/v1/rag/context
Builds readable document sources and, when requested and authorized, bounded graph relationships for the model called by the client.
Inputs: query; optional limit, includeGraph, format.
Result: Document context. This contract is deprecated; the contract recommends migration to Context Pack v2.
Example: Maintain an existing RAG integration during migration.
12. Find documents similar to a document
GET /api/v1/knowledge/documents/{id}/similar
Uses an authorized reference document to find similar documents through vector similarity.
Inputs: Path parameter id; optional limit, minScore, includeChunks.
Result: Similar documents, scores and optional passages.
Example: Suggest additional documents related to the document a user is reading.
13. Find documents similar to supplied text
POST /api/v1/knowledge/similar
Finds documents semantically similar to supplied text without requiring an existing reference document.
Inputs: content; optional parameters in options.
Result: Documents similar to the submitted content within the active workspace.
Example: Find procedures related to an incident description.
14. Find documents linked to an entity
GET /api/v1/knowledge/entities/{entityId}/documents
Reads documents linked to an ontology entity and can extend the selection to related entities.
Inputs: Path parameter entityId; optional includeLinked, linkTypes, limit.
Result: Linked documents readable by the caller.
Example: Display supporting documents linked to a business entity.
15. Search entities with their documents
POST /api/v1/knowledge/entities/search
Searches entities lexically and enriches matches with linked document counts and previews.
Inputs: query; optional entityTypes, includeLinkedEntities, limit.
Result: Matching entities with related document information.
Example: Navigate from a business term to matching entities and supporting documents.
Instances and business dossiers
16. Search instances of a business type
POST /api/v1/object-types/{id}/instances/search
Performs deterministic search over external identifiers, display titles and authorized scalar properties of active instances. Exact and prefix matches rank before partial matches.
Inputs: Type identifier id in the path; query, optional filters, sort, page, limit.
Result: Paginated instances with governed readable data.
Example: Find an order by number or a customer by name.
17. Build a factual instance dossier
POST /api/v1/instances/{id}/context
Collects explicitly requested fields of a canonical instance, with optional direct relations, selected neighbor facts and citations from associated document collections.
Inputs: Path parameter id; population, fields; optional relations, documents with an explicit query.
Result: Typed facts, references, coverage and citable sources. Fields are explicitly selected; no LLM summary is generated automatically.
Example: Prepare facts and sources an assistant can use to answer questions about a customer dossier.
18. Read direct instance relations
GET /api/v1/instances/{id}/edges
Returns one bounded page of authorized active business edges connected to an instance.
Inputs: Path parameter id; optional direction, linkTypeId, limit, offset.
Result: Edges, readable governed edge properties, total and filtered-population coverage.
Example: List relations between an order and associated objects.
19. Explore an instance’s business neighborhood
GET /api/v1/instances/{id}/neighborhood
Traverses a bounded instance graph with explicit depth, node and edge limits.
Inputs: Path parameter id; optional maxDepth, direction, linkTypeId, maxNodes, maxEdges.
Result: Authorized instances and edges, readable properties and truncation diagnostics.
Example: Explore objects linked to an incident across two relation levels.
Graph exploration
These APIs explore workspace graph nodes. Instance relations have dedicated contracts in the previous section.
20. Inspect graph-node neighbors
GET /api/v1/graph/neighbors/{entityId}
Reads a workspace graph node’s neighborhood with direction, relation-type and neighbor-type filters.
Inputs: Path parameter entityId; optional direction, depth, relationTypes, types, limit.
Result: Neighbor nodes and relations within the authorized scope.
Example: Display connections of a selected node in a graph view.
21. Traverse the graph from a starting node
POST /api/v1/graph/traverse
Explores the graph from one node within the requested depth and limits.
Inputs: startNodeId; optional maxDepth, direction, edgeTypes, maxResults, timeoutSeconds.
Result: Nodes, edges, paths and bounded traversal diagnostics.
Example: Explore accessible dependencies from a graph element.
22. Find a path between two nodes
POST /api/v1/graph/paths
Finds the shortest path between two nodes within a maximum hop count.
Inputs: sourceId, targetId; optional maxHops, edgeTypes, timeoutSeconds.
Result: A path of nodes and edges within traversal limits.
Example: Show how two business elements are connected through relations.
23. Expand semantic search into the graph
POST /api/v1/graph/expand
Selects semantic anchor nodes matching the query and then explores their graph neighborhood.
Inputs: query; optional topK, maxDepth, maxResults, entityTypes, direction, edgeTypes, minAnchorScore.
Result: Semantic anchors and the authorized expanded subgraph.
Example: Move from a natural-language question to related concepts and their connections.
24. Explore a graph impact radius
POST /api/v1/graph/impact
Traverses upstream or downstream relationships to describe a bounded impact radius.
Inputs: startNodeId; optional maxDepth, maxResults, edgeTypes, direction, timeoutSeconds.
Result: Reached nodes and edges with limits and coverage diagnostics.
Example: Inspect downstream connected elements before analyzing a change.
25. Search within a graph neighborhood
POST /api/v1/graph/constrained-search
Builds a bounded node neighborhood, restricts vector retrieval to that scope and reranks matching entities.
Inputs: startNodeId, query; optional scopeDepth, scopeLimit, topK, entityTypes, edgeTypes, direction.
Result: Relevant entities within the authorized neighborhood.
Example: Search for a payment-related concept only within a selected process’s neighborhood.
Population and model analysis
26. Compare two instance populations
POST /api/v1/object-types/{id}/instances/compare
Computes the same metrics for two filtered populations of one ObjectType in a consistent read.
Inputs: Type identifier id; population, leftFilters, rightFilters, metrics.
Result: Comparable metrics and exact authorized canonical-instance counts. No causal conclusion is inferred.
Example: Compare metrics for two groups of instances selected through filters.
27. Measure instance completeness
POST /api/v1/object-types/{id}/instances/profile
Counts present, missing and invalid values for requested fields across an authorized canonical population.
Inputs: Type identifier id; population, fields; optional filters.
Result: Completeness profile with an exact denominator; measurement is not limited to a result page.
Example: Identify fields with missing values before a data-quality operation.
28. Inspect a type’s known ontology impact
POST /api/v1/ontology/impact
Combines direct current-schema relations and, when requested and authorized, registered consumers of an ObjectType or LinkType.
Inputs: elementType, elementId; optional maxResults, includeRegisteredConsumers.
Result: Structure and consumers with separate coverage. Consumer access requires settings.admin.
Example: Inspect registered uses of a type before preparing a model change.
29. Validate a model proposal
POST /api/v1/ontology/models/validate
Recompiles an identified ontology proposal and checks its rules using the canonical compiler.
Inputs: proposalId.
Result: Satisfied or violated rules and rules requiring human review. The call neither publishes nor modifies the model.
Example: Check a proposal before review and publication.
30. Compare two immutable model releases
POST /api/v1/ontology/models/diff
Compares two releases from the same ontology lineage and workspace using exact digests.
Inputs: fromReleaseDigest, toReleaseDigest.
Result: Added, removed or changed resources and changed fields. The potentiallyBreaking signal calls for compatibility analysis.
Example: Prepare a change review between two model releases.
Calling examples
Use your configured API base URL, an active API key and a workspace UUID. The key’s scopes and the caller’s current permissions both apply. These requests illustrate the contracts; they have not been executed against a live workspace.
export API_URL="https://api.ontologie-growthsystemes.com"
export API_KEY="df_..."
export WORKSPACE_ID="WORKSPACE_UUID"
1. Inspect capabilities
curl "$API_URL/api/v1/retrieval/capabilities" \
-H "X-API-Key: $API_KEY" \
-H "x-workspace-id: $WORKSPACE_ID"
2. Search definitions lexically
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. Search documents with composed retrieval
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}'
Limits
- Access: results, fields, documents and graph relations depend on workspace permissions and API-key scopes. Multi-surface requests require the scopes of all selected surfaces.
- Coverage: bounded retrieval, neighborhoods and paths can be truncated. Read coverage, partial-result, fallback and truncation diagnostics before interpreting an empty result.
- Scores: lexical, vector, recommendation and structural scores measure different things. They are not confidence probabilities or evidence of model compatibility.
- Context: these APIs retrieve facts and sources. Searching does not execute a returned action or workflow. Context assembly does not itself generate a model answer.
- RAG compatibility:
rag/contextis deprecated.graphBoost, optional graph context and documenthybrid_graphhave different contracts; inspect the executed mode and evidence.
