Graph

Get seed graph

GET /api/v1/graph/seed

Returns a BFS neighborhood of a seed node up to the requested depth. Used by the dashboard graph view for the initial paint.

If no seed is supplied the tenant’s hub node (highest connection_count, excluding archived nodes) is used automatically.

Query parameters

Parameter	Type	Default	Description
seed	string	—	ID of the seed node. Omit to use the hub node.
depth	1 | 2 | 3	1	BFS depth. Higher values return larger neighborhoods.

Response

{
  "seed_id": "abc123",
  "nodes": [
    {
      "id": "abc123",
      "title": "Node title",
      "para_category": "projects",
      "para_item_id": "para-456",
      "connection_count": 5,
      "depth": 0
    }
  ],
  "edges": [
    {
      "source": "abc123",
      "target": "def456",
      "link_type": "related",
      "weight": 0.9
    }
  ],
  "frontier_ids": ["def456"],
  "meta": {
    "node_count": 12,
    "edge_count": 15,
    "depth": 1
  }
}

seed_id is null and all arrays are empty when the tenant has no nodes.

frontier_ids lists nodes at the deepest BFS hop that have additional unloaded neighbours. The dashboard uses these IDs to display the expansion affordance.

depth in each node is 0 for the seed itself and 1–3 for BFS hops.

Error responses

Status	Condition
400	depth is not 1, 2, or 3
401	Missing or invalid authentication
404	Seed node not found, belongs to another tenant, or is archived
429	Rate limit exceeded

---

Get node neighbors

GET /api/v1/graph/neighbors/:id

Returns the one-hop neighbours of a single node. Intended for on-demand expansion when the user clicks a frontier node in the graph view.

All returned nodes carry newly_added: true so the client can apply a fade-in animation.

When there are more neighbours than limit the response includes a next_cursor value for retrieving the next page.

Path parameters

Parameter	Description
id	ID of the node whose neighbours to return.

Query parameters

Parameter	Type	Default	Description
direction	out | in | both	both	Which link direction to follow.
limit	1–200	50	Maximum number of neighbour nodes to return.
cursor	string	—	Pagination cursor from a previous response.

Cursor contract

Cursors are opaque to clients. Do not parse or construct them. Internally they are base64url-encoded JSON:

• direction=out or direction=in: encodes { dir, weight, source_id, target_id }. Results are ordered by weight DESC, source_id ASC, target_id ASC.
• direction=both: encodes { out?: string, in?: string } — a composite of independent per-direction cursors. Each side pages independently; a side is absent once it is exhausted.

An invalid or expired cursor returns 400. Clients must not carry a cursor across seed changes.

Response

{
  "node_id": "abc123",
  "nodes": [
    {
      "id": "def456",
      "title": "Neighbor node",
      "para_category": null,
      "para_item_id": null,
      "connection_count": 3,
      "newly_added": true
    }
  ],
  "edges": [
    {
      "source": "abc123",
      "target": "def456",
      "link_type": "related",
      "weight": 0.9
    }
  ],
  "next_cursor": null
}

next_cursor is null when there are no further pages.

Error responses

Status	Condition
400	Invalid direction, limit out of range, or invalid cursor
401	Missing or invalid authentication
404	Node not found, belongs to another tenant, or is archived
429	Rate limit exceeded