---
title: "Return the tenant's knowledge graph."
method: GET
path: "/v1/graph"
tags: ["graph"]
---

# Return the tenant's knowledge graph.

`GET /v1/graph`

## Request

- Base URL: `https://api.andish.ru` (the document declares no server; this is the origin it was published from)
- URL: `https://api.andish.ru/v1/graph`
- Auth: none declared

Return entity nodes and relationship edges for the current tenant's workspace.  Shape is compatible with react-force-graph-2d ``graphData`` prop.

**List mode** (no ``root``): returns the top-N most-connected nodes ordered by degree DESC, node_id ASC.  Paginate with ``limit`` and ``cursor``.

**Focus mode** (``root`` set): BFS traversal from the given node label up to ``depth`` hops (1–3, default 2).  Returns at most ``limit`` nodes ordered by degree DESC.  Cursor pagination does not apply in focus mode (BFS result is bounded by max_nodes, not paginated).

**Pagination (list mode):** use ``limit`` (default 200, max 1000) and ``cursor`` (opaque string — forward the ``X-Next-Cursor`` header).
When a next page exists the response header ``X-Next-Cursor`` is set and ``metadata.truncated`` is ``true``.

**RLS:** only entities belonging to the authenticated workspace are returned.  Empty workspace → empty lists, never stub data.

**Metadata semantics (list mode):** ``metadata.total_nodes`` is the workspace-wide count; ``metadata.truncated`` is True when any cap was applied (page cap OR workspace-exceeds-limit).

**Metadata semantics (focus mode):** ``metadata.total_nodes`` is the workspace-wide count; ``metadata.truncated`` is True when the BFS result exceeded ``limit`` nodes.

## Query parameters

- `limit` integer: Maximum number of nodes per page (list mode) or max BFS nodes (focus mode). Default 200, max 1000.
- `cursor` string, nullable: Opaque pagination cursor (list mode only). Pass the value of the ``X-Next-Cursor`` response header to fetch the next page. Ignored when ``root`` is set.
- `root` string, nullable: Focus-mode root node label. When set, the endpoint performs a BFS traversal from this node instead of the list-mode top-N query. Non-existent root → empty graph (not 404). Cross-tenant root → empty graph (RLS isolation).
- `depth` integer: BFS depth in focus mode (1–3). Ignored when ``root`` is not set. Default 2.

## Response `200`

Successful Response

- GraphResponse: 200 response for GET /v1/graph. Compatible with react-force-graph-2d ``graphData`` prop shape: { nodes: Node[], links: Link[] } The frontend adapts ``edges`` → ``links`` in the component layer.
  - `nodes` GraphNode[], required: Entity nodes in the workspace graph.
    - `id` string, required: Stable entity identifier (UUID or opaque string).
    - `label` string, required: Human-readable entity name.
    - `type` string, required: Entity sub-type. One of: Person, Organization, Concept, Method, Artifact, Location, Creature, Other. Frontend maps each value to a distinct node colour.
    - `weight` number, required: Degree centrality weight (≥ 0). Proportional to the number of incident edges. Used by react-force-graph-2d to size nodes.
  - `edges` GraphEdge[], required: Directed relationships between nodes.
    - `source` string, required: Source node id (must match a GraphNode.id).
    - `target` string, required: Target node id (must match a GraphNode.id).
    - `type` string, required: Relationship label (e.g. 'uses', 'reports_to').
    - `weight` number, required: Relationship strength in [0, 1]. Drives edge opacity / dash pattern.
  - `metadata` GraphMetadata, required: Lightweight metadata returned alongside graph data. ``total_nodes`` -- total entity count in workspace (may exceed ``nodes`` length when the server applies a top-N cap per PRD F17). ``total_edges`` -- total edge count in workspace. ``truncated`` -- True when top-N cap was applied (PRD F17: top-500 by degree centrality when N > 500).
    - `total_nodes` integer, required: Total entity count in workspace.
    - `total_edges` integer, required: Total edge count in workspace.
    - `truncated` boolean: True when the returned graph is a subset of the workspace graph (top-500 by degree centrality, per PRD F17 acceptance criteria).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/andish/apis/mnemo-api.md) · [All operations](https://skmtc.dev/andish/apis/mnemo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/andish/apis/mnemo-api/revisions/d5449f23414c?raw)