Nodes

Search nodes

GET /api/v1/nodes

Search the knowledge graph with keyword, semantic, or hybrid search.

Query parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | — | Search query (max 500 chars) | | mode | string | hybrid | Search mode: keyword, semantic, or hybrid | | para_item_id | string | — | Filter by PARA item | | status | string | — | Filter: raw, validated, or dismissed | | orphan | boolean | — | If true, return only unassigned nodes | | page | number | 1 | Page number | | per_page | number | 20 | Results per page (max 100) |

Response

{
  "data": [
    {
      "id": "abc123",
      "title": "Node title",
      "summary": "Brief summary",
      "body_markdown": "Full content...",
      "tags": ["tag1"],
      "para_item_ids": ["para_id"],
      "status": "validated",
      "match_provenance": { "keyword": true, "semantic": true, "score": 0.0325 },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 50,
  "total_matches": 636,
  "coverage_capped": true,
  "page": 1,
  "per_page": 20
}

• total — number of results in the served set (for pagination)
• total_matches — honest lexical match count (≥N match by keyword). Present for hybrid/keyword searches.
• coverage_capped — true when matches exceed the candidate pool, indicating recall is limited
• match_provenance — per-result provenance showing which index(es) matched. Present on hybrid search results.

---

Get node

GET /api/v1/nodes/:id

Returns a single node by ID.

---

Create node

POST /api/v1/nodes
Content-Type: application/json

Request body

{
  "title": "Node title",
  "content": "Markdown body content",
  "summary": "Brief summary",
  "tags": ["tag1", "tag2"],
  "para_item_ids": ["para_id"]
}

Returns 201 with the created node.

---

Update node

PATCH /api/v1/nodes/:id
Content-Type: application/json

Accepts partial updates to title, content, summary, tags, and status.

---

Delete node

DELETE /api/v1/nodes/:id

Returns 204 on success. Removes the node and its link associations.