API Reference¶

Endpoint documentation for the Microlearning Platform API, deployed as independent Supabase Edge Functions.

Architecture¶

┌─────────────────────────────────────────────────────────────────────┐
│                      CLIENT APPLICATIONS                             │
│         (Web, Mobile - using OpenAPI-generated clients)             │
└────────────────────────┬────────────────────────────────────────────┘
                         │
                         ▼
               ┌───────────────────┐
               │   Supabase Edge   │
               │     Functions     │
               │   Deno + Hono     │
               └─────────┬─────────┘
                         │
               ┌─────────▼─────────┐
               │    PostgreSQL     │
               │  (Supabase + RLS) │
               └───────────────────┘

Edge Functions¶

The API is split across 7 independent Edge Functions:

Function	Path	Auth	Description
`graph`	`/graph/*`	Optional	Knowledge graph, domains, trails, concepts, sparks, beacons, explore
`content`	`/content/*`	Optional	Lesson content delivery and version history
`home`	`/home`	Optional	Homepage aggregation
`journeys`	`/journeys/*`	Optional	Journey graph navigation: browse, filter, explore
`search`	`/search/*`	Required	Full-text search and autocomplete
`snapshots`	`/snapshots/*`	Required	Content versioning
`user`	`/me/*`	Required	User profile, journeys, events, milestones
`metadata`	`/metadata/*`	Public	Static enumerations

Endpoint Reference¶

Graph Function (`/graph/*`)¶

Endpoint	Description
Domains API	List and get domain details
Discovery API	Faceted browsing across all resource types
Graph API	Prerequisite graph, learning paths, breadcrumbs

Journeys Functions¶

Document	Function	Description
Journeys overview	—	Quick reference, auth, caching
Graph navigation	`journeys`	Browse, filter, and explore journeys
User progress	`user`	`/me/journeys` — authenticated enrollments

Other Functions¶

Document	Function	Description
Search API	`search`	Full-text search and autocomplete
User API	`user`	Profile, journeys, events, milestones
Snapshots API	`snapshots`	Content versioning and publishing
Metadata API	`metadata`	Enumeration values

Base URLs¶

Environment	Base URL
Local	`http://127.0.0.1:54321/functions/v1/{function}`
Production	`https://<project-ref>.supabase.co/functions/v1/{function}`

Examples:

http://127.0.0.1:54321/functions/v1/graph/domains
http://127.0.0.1:54321/functions/v1/search?q=transformers
http://127.0.0.1:54321/functions/v1/journeys/

Authentication¶

All requests to Supabase Edge Functions locally require the apikey header:

apikey: <supabase-anon-key>

Protected endpoints additionally require a JWT:

Authorization: Bearer <jwt-token>

Endpoint auth levels:

Endpoint category	Auth
`GET /graph/*`	Optional — enhances response if authenticated
`GET /content/*`	Optional
`GET /home`	Optional
`GET /journeys/*`	Optional — adds user progress when authenticated
`GET /search/*`	Required
`GET /snapshots/*`	Required
`GET /me/*`	Required
`GET /metadata/*`	Public

Response Format¶

Success — List¶

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Success — Single Resource¶

{
  "data": { ... }
}

Error¶

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Common Error Codes¶

Code	HTTP Status	Description
`NOT_FOUND`	404	Resource does not exist
`UNAUTHORIZED`	401	Authentication required
`FORBIDDEN`	403	Insufficient permissions
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Pagination¶

All list endpoints support pagination via query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-based)
`per_page`	integer	20	Items per page (max: 100)

Common Query Parameters¶

Parameter	Description	Example
`page`	Page number (1-indexed)	`?page=2`
`per_page`	Items per page (max 100)	`?per_page=50`
`snapshot_id`	Historical data query	`?snapshot_id=uuid`
`domain`	Filter by domain slug	`?domain=machine-learning`
`difficulty`	Filter by difficulty	`?difficulty=intermediate`
`beacon`	Filter by tag	`?beacon=nlp`

Rate Limiting¶

Rate limits vary by user tier:

Tier	Content	Search	User	Events
Anonymous	60/min	10/min	—	—
Free	120/min	20/min	60/min	100/min
Pro	180/min	50/min	120/min	200/min
Premium	300/min	100/min	300/min	500/min

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Interactive Documentation (Swagger UI)¶

Each function exposes a Swagger UI locally:

http://127.0.0.1:54321/functions/v1/{function}/doc

OpenAPI spec: mcp/openapi.json

Content Hierarchy¶

Domain (e.g., "Machine Learning")
  └── Trail / Journey (10-20 hours, e.g., "Transformer Mastery")
        └── Concept (30-60 mins, e.g., "Attention Mechanisms")
              └── Spark (5-10 mins, e.g., "Self-Attention Explained")

Entity	Description	Typical Time
Domain	Top-level field of study	—
Trail / Journey	Complete learning path	10–20 hours
Concept	Knowledge cluster	30–60 mins
Spark	Atomic learning unit	5–10 mins

HTTP Test Files¶

Test files organized by function in the /http directory:

http/
├── domain/           # Domain API tests
│   ├── discovery.http
│   ├── domains.http
│   ├── graph.http
│   ├── metadata.http
│   ├── snapshots.http
│   └── user.http
└── http-client.env   # Shared environment config