---
title: "Resolve a concept name to a knowledge graph node"
method: POST
path: "/knowledgeGraph/nodes/resolve"
tags: ["KnowledgeGraph"]
---

# Resolve a concept name to a knowledge graph node

`POST /knowledgeGraph/nodes/resolve`

Name-based resolution of a concept name to a knowledge graph node: (1) exact lowercased name + label match, (2) substring match via SEARCH_SUBSTRING on name_substring_tokens. Returns null when neither produces a match. The two are NOT equivalent: an exact match is a deterministic identity, while a substring match is a lexical name-overlap SIGNAL (match_kind name_substring) that the caller surfaces to its agent as a candidate to weigh, not an identity verdict. Semantic similarity is not performed here; use the similarityNeighbors endpoint for embedding-based neighborhood lookup. Writer-only endpoint (AMA uses this; not for general-purpose search). concept_type is restricted to Page, Workflow, Feature (AMA's writable concept labels).

## Request body

- ResolveKnowledgeGraphNodeRequest — Request body for resolving a concept name to a knowledge graph node. Restricted to AMA writer-only 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 resolve against (writer-only labels only)
  - `candidate_name` string, required — The candidate name to resolve

## Response `200`

A node matched by exact name+label (a deterministic identity) or by name substring (a lexical name-overlap signal for the caller's agent to weigh).

- ResolveKnowledgeGraphNodeResponse — Resolution result returned with HTTP 200 when a node was matched by exact name or name substring. When no match is found, the endpoint returns HTTP 204 No Content with no body — callers should treat 204 as "no name match". All listed properties are required when this body is returned. match_kind distinguishes the two: exact is a deterministic identity; name_substring is a lexical name-overlap signal the caller weighs, not an identity verdict.
  - `node_id` string, required — The resolved node ID
  - `match_kind` 'exact' | 'name_substring', required — How the node's name relates to the candidate: exact (case-insensitive name equality — a deterministic identity) or name_substring (the candidate name is a substring of the node's name — a lexical overlap signal, not an identity verdict).
  - `confidence` number, double, required — Fixed per match_kind (exact = 1.0, name_substring = 0.95). Retained for backward compatibility; it carries no information beyond match_kind and callers should key on match_kind instead.

## Other responses

- `204` — No node matched either resolution tier. Generated clients should treat this as a "no match" outcome (no response body).
- `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)