Skip to main content
Nodes represent the learning graph hierarchy: topics (root), concepts, and subconcepts. They form a directed acyclic graph (DAG) with dependency edges.

​
List Nodes

curl "http://localhost:8000/api/nodes?userId=00000000-0000-0000-0000-000000000000&type=concept&branchId=abc123"
GET /api/nodes List nodes with optional filters.

​
Query Parameters

​
userId
string
Filter by user UUID
​
type
string
Filter by node type: root, concept, or subconcept
​
branchId
string
Filter by branch UUID
​
parentId
string
Filter by parent node UUID

​
Response

​
[]
array
Array of node objects
​
id
string
Node UUID
​
userId
string
Owner UUID
​
type
string
root, concept, or subconcept
​
branchId
string | null
Branch UUID
​
parentId
string | null
Parent node UUID
​
title
string
Node title
​
desc
string | null
Node description
​
accuracyScore
number
Accuracy score (0-1)
​
createdAt
string
ISO 8601 timestamp
​
updatedAt
string
ISO 8601 timestamp

​
Get Node

GET /api/nodes/:id Retrieve a single node by ID.

​
Get Node Children

GET /api/nodes/:id/children Retrieve all direct children of a node.

​
Get Dependency Edges

curl "http://localhost:8000/api/nodes/abc123/dependency-edges?childType=subconcept"
GET /api/nodes/:id/dependency-edges Retrieve dependency edges between direct children of a parent node.

​
Query Parameters

​
childType
string
Filter child nodes by type: concept or subconcept

​
Response

​
[]
array
Array of edge objects
​
id
string
Edge UUID
​
sourceNodeId
string
Prerequisite node UUID
​
targetNodeId
string
Dependent node UUID
​
createdAt
string
ISO 8601 timestamp

​
Create Node

curl -X POST http://localhost:8000/api/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "type": "root",
    "title": "Introduction to Algorithms",
    "desc": "Learn fundamental algorithms and data structures",
    "branchId": "abc123"
  }'
POST /api/nodes Create a new node.

​
Body Parameters

​
userId
string
required
User UUID
​
type
string
required
Node type: root, concept, or subconcept
​
title
string
required
Node title
​
branchId
string
Branch UUID (optional)
​
parentId
string
Parent node UUID (optional)
​
desc
string
Node description (optional)

​
Update Node

PATCH /api/nodes/:id Update a node’s title, description, or accuracy score.

​
Body Parameters

​
title
string
New title
​
desc
string
New description
​
accuracyScore
number
New accuracy score (0-1)

​
Delete Node

DELETE /api/nodes/:id Delete a node. Does not cascade to children. Status: 204 No Content

​
Node Contents

​
Get Contents

GET /api/nodes/:nodeId/contents Retrieve all content versions for a node.

​
Get Active Content

GET /api/nodes/:nodeId/contents/active Retrieve the active content for a node.
​
id
string
Content UUID
​
nodeId
string
Node UUID
​
explanationMd
string
Markdown explanation text
​
visualizationKind
string | null
Visualization type: mermaid, svg, or json
​
visualizationPayload
string | null
Visualization data
​
cards
string | null
JSON array of learning cards: [{ id, index, explanation, question, questionType }]
​
status
string
draft, active, or archived
​
createdAt
string
ISO 8601 timestamp

​
Create Content

POST /api/nodes/:nodeId/contents Create new content for a node.

​
Node Generations

​
Get Generations

GET /api/nodes/:nodeId/generations Retrieve generation history for a node.
​
[]
array
​
id
string
Generation UUID
​
nodeId
string
Node UUID
​
trigger
string
on_first_enter, manual_regenerate, or system_refresh
​
model
string
AI model used (e.g., claude-3-5-sonnet-20241022)
​
prompt
string
Generation prompt
​
responseMeta
string
JSON metadata about the generation
​
createdAt
string
ISO 8601 timestamp

​
Documents

​
Upload Documents

curl -X POST http://localhost:8000/api/nodes/abc123/documents \
  -F "[email protected]" \
  -F "[email protected]"
POST /api/nodes/:nodeId/documents Upload documents for a topic node. Accepts PDF, plain text, and Markdown files (max 10MB each, up to 5 files).

​
List Documents

GET /api/nodes/:nodeId/documents List all documents for a node.

​
Delete Document

DELETE /api/nodes/:nodeId/documents/:documentId Delete a document from S3 and the database.

Build docs developers (and LLMs) love

Get started for freeTalk to us