> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/instance-api/semantic-graph.md).

# Semantic Graph

The Semantic Graph endpoints expose the **Neural Semantic Graph** built from indexed documents: nodes, relationships, and exploration primitives. Each semantic node is a triple of `(node_1, node_2, edge)` — an entity-relationship-entity extracted from indexed content.

Authenticated with `instance-id` + `api-key` headers — see [Instance API keys](/knowledge-ai/authentication/api-keys.md).

***

## POST /api/semantic-graph/identify-nodes

Identify all semantic nodes relevant to a natural-language query. The system translates the query, embeds it, finds approximate related nodes by semantic similarity, then selects the most relevant documents.

If `need_documents` is `true`, partial document content from the matching chunks is included in `documents_contents`. If `false`, `documents_contents` is an empty array and document IDs are available within each semantic node's `documents` field.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/semantic-graph/identify-nodes" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST https://api.kai-studio.ai/api/semantic-graph/identify-nodes \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the safety requirements?", "need_documents": true}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/semantic-graph/identify-nodes",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"query": "What are the safety requirements?", "need_documents": True},
)
response.raise_for_status()
payload = response.json()["response"]
for node in payload["semantic_nodes"]:
    print(node["node_1"], "->", node["edge"], "->", node["node_2"])
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api.kai-studio.ai/api/semantic-graph/identify-nodes",
  {
    method: "POST",
    headers: {
      "instance-id": "<YOUR_INSTANCE_ID>",
      "api-key": "<YOUR_API_KEY>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "What are the safety requirements?",
      need_documents: true,
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

***

## POST /api/semantic-graph/nodes

List all semantic nodes in the instance with pagination. Each node carries `id`, `node_1`, `node_2`, `edge`, and an `extraproperties` object listing the contributing `documents`, `chunks`, and occurrence `count`.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/semantic-graph/nodes" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST https://api.kai-studio.ai/api/semantic-graph/nodes \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"offset": 0, "limit": 50}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/semantic-graph/nodes",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"offset": 0, "limit": 50},
)
response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api.kai-studio.ai/api/semantic-graph/nodes",
  {
    method: "POST",
    headers: {
      "instance-id": "<YOUR_INSTANCE_ID>",
      "api-key": "<YOUR_API_KEY>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ offset: 0, limit: 50 }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

***

## POST /api/semantic-graph/nodes-by-label

List semantic nodes where either `node_1` or `node_2` matches the given label. The label must not be empty; an empty label returns a 403 error.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/semantic-graph/nodes-by-label" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

***

## POST /api/semantic-graph/linked-nodes-by-id

Find semantic nodes that share entity labels with the `node_1` or `node_2` of a given semantic node. This enables graph exploration by following connections from a known node. The given node itself is excluded from the results.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/semantic-graph/linked-nodes-by-id" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}