Skip to content

Reference

Search APIs

Explore 30 search operations: purpose, inputs, results, business examples.

12 min

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

NeedAPIs to consider
Search several business surfacesretrieval/search, with capabilities and explain
Search business definitionssearch, ontology/search, search/global
Recommend or compare definitionsretrieval/recommend, ontology/structure/similar
Retrieve documentary evidencedocumentation/search, knowledge similarity and entity-document APIs
Find an operational object and its contextInstance search, context, edges and neighborhood APIs
Explore relationshipsGraph neighbors, traversal, paths, expansion, impact and constrained search
Count exact distributionsretrieval/facets
Review data completeness or model changesInstance comparison and profiling, impact, model validation and model comparison

Elements and contracts

Search surfaces and modes

SurfaceContent
processesBusiness definitions (ObjectTypes and LinkTypes), actions and workflows, according to the selected API
recordsCanonical instances and authorized connected records, according to the reader
documentsDocument-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.

ModePurpose
deterministicMatch identifiers, readable fields and filters with defined rules
lexicalRetrieve resources through words and text matches
semanticRetrieve resources by meaning using vector similarity
hybridCombine lexical and semantic retrieval
hybrid_graphEnrich document retrieval through authorized graph evidence when the surface supports it
autoLet 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 surfaceDeclared modesScopes required for composition
processesauto, deterministic, lexical, semantic, hybridnodes.read, actions.read, workflow.read
recordsauto, deterministicnodes.read, livedata.read; additionally pipelines.read when selecting a dataset
documentsauto, lexical, semantic, hybrid, hybrid_graphknowledge.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”.

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/context is deprecated. graphBoost, optional graph context and document hybrid_graph have different contracts; inspect the executed mode and evidence.

Did this page help you achieve your goal?