Micro-Learning Platform Developer Guide¶
A comprehensive guide for developers integrating with the Micro-Learning Platform API. This documentation focuses on understanding the platform's concepts, how they interconnect, and practical usage patterns for building learning applications.
Table of Contents¶
- Introduction
- Core Philosophy
- Domain Vocabulary
- The Knowledge Graph
- User Learning Model
- API Usage by Use Case
- Integration Patterns
- Common Workflows
- Best Practices
- SDK Development
Introduction¶
The Micro-Learning Platform is designed for delivering technical education in digestible 5-10 minute units. Unlike traditional Learning Management Systems (LMS) that focus on long-form courses, this platform embraces atomic learning—breaking complex topics into interconnected micro-lessons that can be consumed independently or as part of structured learning paths.
Who is this for?¶
- Frontend developers building learning applications, mobile apps, or dashboards
- Backend developers integrating learning features into existing platforms
- Product teams designing learning experiences for software engineers, ML practitioners, and AI enthusiasts
What makes this different?¶
| Traditional LMS | Micro-Learning Platform |
|---|---|
| Fixed course structure | Flexible navigation (atomic or guided) |
| Linear progression | Graph-based prerequisites (DAG) |
| Hours-long courses | 5-10 minute micro-lessons |
| Static content | AI-generated with human review |
| Completion-focused | Mastery and retention-focused |
Core Philosophy¶
1. Atomic Learning Units¶
Every piece of content is designed to teach one concept well in under 10 minutes. A learner should be able to: - Open any topic directly (no forced prerequisites) - Understand what they need to know first (visible dependencies) - Complete a meaningful learning unit in a single session
2. Knowledge as a Graph¶
Learning isn't linear. Understanding "Attention Mechanisms" might require knowledge of "Linear Algebra" and "Word Embeddings"—concepts from different domains. The platform models this as a Directed Acyclic Graph (DAG) where: - Nodes are learning units - Edges represent prerequisite relationships - Paths can be calculated to any destination
3. Flexible Entry Points¶
Users can enter the platform at any point: - Bottom-up: Start with a specific concept they need right now - Top-down: Follow a curated learning path (Trail) - Exploratory: Browse by tags (Beacons) or search
4. Progress is Personal¶
The platform tracks individual learning journeys, not just completion status. It understands: - What you've mastered - What you're currently learning - What you should review - What's recommended next
Domain Vocabulary¶
The platform uses distinct terminology to differentiate from traditional LMS concepts and capture the micro-learning essence.
Entity Hierarchy¶
┌─────────────────────────────────────────────────────────────────┐
│ DOMAIN │
│ (e.g., "Machine Learning", "Software Engineering") │
└─────────────────────────────────────────────────────────────────┘
│
│ contains many
▼
┌─────────────────────────────────────────────────────────────────┐
│ TRAIL │
│ (e.g., "Transformer Architecture Mastery" - ~10-20 hours) │
└─────────────────────────────────────────────────────────────────┘
│
│ composed of ordered
▼
┌─────────────────────────────────────────────────────────────────┐
│ CONCEPT │
│ (e.g., "Attention Mechanisms" - ~30-60 mins) │
└─────────────────────────────────────────────────────────────────┘
│
│ groups related
▼
┌─────────────────────────────────────────────────────────────────┐
│ SPARK │
│ (e.g., "Self-Attention Explained" - 5-10 mins) │
└─────────────────────────────────────────────────────────────────┘
Detailed Vocabulary¶
Spark (Atomic Learning Unit)¶
What it is: The fundamental unit of learning. A Spark teaches exactly one focused concept with examples, typically consumable in 5-10 minutes.
Real-world analogy: Think of a Spark like a well-crafted YouTube tutorial or a focused documentation page—complete in itself but part of a larger ecosystem.
Key characteristics: - Self-contained (can be understood independently) - Focused (one concept, one objective) - Timed (estimated completion time) - Difficulty-rated (beginner to expert) - Versioned (content evolves, history preserved)
Example Sparks: - "Understanding Python List Comprehensions" (7 min, beginner) - "Self-Attention: How Tokens Communicate" (9 min, intermediate) - "Implementing Backpropagation from Scratch" (12 min, advanced)
Concept (Knowledge Cluster)¶
What it is: A higher-level abstraction grouping related Sparks into a coherent sub-topic. Concepts represent a skill or knowledge area that requires multiple Sparks to fully understand.
Real-world analogy: A chapter in a textbook, or a module in an online course.
Key characteristics: - Groups 3-8 related Sparks - Has a logical learning order within - Can exist independently or within a Trail - Represents a teachable skill unit
Example Concepts: - "Attention Mechanisms" (contains: Self-Attention, Multi-Head Attention, Positional Encoding) - "Python Data Structures" (contains: Lists, Dictionaries, Sets, Tuples)
Trail (Learning Journey)¶
What it is: A curated sequence of Concepts forming a complete learning path. Trails represent comprehensive knowledge acquisition in a subject area.
Real-world analogy: A complete online course or a certification track.
Key characteristics: - Ordered sequence of Concepts - Estimated total time (hours) - Difficulty progression (often beginner → advanced) - Clear learning outcomes
Example Trails: - "Transformer Architecture Mastery" (15 hours, intermediate-advanced) - "Python for Data Science" (20 hours, beginner-intermediate) - "System Design Fundamentals" (12 hours, intermediate)
Domain (Knowledge Field)¶
What it is: The broadest category representing a field of study. Domains organize Trails into logical groupings.
Key characteristics: - Top-level navigation category - Contains multiple related Trails - Represents a professional discipline or field
Example Domains: - Machine Learning - Software Engineering - Cloud Infrastructure - Data Engineering
Beacon (Discovery Tag)¶
What it is: A tag or keyword attached to Sparks for cross-cutting discovery. Beacons transcend the hierarchical structure, enabling topic-based exploration.
Real-world analogy: Hashtags on social media, or tags on Stack Overflow questions.
Key characteristics: - Many-to-many relationship with Sparks - Categorized (technology, concept, application, level, format) - Enables cross-domain discovery - Powers search and recommendations
Example Beacons:
- Technology: python, pytorch, kubernetes
- Concept: recursion, distributed-systems, gradient-descent
- Application: nlp, computer-vision, web-development
Link (Prerequisite Relationship)¶
What it is: A directed edge in the knowledge graph representing that one Spark/Concept should be understood before another.
Key characteristics: - Directed (A → B means "A before B") - Weighted (strength of relationship: 0-1) - Typed (prerequisite, recommended, related, deepens) - Forms a DAG (no circular dependencies)
Link types explained:
- prerequisite: Required knowledge (weight: 0.8-1.0)
- recommended: Helpful but not required (weight: 0.5-0.7)
- related: Tangentially connected (weight: 0.3-0.5)
- deepens: Advanced extension of the topic (weight: 0.6-0.8)
Journey (User Progress Record)¶
What it is: A user's personal learning record on a Trail. Tracks progress, status, and activity.
Key characteristics:
- One Journey per user per Trail
- Tracks percentage completion
- Records start time, last activity, completion
- Status: in_progress, completed, paused
Milestone (Achievement Record)¶
What it is: A record of mastery or achievement for a Spark, Concept, or Trail.
Key characteristics: - Earned through completion and demonstrated understanding - Has mastery level (0-100) - Timestamped achievement - Unlocks dependent content visibility
Learning Event (Activity Record)¶
What it is: An xAPI-inspired record of learning activity. Every interaction with content generates events.
Event verbs:
- started: Began viewing a Spark
- completed: Finished a Spark (with success indicator)
- practiced: Engaged with exercises
- mastered: Demonstrated deep understanding
- revisited: Returned to previously completed content
- bookmarked: Saved for later
- skipped: Intentionally bypassed
The Knowledge Graph¶
Understanding Prerequisites¶
The platform models knowledge dependencies as a Directed Acyclic Graph (DAG). This enables:
- Prerequisite visualization: Show learners what they need to know first
- Learning path calculation: Find the optimal route to any topic
- Gap analysis: Identify missing knowledge for a target goal
- Personalized recommendations: Suggest next steps based on current knowledge
Graph Structure¶
┌─────────────┐
│ Linear │
│ Algebra │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Matrix │ │ Vector │ │ Tensor │
│Operations│ │ Spaces │ │ Basics │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
└────────────┼────────────┘
│
▼
┌──────────────┐
│ Word │
│ Embeddings │
└──────┬───────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Self- │ │ Cosine │
│ Attention │ │ Similarity │
└──────┬──────┘ └─────────────┘
│
▼
┌─────────────┐
│ Multi-Head │
│ Attention │
└─────────────┘
What Questions Does the Graph Answer?¶
| Question | API Endpoint | Response |
|---|---|---|
| "What do I need to know before learning X?" | GET /api/v1/sparks/{slug}/prerequisites |
List of prerequisite Sparks with depth |
| "What's the fastest path to learn X?" | GET /api/v1/graph/path?target={slug} |
Ordered learning path with time estimates |
| "What can I learn next after X?" | GET /api/v1/graph/sparks/{slug}?direction=dependents |
Sparks that depend on X |
| "Show me the knowledge map for X" | GET /api/v1/graph/sparks/{slug} |
Full graph (nodes + edges) for visualization |
User Learning Model¶
How Progress is Tracked¶
┌─────────────────────────────────────────────────────────────────┐
│ USER │
└─────────────────────────────────────────────────────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ JOURNEYS │ │ LEARNING EVENTS │ │ MILESTONES │
│ (Trail progress)│ │ (All activity) │ │ (Achievements) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
"45% complete "Started Spark X "Mastered Spark Y
on Trail A" at 2:30 PM" with 92% score"
The Learning Event Flow¶
When a user interacts with a Spark:
User opens Spark
│
▼
┌──────────────┐ Event: "started"
│ POST /event │ ──► spark_id, timestamp
└──────────────┘
│
│ (user studies content)
│
▼
┌──────────────┐ Event: "completed"
│ POST /event │ ──► spark_id, result: { success: true, score: 85 }
└──────────────┘
│
▼
┌──────────────────────────────────────────┐
│ AUTOMATIC UPDATES │
├──────────────────────────────────────────┤
│ • Milestone created/updated for Spark │
│ • Journey progress recalculated │
│ • Trail milestone if Journey complete │
└──────────────────────────────────────────┘
Mastery vs. Completion¶
The platform distinguishes between:
- Completion: User finished the content
- Mastery: User demonstrated understanding (score ≥ 80%)
A user can complete a Spark without mastering it. Mastery unlocks: - Milestone achievements - Progress toward Concept/Trail mastery - Recommendations for advanced content
API Usage by Use Case¶
Use Case 1: Content Discovery¶
Scenario: A user opens your learning app and wants to explore available content.
"What domains are available?"¶
Returns top-level categories with stats (trail count, spark count).
When to use: Homepage, main navigation, onboarding flow.
"What can I learn in Machine Learning?"¶
Returns the domain with its Trails, descriptions, and difficulty levels.
When to use: Domain landing pages, category browsing.
"Show me beginner-friendly content"¶
Filter content by difficulty level.
When to use: Skill-level filtering, onboarding recommendations.
"What's trending/popular?"¶
Returns tags sorted by popularity.
When to use: Trending topics section, tag clouds.
Use Case 2: Structured Learning¶
Scenario: A user wants to follow a complete learning path.
"Start the Transformer Architecture trail"¶
Creates a Journey record for the user on this Trail.
When to use: "Start Learning" button on Trail page.
"What's my current progress?"¶
Returns detailed progress including: - Overall percentage - Current Concept - Per-Spark completion status - Time invested
When to use: Progress dashboard, continue learning UI.
"What should I learn next in this Trail?"¶
The Journey response includes current_concept and spark_progress showing:
- Completed Sparks
- In-progress Sparks
- Not-started Sparks
When to use: "Continue" button, next lesson recommendations.
"I need to pause this Trail"¶
When to use: User wants to focus on different content.
Use Case 3: Atomic Learning¶
Scenario: A user needs to quickly learn one specific topic.
"I just need to understand Self-Attention"¶
Returns full Spark content, estimated time, and prerequisites.
When to use: Direct content access, search result click.
"What do I need to know first?"¶
Returns prerequisite Sparks with depth levels (immediate vs. transitive).
When to use: "Prerequisites" panel, learning gap analysis.
"Give me the fastest path to learn this"¶
Calculates optimal learning path considering: - What the user already knows (authenticated) - Weighted prerequisite importance - Estimated total time
When to use: "Learning Path" generator, study planner.
Use Case 4: Progress Tracking¶
Scenario: Track and record user learning activity.
"User started viewing a Spark"¶
When to use: When user opens Spark content.
"User completed a Spark"¶
POST /api/v1/me/events
Body: {
"spark_id": "uuid",
"verb": "completed",
"result": {
"success": true,
"score": 85,
"duration_secs": 420
}
}
Automatic effects: - Creates/updates Milestone for Spark - Updates Journey progress if Spark is in an active Journey - May complete the Trail if all Sparks done
When to use: When user finishes Spark content or passes a quiz.
"What are my achievements?"¶
GET /api/v1/me/milestones
GET /api/v1/me/milestones?entity_type=spark
GET /api/v1/me/milestones?entity_type=trail
When to use: Achievement page, profile badges.
"What's my overall learning stats?"¶
Returns: - Sparks mastered - Concepts mastered - Trails completed - Total learning time - Current streak
When to use: Dashboard, profile page, gamification.
Use Case 5: Search & Discovery¶
Scenario: User is looking for specific content.
"Search for 'attention mechanism'"¶
Returns results across Sparks, Concepts, and Trails with: - Relevance scores - Facets for filtering - Total counts
When to use: Search results page.
"Search only in Sparks"¶
When to use: Filtered search.
"Filter by difficulty and tags"¶
When to use: Advanced search with filters.
"Autocomplete as user types"¶
Returns quick suggestions for: - Spark titles - Beacon names
When to use: Search input autocomplete dropdown.
Use Case 6: Content Exploration by Tags¶
Scenario: User wants to explore content by topic tags.
"What content is tagged 'transformers'?"¶
Returns the beacon with all associated Sparks.
When to use: Tag detail pages, topic exploration.
"Browse all available tags"¶
When to use: Tag browser, filter panels.
Use Case 7: Visualizing Knowledge¶
Scenario: Show users a visual knowledge map.
"Show the prerequisite graph for this Spark"¶
Returns:
{
"root_id": "uuid",
"nodes": [
{ "id": "...", "title": "Multi-Head Attention", "depth": 0 },
{ "id": "...", "title": "Self-Attention", "depth": 1 },
{ "id": "...", "title": "Linear Algebra", "depth": 2 }
],
"edges": [
{ "source": "self-attention-id", "target": "multi-head-id", "weight": 0.9 }
]
}
When to use: Knowledge graph visualization, D3.js/Vis.js diagrams.
"Show both prerequisites AND what this unlocks"¶
When to use: Full context view showing what comes before and after.
Integration Patterns¶
Pattern 1: Anonymous Browsing → Authenticated Learning¶
┌─────────────────────────────────────────────────────────────────┐
│ ANONYMOUS USER │
├─────────────────────────────────────────────────────────────────┤
│ Can access: │
│ • GET /domains, /trails, /concepts, /sparks │
│ • GET /search, /beacons │
│ • GET /graph/* │
│ │
│ Cannot access: │
│ • /me/* endpoints (401 Unauthorized) │
└─────────────────────────────────────────────────────────────────┘
│
│ User signs up/logs in
▼
┌─────────────────────────────────────────────────────────────────┐
│ AUTHENTICATED USER │
├─────────────────────────────────────────────────────────────────┤
│ All anonymous access PLUS: │
│ • GET/PATCH /me (profile) │
│ • GET /me/stats │
│ • POST/GET /me/journeys │
│ • POST/GET /me/events │
│ • GET /me/milestones │
│ │
│ Personalized features: │
│ • Learning paths consider completed Sparks │
│ • Search results can be personalized │
└─────────────────────────────────────────────────────────────────┘
Pattern 2: Event-Driven Progress Updates¶
┌──────────────┐
│ User Action │
│ (completes │
│ Spark) │
└──────┬───────┘
│
▼
┌──────────────┐ ┌──────────────────────────────────┐
│ POST /events │────►│ Backend automatically: │
└──────────────┘ │ 1. Records learning event │
│ 2. Creates/updates Milestone │
│ 3. Updates Journey progress │
│ 4. Checks Trail completion │
└──────────────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Frontend can then: │
│ • GET /me/journeys/{id} for │
│ updated progress │
│ • GET /me/stats for new totals │
│ • Show achievement notifications │
└──────────────────────────────────┘
Pattern 3: Caching Strategy¶
┌─────────────────────────────────────────────────────────────────┐
│ CACHE AGGRESSIVELY │
├─────────────────────────────────────────────────────────────────┤
│ • GET /domains (changes rarely) │
│ • GET /trails (changes rarely) │
│ • GET /concepts (changes rarely) │
│ • GET /sparks/{slug} content (versioned, cache by version) │
│ • GET /beacons (changes rarely) │
│ • GET /graph/* (changes when links change) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ CACHE CAREFULLY │
├─────────────────────────────────────────────────────────────────┤
│ • GET /search (cache by query string, short TTL) │
│ • GET /me/* (user-specific, short TTL or no cache) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ NEVER CACHE │
├─────────────────────────────────────────────────────────────────┤
│ • POST /me/events (write operation) │
│ • POST /me/journeys (write operation) │
│ • PATCH /* (write operations) │
└─────────────────────────────────────────────────────────────────┘
Pattern 4: Mobile App Integration¶
┌─────────────────────────────────────────────────────────────────┐
│ OFFLINE-FIRST APPROACH │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. SYNC ON LAUNCH │
│ • GET /me/journeys (current learning state) │
│ • GET /trails/{id} for each active Journey │
│ • Cache Spark content for offline reading │
│ │
│ 2. QUEUE EVENTS OFFLINE │
│ • Store learning events locally │
│ • POST /me/events when online (batch supported) │
│ │
│ 3. OPTIMISTIC UI │
│ • Update local progress immediately │
│ • Sync with server in background │
│ │
└─────────────────────────────────────────────────────────────────┘
Common Workflows¶
Workflow 1: New User Onboarding¶
1. User lands on app
└── GET /api/v1/domains (show available fields)
2. User selects "Machine Learning"
└── GET /api/v1/domains/machine-learning (show trails)
3. User browses trails, selects "Intro to Deep Learning"
└── GET /api/v1/trails/intro-to-deep-learning (show details)
4. User clicks "Start Learning"
└── POST /api/v1/me/journeys { trail_id: "..." }
5. App redirects to first Spark
└── GET /api/v1/sparks/{first-spark-slug}
6. User completes first Spark
└── POST /api/v1/me/events { verb: "completed", ... }
7. App shows next Spark or progress summary
└── GET /api/v1/me/journeys/{id}
Workflow 2: Quick Lookup (Atomic Learning)¶
1. User searches "gradient descent"
└── GET /api/v1/search?q=gradient+descent
2. User clicks on "Understanding Gradient Descent" Spark
└── GET /api/v1/sparks/understanding-gradient-descent
3. App shows prerequisites panel
└── GET /api/v1/sparks/understanding-gradient-descent/prerequisites
4. User realizes they need "Calculus Basics" first
└── GET /api/v1/graph/path?target=understanding-gradient-descent
5. User follows the suggested path
└── (Events recorded for each Spark)
Workflow 3: Resume Learning¶
1. User opens app (authenticated)
└── GET /api/v1/me/journeys?status=in_progress
2. App shows active Journeys with progress
└── For each: GET /api/v1/me/journeys/{id} (detailed progress)
3. User clicks "Continue" on a Journey
└── Navigate to first non-completed Spark in spark_progress
4. User completes session
└── POST /api/v1/me/events for completed Sparks
Workflow 4: Achievement Review¶
1. User visits profile/achievements
└── GET /api/v1/me/stats (overview)
└── GET /api/v1/me/milestones?entity_type=trail (completed trails)
└── GET /api/v1/me/milestones?entity_type=spark (mastered sparks)
2. App displays:
- Total learning time
- Current streak
- Badges/achievements
- Recently mastered content
Workflow 5: Knowledge Map Exploration¶
1. User views a Spark and wants to see the "big picture"
└── GET /api/v1/graph/sparks/{slug}?direction=both&depth=3
2. App renders interactive graph visualization
└── Nodes colored by completion status (from /me/milestones)
3. User clicks on a node in the graph
└── GET /api/v1/sparks/{clicked-slug}
4. User can navigate the knowledge graph visually
Best Practices¶
1. Authentication¶
Always include the Supabase JWT token for authenticated endpoints:
Anonymous users can browse content but cannot: - Track progress - Start journeys - Record events - View personal stats
2. Pagination¶
All list endpoints support pagination:
Response includes pagination metadata:
{
"data": [...],
"meta": {
"total": 150,
"page": 1,
"per_page": 20,
"total_pages": 8,
"has_next": true,
"has_prev": false
}
}
3. Error Handling¶
All errors follow a consistent format:
Common error codes:
- NOT_FOUND (404): Resource doesn't exist
- UNAUTHORIZED (401): Authentication required
- VALIDATION_ERROR (400): Invalid request data
- CONFLICT (409): Resource already exists (e.g., duplicate Journey)
- INTERNAL_ERROR (500): Server error
4. Content Slugs vs. UUIDs¶
Most endpoints accept both slugs and UUIDs:
GET /api/v1/sparks/self-attention-explained (by slug)
GET /api/v1/sparks/550e8400-e29b-41d4-a716-446655440000 (by UUID)
Use slugs for: - User-facing URLs - Bookmarkable links - SEO-friendly routes
Use UUIDs for: - Internal references - Foreign key relationships - API-to-API communication
5. Filtering and Sorting¶
Most list endpoints support filters:
GET /api/v1/sparks?difficulty=beginner&is_published=true
GET /api/v1/trails?domain_id={uuid}&sort=recent
GET /api/v1/beacons?category=technology&sort=usage
6. Rate Limiting¶
The API enforces rate limits. Check response headers:
Implement exponential backoff on 429 responses.
7. Versioning Content¶
Spark content is versioned. To get version history:
To compare versions:
This is useful for: - Showing "what's changed" to returning users - Audit trails for AI-generated content - Rollback capabilities
SDK Development¶
Overview¶
The TypeScript SDK (/sdk) is not automatically generated when you add new API routes. The SDK generation process requires manual steps to ensure the SDK stays in sync with the API.
How SDK Generation Works¶
The SDK generation follows a two-step process:
-
OpenAPI Spec Generation: The OpenAPI specification (
mcp/openapi.json) is generated from your Hono route definitions. Hono automatically generatesoperationIdvalues based on the HTTP method and path. -
SDK Operations Generation: The SDK operations file is generated by reading the OpenAPI spec, not directly from your route code. This means the OpenAPI spec must be updated first.
When to Regenerate the SDK¶
You need to regenerate the SDK whenever you: - Add a new API route/endpoint - Modify route paths or methods - Change route parameters or query schemas - Add or remove route tags
Regenerating the SDK¶
Option 1: Full Build (Recommended)¶
Run the complete SDK build process which does all steps:
This command runs:
1. deno task mcp:generate:offline - Generates the OpenAPI spec from your routes
2. deno task sdk:generate - Generates SDK operations from the OpenAPI spec
3. deno task sdk:build - Builds the SDK package
Option 2: Step-by-Step¶
If you prefer to run each step individually:
# Step 1: Regenerate OpenAPI spec (includes all new routes)
deno task mcp:generate:offline
# Step 2: Regenerate SDK operations from the updated spec
deno task sdk:generate
# Step 3: Build the SDK
deno task sdk:build
After Regeneration¶
After running the generation commands:
-
Check Generated Operations: Review
sdk/src/endpoints/generated/operations.tsto see the new operation (e.g.,listDiscoveryBrowsefor a/discovery/browseroute). -
Add SDK Method: Add a corresponding method in the appropriate endpoint class (e.g.,
sdk/src/endpoints/discovery.ts) to expose the new operation:
async browse(
params: ListDiscoveryBrowseParams = {}
): Promise<DiscoveryBrowseResponse> {
const op = operations.listDiscoveryBrowse;
const response = await this.client.request<unknown>(op.path, {
method: op.method,
query: params as QueryParams,
});
return DiscoveryBrowseResponseSchema.parse(response);
}
-
Update Types: Import any new parameter types from
./generated/types.jsif needed. -
Test: Verify the new SDK method works correctly with your API.
Troubleshooting¶
Problem: New route doesn't appear in generated operations
Solution:
- Ensure the route is properly defined with createRoute() and registered with app.openapi()
- Check that the route path starts with /api/v1 (the generator only processes these paths)
- Verify the OpenAPI spec was regenerated: check mcp/openapi.json for your route
Problem: SDK generation fails with "Failed to read OpenAPI spec"
Solution: Run deno task mcp:generate:offline first to create the OpenAPI spec file.
Problem: Operation ID doesn't match expected pattern
Solution: Hono auto-generates operationId values. The pattern is typically:
- GET /api/v1/discovery/browse → listDiscoveryBrowse
- GET /api/v1/sparks/{slug} → getSpark
- POST /api/v1/me/journeys → createMeJourney
Check the generated OpenAPI spec to see the exact operationId for your route.
Appendix: Quick Reference¶
Content Endpoints (Public)¶
| Endpoint | Description |
|---|---|
GET /api/v1/domains |
List all domains |
GET /api/v1/domains/{slug} |
Get domain with trails |
GET /api/v1/trails |
List trails (filterable) |
GET /api/v1/trails/{slug} |
Get trail with concepts |
GET /api/v1/concepts |
List concepts |
GET /api/v1/concepts/{slug} |
Get concept with sparks |
GET /api/v1/sparks |
List sparks (filterable) |
GET /api/v1/sparks/{slug} |
Get spark with content |
GET /api/v1/sparks/{slug}/prerequisites |
Get prerequisite chain |
GET /api/v1/sparks/{slug}/versions |
Get version history |
GET /api/v1/beacons |
List tags |
GET /api/v1/beacons/{slug} |
Get tag with sparks |
Graph Endpoints (Public)¶
| Endpoint | Description |
|---|---|
GET /api/v1/graph/sparks/{slug} |
Get knowledge graph |
GET /api/v1/graph/path?target={slug} |
Calculate learning path |
Search Endpoints (Public)¶
| Endpoint | Description |
|---|---|
GET /api/v1/search?q={query} |
Full-text search |
GET /api/v1/search/autocomplete?q={query} |
Autocomplete suggestions |
User Endpoints (Authenticated)¶
| Endpoint | Description |
|---|---|
GET /api/v1/me |
Get current user profile |
PATCH /api/v1/me |
Update profile |
GET /api/v1/me/stats |
Get learning statistics |
GET /api/v1/me/milestones |
List achievements |
GET /api/v1/me/journeys |
List learning journeys |
POST /api/v1/me/journeys |
Start a journey |
GET /api/v1/me/journeys/{id} |
Get journey progress |
PATCH /api/v1/me/journeys/{id} |
Update journey status |
DELETE /api/v1/me/journeys/{id} |
Remove journey |
GET /api/v1/me/events |
List learning events |
POST /api/v1/me/events |
Record learning event |
GET /api/v1/me/events/spark/{id} |
Get spark event summary |
Need Help?¶
- API Specification: Visit
/docfor interactive Swagger documentation - OpenAPI Schema: Available at
/openapi.json - Health Check:
GET /healthto verify API availability