User API¶

User profile, learning journeys, progress tracking, and achievements.

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

Endpoints¶

Endpoint	Purpose
`GET /`	Current user profile
`GET /stats`	Learning statistics
`GET /milestones`	User achievements
`GET /journeys`	List learning journey enrollments
`GET /journeys/{id}`	Journey details with per-spark progress
`GET /events`	Learning activity events
`GET /health`	Health check

GET /¶

Returns the current user's profile.

Response¶

{
  "id": "uuid",
  "email": "user@example.com",
  "display_name": "John Doe",
  "created_at": "2024-01-01T00:00:00Z"
}

GET /stats¶

Returns learning statistics.

Response¶

{
  "sparks_completed": 45,
  "sparks_mastered": 32,
  "concepts_completed": 12,
  "trails_completed": 3,
  "total_learning_mins": 420,
  "current_streak_days": 7
}

GET /milestones¶

Returns user achievements and mastery records.

Parameters¶

Parameter	Type	Default	Description
`entity_type`	enum	all	Filter: `spark`, `concept`, `trail`
`page`	integer	1	Page number
`per_page`	integer	20	Items per page

Response¶

{
  "data": [
    {
      "entity_type": "spark",
      "entity_id": "uuid",
      "entity_slug": "self-attention",
      "mastery_level": 92,
      "achieved_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { ... }
}

GET /journeys¶

Returns the authenticated user's learning journey enrollments, enriched with spark completion counts.

Parameters¶

Parameter	Type	Default	Description
`status`	enum	—	Filter by status: `not_started`, `in_progress`, `completed`
`sort`	enum	`recent`	Sort order: `recent` (last activity), `progress` (completion %), `started` (enroll date)

Response¶

{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "trail_id": "uuid",
      "status": "in_progress",
      "progress_percent": 45,
      "started_at": "2026-01-10T00:00:00Z",
      "completed_at": null,
      "last_activity_at": "2026-02-20T10:30:00Z",
      "completed_sparks": 12,
      "total_sparks": 27,
      "trail": {
        "id": "uuid",
        "title": "Agentic AI Mastery",
        "slug": "agentic-ai-mastery",
        "difficulty_level": "intermediate"
      }
    }
  ]
}

GET /journeys/{id}¶

Returns full progress detail for a specific journey enrollment, including per-spark status and the current active concept.

Parameters¶

Parameter	Type	Description
`id`	UUID	Journey enrollment ID

Response¶

{
  "id": "uuid",
  "user_id": "uuid",
  "trail_id": "uuid",
  "status": "in_progress",
  "progress_percent": 45,
  "started_at": "2026-01-10T00:00:00Z",
  "completed_at": null,
  "last_activity_at": "2026-02-20T10:30:00Z",
  "completed_sparks": 12,
  "total_sparks": 27,
  "current_concept": {
    "id": "uuid",
    "title": "Tool Use Patterns",
    "slug": "tool-use-patterns"
  },
  "spark_progress": [
    {
      "spark_id": "uuid",
      "title": "What is an AI Agent?",
      "status": "completed",
      "completed_at": "2026-02-15T09:00:00Z"
    },
    {
      "spark_id": "uuid",
      "title": "Agents vs Chatbots",
      "status": "in_progress",
      "completed_at": null
    },
    {
      "spark_id": "uuid",
      "title": "ReAct Loop Explained",
      "status": "not_started",
      "completed_at": null
    }
  ],
  "trail": {
    "id": "uuid",
    "title": "Agentic AI Mastery",
    "slug": "agentic-ai-mastery",
    "difficulty_level": "intermediate"
  }
}

current_concept is the first concept with incomplete sparks — a "continue here" pointer for clients. It is null when all sparks are completed.

Spark status values: not_started, in_progress, completed.

GET /events¶

Returns learning activity events.

Parameters¶

Parameter	Type	Default	Description
`verb`	enum	all	Filter: `started`, `completed`, `mastered`, `bookmarked`
`page`	integer	1	Page number
`per_page`	integer	20	Items per page

Response¶

{
  "data": [
    {
      "id": "uuid",
      "verb": "completed",
      "spark_id": "uuid",
      "spark_slug": "self-attention",
      "result": { "success": true, "score": 85 },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { ... }
}

When to Use¶

User dashboard and profile pages
Progress tracking UI
Achievement displays
"Continue learning" features
Activity history