---
title: "Search knowledge graph nodes"
method: POST
path: "/knowledgeGraph/nodes/search"
tags: ["KnowledgeGraph"]
---

# Search knowledge graph nodes

`POST /knowledgeGraph/nodes/search`

Hybrid search across knowledge graph nodes using semantic (vector), fulltext, and substring modes. Supports Reciprocal Rank Fusion (RRF) when multiple input types are provided. At least one of query_text, literal_phrases, or name_substring must be supplied. When mode=auto (default), the server selects the active modes based on which inputs are present; modes_used reflects the actual modes that ran.

## Request body

- SearchKnowledgeGraphNodesRequest — Request body for hybrid knowledge graph node search. At least one of query_text, literal_phrases, or name_substring must be supplied.
  - `workspace_id` string, required — The workspace ID
  - `application_id` string, required — The application ID
  - `query_text` string — Semantic query text for vector similarity search
  - `literal_phrases` string[] — Exact phrase(s) for FULLTEXT search. Phrases are OR-joined — a node matches when any one phrase matches, and ranking rewards nodes that match several.
  - `name_substring` string — Substring match on node name
  - `label_filter` KnowledgeGraphNodeLabel[] — Optional filter to restrict results to specific node labels
  - `mode` 'auto' | 'semantic' | 'fulltext' | 'substring' | 'rrf' — Search mode. auto (default) selects active modes based on provided inputs. Explicit values force a specific mode. modes_used in the response reflects the actual mode(s) that ran.
  - `limit` integer — Maximum number of results to return. Capped at 50 to keep the agent-facing response within a manageable LLM context budget.

## Response `200`

Search results with RRF-fused ranking and per-mode ranks

- SearchKnowledgeGraphNodesResponse — Response from hybrid knowledge graph node search
  - `nodes` KnowledgeGraphSearchResult[], required — Ranked search results
    - `node_id` string — Unique identifier of the matching node
    - `label` 'Page' | 'Workflow' | 'Feature' | 'KnowledgeDoc' | 'Pattern' — Label for a knowledge graph node indicating its concept type
    - `name` string — The name of the concept
    - `summary` string — A short summary of the concept
    - `rrf_score` number, double — Fused RRF score; present when mode=rrf or auto-degraded with multiple branches
    - `semantic_rank` integer — 1-based rank in the semantic branch from the RRF fusion. Absent when semantic mode did not contribute, and absent for single-branch results (when only one mode ran, no fusion occurs and result order is determined by the underlying relevance signal via `ORDER BY` directly — see `modes_used` to detect single-branch responses).
    - `fulltext_rank` integer — 1-based rank in the fulltext branch from the RRF fusion. Absent when fulltext mode did not contribute, and absent for single-branch results (when only one mode ran, no fusion occurs and result order is determined by the underlying relevance signal via `ORDER BY` directly — see `modes_used` to detect single-branch responses).
    - `substring_rank` integer — 1-based rank in the substring branch from the RRF fusion. Absent when substring mode did not contribute, and absent for single-branch results (when only one mode ran, no fusion occurs and result order is determined by the underlying relevance signal via `ORDER BY` directly — see `modes_used` to detect single-branch responses).
    - `snippet` string — Best-effort highlighted excerpt sourced from the node's `summary` when the FULLTEXT branch contributed a match. May be absent when fulltext did not contribute, when no highlightable terms were found, or when the match was on `content` only (the fulltext index does not store `content`, so content-only matches still return the row but cannot be snippeted). Treat as advisory rendering, not as proof of why the row matched.
  - `modes_used` string[], required — The actual search modes that contributed to the results

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Entity not found
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)