Journeys API — Overview¶

Reference index for all Journey endpoints across the platform's edge functions.

Journeys are curated learning paths (10-20 hours) within a Domain. The Journeys API is split across two independent edge functions, each serving a distinct bounded context. All journey functions set verify_jwt = false; auth is handled at the application level.

Edge Functions at a Glance¶

Function	Base Path	Auth	Context	Source
`journeys`	`/journeys/`	Optional	Graph navigation — browse, filter, explore	`src/modules/journeys-graph/`
`user`	`/me/journeys/`	Required	User progress — enrollments, per-spark status	`src/routes/me/journeys.ts`
`graph` (deprecated)	`/graph/journeys/`	Optional	Monolithic aggregator — backward compat only	`src/routes/graph/`

Endpoint Quick Reference¶

`journeys` function — Graph Navigation¶

Method	Path	Description
`GET`	`/journeys/`	List all journeys (filterable, paginated)
`GET`	`/journeys/{id}`	Get journey by UUID or slug
`GET`	`/journeys/{id}/chapters`	List chapters within a journey

`user` function — User Progress¶

Method	Path	Description
`GET`	`/me/journeys`	List authenticated user's journey enrollments
`GET`	`/me/journeys/{id}`	Full progress detail for a specific enrollment

Authentication¶

Endpoint	Auth	Behavior
`/journeys/*`	Optional	Core data always returned; adds `progress` field when authenticated + `?include_progress=true`
`/me/journeys*`	Required	Returns `401` without a valid `Authorization: Bearer <jwt>` header

Headers:

Header	Required	Description
`apikey`	Local dev only	Supabase anon key — required by `supabase functions serve`
`Authorization`	Conditional	`Bearer <jwt>` — required for `/me/journeys`; optional for progress enrichment elsewhere

Caching¶

The journeys function applies CACHE_MODERATE:

Scope	Duration	Cache-Control value
Browser (unauthenticated)	2 min	`public, max-age=120, s-maxage=1800, stale-while-revalidate=3600`
Browser (authenticated)	2 min	`private, max-age=120, stale-while-revalidate=3600`
CDN (unauthenticated only)	30 min	via `s-maxage=1800`

Vary: Authorization, Accept is set to ensure correct cache keying when the same URL serves both anonymous and authenticated responses.

/me/journeys* endpoints are not cached (user-specific, mutable data).

Local Development URLs¶

# journeys function
GET http://127.0.0.1:54321/functions/v1/journeys/
GET http://127.0.0.1:54321/functions/v1/journeys/{id}
GET http://127.0.0.1:54321/functions/v1/journeys/{id}/chapters

# user function (authenticated)
GET http://127.0.0.1:54321/functions/v1/user/me/journeys
GET http://127.0.0.1:54321/functions/v1/user/me/journeys/{id}

# deprecated monolithic graph function
GET http://127.0.0.1:54321/functions/v1/graph/journeys
GET http://127.0.0.1:54321/functions/v1/graph/journeys/{id}
GET http://127.0.0.1:54321/functions/v1/graph/journeys/{id}/chapters

# backward-compatibility redirects (302)
GET http://127.0.0.1:54321/functions/v1/graph/trails   → /graph/journeys
GET http://127.0.0.1:54321/functions/v1/graph/trails/* → /graph/journeys/*

Error Responses¶

All journey endpoints use the same error shape:

{ "error": { "code": "NOT_FOUND", "message": "Journey not found: <id>" } }

Code	HTTP	Endpoints
`NOT_FOUND`	404	Any endpoint with `{id}` param
`UNAUTHORIZED`	401	`/me/journeys*` only
`INTERNAL_ERROR`	500	All endpoints

Detailed Documentation¶

Document	Covers
graph.md	`journeys` function — list, get, chapters (graph navigation)
user-progress.md	`user` function — `/me/journeys` authenticated endpoints

Source Files¶

File	Purpose
`functions/journeys/index.ts`	Edge function entry point (graph)
`functions/user/index.ts`	Edge function entry point (user)
`src/modules/journeys-graph/`	Graph navigation module (schema, routes, service, types)
`src/routes/me/journeys.ts`	User progress route handlers
`src/routes/graph/index.ts`	Deprecated monolithic graph aggregator
`http/journeys-graph.http`	REST client tests — graph navigation
`http/user.http`	REST client tests — user progress journeys