---
title: "Find nearest-neighbor concepts to a candidate"
method: POST
path: "/knowledgeGraph/nodes/similarityNeighbors"
tags: ["KnowledgeGraph"]
---

# Find nearest-neighbor concepts to a candidate

`POST /knowledgeGraph/nodes/similarityNeighbors`

Returns the top-K active concept nodes most similar to a candidate concept by symmetric cosine similarity over the node embedding column. The App Modeling Agent uses this to see the nearest existing concepts when resolving a candidate, and judges whether the candidate is the same concept, a variant, or genuinely new. No score threshold is applied — every returned neighbor is ranked, none filtered out.
The candidate is embedded server-side using the same symmetric document format as the stored embeddings (`title: <label>: <candidate_name> | text: <candidate_text>`) with `RETRIEVAL_DOCUMENT` task type, so candidate-vs-stored cosine distance is meaningful. When `candidate_text` is omitted, the candidate name alone is used as the embedding text.
Writer-only endpoint (consumes embedding API quota); `concept_type` is restricted to the agent's writable labels (Page, Workflow, Feature). Returns 503 when the embedding service is unavailable, so the caller treats it as a transient failure rather than reading an empty neighborhood as "this candidate is unique".

## Request body

- SimilarityNeighborsKnowledgeGraphNodesRequest — Request body for the App Modeling Agent's concept-neighborhood lookup. Restricted to the agent's writer concept labels (Page, Workflow, Feature).
  - `workspace_id` string, required — The workspace ID
  - `application_id` string, required — The application ID
  - `concept_type` 'Page' | 'Workflow' | 'Feature', required — The concept type to look up neighbors against (writer-only labels only)
  - `candidate_name` string, required — The candidate concept name; used both as the title prefix and as the embedding text fallback when candidate_text is absent
  - `candidate_text` string — Optional candidate prose to embed (mirrors the stored concept's `content` column). When supplied, the embedding input is `title: <concept_type>: <candidate_name> | text: <candidate_text>`. When absent, the candidate name alone is reused as the embedding text. Capped at 20000 characters to mirror the concept-content cap.
  - `limit` integer — Maximum number of neighbors to return (a result-count cap, not a similarity cutoff). Defaults to a small set the agent can inspect; the cap of 50 keeps responses within the agent context budget.

## Response `200`

Top-K similar nodes (may be empty when no concepts of the given label exist).

- SimilarityNeighborsKnowledgeGraphNodesResponse — Response from the App Modeling Agent's concept-neighborhood lookup
  - `neighbors` KnowledgeGraphSimilarityNeighbor[], required — Ranked neighbors ordered by similarity descending (closest first). Empty when no active concepts of the requested label exist in the workspace.
    - `node_id` string, required — Unique identifier of the neighbor node
    - `label` 'Page' | 'Workflow' | 'Feature' | 'KnowledgeDoc' | 'Pattern', required — Label for a knowledge graph node indicating its concept type
    - `name` string, required — The neighbor concept's name
    - `summary` string — The neighbor concept's short summary (may be absent)
    - `similarity` number, double, required — Cosine similarity in [0.0, 1.0]; equals 1.0 - cosine_distance

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Entity not found
- `503` — Unknown error
- `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)