Journeys API — Graph Navigation¶

Edge function: journeys · Source: src/modules/journeys-graph/

Graph navigation endpoints for browsing, filtering, and exploring journeys. Returns structured { node, context } responses with breadcrumbs and sibling counts, suited for knowledge-graph navigation UIs.

Base URL (local): http://127.0.0.1:54321/functions/v1/journeys Authentication: Optional — pass Authorization: Bearer <jwt> with ?include_progress=true to receive per-user progress data. Cache policy: Moderate (2 min browser / 30 min CDN for unauthenticated). HTTP tests: http/journeys-graph.http

`GET /journeys/` — List All Journeys¶

List published journeys with optional domain and difficulty filtering, multiple sort orders, and optional inline embeds.

Operation ID: v1_list_journeys

Query Parameters¶

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`per_page`	integer	`20`	Items per page (max 100)
`domain`	string	—	Filter by domain slug or UUID
`difficulty`	string	—	`beginner` · `intermediate` · `advanced` · `expert`
`sort`	string	—	`popularity` · `sequence` · `recent`
`include_domain`	boolean	`false`	Embed parent domain object in each item
`include_chapters`	boolean	`false`	Embed chapter preview in each item
`chapter_limit`	integer	`3`	Max chapters per item when `include_chapters=true`

Response `200`¶

{
  "data": [
    {
      "id": "aaaaaaaa-0001-0001-0001-000000000001",
      "slug": "agentic-ai-mastery",
      "name": "Agentic AI Mastery",
      "description": "A comprehensive journey through agentic AI.",
      "domain": { // only when include_domain=true
        "id": "dddddddd-0001-...",
        "slug": "agentic-ai",
        "name": "Agentic AI"
      },
      "sequence_order": 1,
      "difficulty_level": "intermediate",
      "estimated_duration_minutes": 480,
      "stats": {
        "chapters_count": 6,
        "sparks_count": 24,
        "learners_count": 1247
      },
      "chapters": [], // only when include_chapters=true
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-02-20T00:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Response Schema¶

JourneyListItem

Field	Type	Notes
`id`	uuid	Journey UUID
`slug`	string	URL-safe identifier
`name`	string	Display title
`description`	string	Short description
`domain`	`DomainListItem` \| `null`	Present when `include_domain=true`
`sequence_order`	integer \| null	Curriculum sequence position
`difficulty_level`	string \| null	`beginner` · `intermediate` · `advanced` · `expert`
`estimated_duration_minutes`	integer \| null	Total estimated time
`stats`	`JourneyStats`	Aggregate counts
`chapters`	`ChapterListItem[]`	Present when `include_chapters=true`
`created_at`	ISO 8601	Creation timestamp
`updated_at`	ISO 8601	Last update timestamp

JourneyStats

Field	Type	Description
`chapters_count`	integer	Number of chapters
`sparks_count`	integer	Total atomic lessons
`learners_count`	integer	Enrolled users

`GET /journeys/{id}` — Get Journey by ID¶

Retrieve a single journey with full details, navigation context, and optional user progress. Accepts both UUID and slug.

Operation ID: v1_get_journey_graph

Path Parameters¶

Parameter	Type	Description
`id`	string	Journey UUID or URL slug

Query Parameters¶

Parameter	Type	Default	Description
`include_domain`	boolean	`true`	Include parent domain
`include_chapters`	boolean	`false`	Embed chapters list in node
`chapter_limit`	integer	`20`	Max chapters when `include_chapters=true`
`include_progress`	boolean	`false`	Add user progress block (requires auth)

Response `200`¶

{
  "node": {
    "id": "aaaaaaaa-0001-0001-0001-000000000001",
    "slug": "agentic-ai-mastery",
    "name": "Agentic AI Mastery",
    "description": "A comprehensive journey through agentic AI systems.",
    "long_description": "Deep dive into building autonomous AI agents ...",
    "domain": {
      "id": "dddddddd-0001-...",
      "slug": "agentic-ai",
      "name": "Agentic AI"
    },
    "sequence_order": 1,
    "prerequisites": ["basic-ml-concepts"],
    "learning_outcomes": [
      "Build autonomous AI agents using LangChain and LangGraph",
      "Design multi-agent systems with supervisor architectures"
    ],
    "difficulty_level": "intermediate",
    "estimated_duration_minutes": 480,
    "tags": ["agentic-ai", "langchain", "langgraph"],
    "stats": {
      "chapters_count": 6,
      "sparks_count": 24,
      "learners_count": 1247,
      "completion_rate": 0.72         // ratio 0–1
    },
    "chapters": [],                   // only when include_chapters=true
    "progress": { ... },              // only when include_progress=true + valid auth
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-02-20T00:00:00Z"
  },
  "context": {
    "parent": {
      "id": "dddddddd-0001-...",
      "slug": "agentic-ai",
      "name": "Agentic AI"
    },
    "children_count": 6,
    "siblings_count": 3,
    "breadcrumbs": [
      { "label": "Agentic AI",         "href": "/domains/agentic-ai",           "type": "domain"  },
      { "label": "Agentic AI Mastery", "href": "/journeys/agentic-ai-mastery",  "type": "journey" }
    ]
  }
}

Response Schema¶

JourneyNode (inside node)

Field	Type	Notes
`id`	uuid
`slug`	string
`name`	string
`description`	string	Short description
`long_description`	string \| null	Extended markdown description
`domain`	`DomainListItem`	Populated unless `include_domain=false`
`sequence_order`	integer \| null
`prerequisites`	`string[]` \| null	Prerequisite journey slugs
`learning_outcomes`	`string[]` \| null	Mastery outcome bullets
`difficulty_level`	string \| null
`estimated_duration_minutes`	integer \| null
`tags`	`string[]` \| null	Beacon/tag slugs
`stats`	`JourneyDetailStats`	Includes `completion_rate`
`chapters`	`ChapterListItem[]`	Present when `include_chapters=true`
`progress`	`UserProgressInfo` \| null	Present when `include_progress=true` + auth
`created_at`	ISO 8601
`updated_at`	ISO 8601

UserProgressInfo (inside node.progress)

Field	Type	Notes
`status`	string	`not_started` · `in_progress` · `completed`
`progress_percentage`	number	0–100
`time_spent_minutes`	integer \| null
`started_at`	ISO 8601 \| null
`last_accessed_at`	ISO 8601 \| null
`completed_at`	ISO 8601 \| null
`bookmarked`	boolean

JourneyContext (inside context)

Field	Type	Notes
`parent`	`DomainListItem`	Parent domain
`children_count`	integer	Number of chapters
`siblings_count`	integer	Other journeys in the same domain
`breadcrumbs`	`Breadcrumb[]`	Navigation path

Breadcrumb

Field	Type	Description
`label`	string	Display text
`href`	string	Relative URL
`type`	string	`domain` · `journey`

Response `404`¶

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

`GET /journeys/{id}/chapters` — List Journey Chapters¶

Paginated list of chapters within a journey, with optional spark previews and user progress data.

Operation ID: v1_get_journey_chapters

Path Parameters¶

Parameter	Type	Description
`id`	string	Journey UUID or URL slug

Query Parameters¶

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`per_page`	integer	`20`	Items per page (max 100)
`include_sparks`	boolean	`false`	Embed spark preview per chapter
`spark_limit`	integer	`3`	Max sparks per chapter when `include_sparks=true`
`include_progress`	boolean	`false`	Add user progress data (requires auth)

Response `200`¶

{
  "data": [
    {
      "id": "cccccccc-0001-0001-0001-000000000001",
      "slug": "foundations-of-agentic-ai",
      "name": "Foundations of Agentic AI",
      "description": "Understand what agents are and how they differ from chatbots.",
      "sequence_order": 1
    },
    {
      "id": "cccccccc-0001-0001-0001-000000000002",
      "slug": "tool-use-and-memory",
      "name": "Tool Use and Memory",
      "description": "Equip your agent with external tools and persistent memory.",
      "sequence_order": 2
    }
  ],
  "meta": {
    "total": 6,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  },
  "parent": {
    "id": "aaaaaaaa-0001-0001-0001-000000000001",
    "slug": "agentic-ai-mastery",
    "name": "Agentic AI Mastery",
    "type": "journey",
    "domain": {
      "id": "dddddddd-0001-...",
      "slug": "agentic-ai",
      "name": "Agentic AI"
    }
  }
}

Response Schema¶

ChapterListItem

Field	Type	Notes
`id`	uuid
`slug`	string
`name`	string
`description`	string
`sequence_order`	integer \| null	1-based position in journey

Top-level parent

Field	Type	Notes
`id`	uuid	Parent journey UUID
`slug`	string
`name`	string
`type`	string	Always `"journey"`
`domain`	`DomainListItem`	Parent domain

Response `404`¶

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

Implementation Notes¶

Routes are defined in src/modules/journeys-graph/routes.ts and mounted at /journeys in functions/journeys/index.ts.
The service layer (src/modules/journeys-graph/service.ts) is a thin wrapper over ModernTrailService — DB tables remain trails/concepts; only the API surface uses journey/chapter vocabulary.
Breadcrumb href values use /journeys/ (not /trails/).
The deprecated graph function serves the same routes via src/routes/graph/index.ts at /graph/journeys/*.

See also: Journeys overview · Catalog function · User progress

Journeys API — Graph Navigation¶

GET /journeys/ — List All Journeys¶

Query Parameters¶

Response 200¶

Response Schema¶

GET /journeys/{id} — Get Journey by ID¶

Path Parameters¶

Query Parameters¶

Response 200¶

Response Schema¶

Response 404¶

GET /journeys/{id}/chapters — List Journey Chapters¶

Path Parameters¶

Query Parameters¶

Response 200¶

Response Schema¶

Response 404¶

Implementation Notes¶

`GET /journeys/` — List All Journeys¶

Response `200`¶

`GET /journeys/{id}` — Get Journey by ID¶

Response `200`¶

Response `404`¶

`GET /journeys/{id}/chapters` — List Journey Chapters¶

Response `200`¶

Response `404`¶