Graph API

Knowledge graph operations for prerequisites and learning paths.

Base URL: {base-url}/graph Authentication: Required (JWT)

---

Endpoints

Endpoint	Purpose
GET /sparks/{slug}	Prerequisite graph for a spark
GET /path	Calculate optimal learning path
GET /links/sparks	List spark relationships
GET /health	Health check

---

GET /sparks/{slug}

Returns the prerequisite graph for a spark.

Parameters

Parameter	Type	Default	Description
direction	enum	ancestors	ancestors, descendants, or both
max_depth	integer	3	Maximum traversal depth

Response

{
  "root_id": "uuid",
  "nodes": [
    { "id": "uuid", "slug": "self-attention", "title": "Self-Attention", "depth": 0 },
    { "id": "uuid", "slug": "linear-algebra", "title": "Linear Algebra", "depth": 1 }
  ],
  "edges": [
    { "source": "linear-algebra-id", "target": "self-attention-id", "weight": 0.9, "type": "prerequisite" }
  ]
}

Direction Options

Direction	Returns
ancestors	What you need to know first
descendants	What this unlocks
both	Full context (before and after)

---

GET /path

Calculate the optimal learning path to a target.

Parameters

Parameter	Type	Default	Description
target	string	required	Target spark slug
skip_mastered	boolean	true	Exclude already mastered sparks

Response

{
  "path": [
    { "slug": "linear-algebra", "title": "Linear Algebra", "estimated_mins": 10 },
    { "slug": "matrix-operations", "title": "Matrix Operations", "estimated_mins": 8 },
    { "slug": "self-attention", "title": "Self-Attention", "estimated_mins": 12 }
  ],
  "total_mins": 30,
  "skipped_count": 2
}

---

When to Use

• "Prerequisites" panel on spark pages
• "Learning Path" generator
• Knowledge map visualization
• Study planner features