docs
CTRL K
GitHubDiscord
DevelopersAPI ReferenceLearnIntegrationsWebsiteGitHubDiscord
Skip to Content

Headless

Server-to-server endpoints for headless integrations: provision users, enroll learners and manage content programmatically. These endpoints require an lh_ API token.

Issue a user token

POST/api/v1/admin/{org_slug}/auth/token
API tokenrequired (no session fallback)

Issue a JWT access token on behalf of a user. The user must belong to the organization matching the org_slug. Requires `users.action_read` permission.

Path parameters

org_slugstringrequired

Request bodyapplication/jsonrequired

user_idintegerrequired

ID of the user to issue a token for

Returns

TokenResponse: Access token minted on behalf of the target user.

access_tokenstringrequired

JWT access token

token_typestring

Token type (always 'bearer')

user_idintegerrequired

ID of the user the token was issued for

user_uuidstringrequired

UUID of the user

Error responses
  • 403 API token lacks permission, user not in org, or org_slug mismatch
  • 404 User or organization not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "access_token": "string",
  "token_type": "bearer",
  "user_id": 1,
  "user_uuid": "string"
}

Check user course access

GET/api/v1/admin/{org_slug}/courses/{course_uuid}/access/{user_id}
API tokenrequired (no session fallback)

Check if a user can access a specific course. Returns enrollment status and whether the course is public. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
course_uuidstringrequired
user_idintegerrequired

Returns

CourseAccessResponse: Access check result — whether the user can view the course.

has_accessbooleanrequired

True if the user can access the course (public or enrolled)

is_enrolledbooleanrequired

True if the user is enrolled in the course

is_publicbooleanrequired

True if the course is public

is_publishedbooleanrequired

True if the course is published

Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "has_access": false,
  "is_enrolled": false,
  "is_public": false,
  "is_published": false
}

Bulk unenroll users from a course

POST/api/v1/admin/{org_slug}/enrollments/bulk/unenroll
API tokenrequired (no session fallback)

Mirror of bulk enroll. Users not currently enrolled are reported in `not_enrolled`.

Path parameters

org_slugstringrequired

Request bodyapplication/jsonrequired

course_uuidstringrequired
user_idsinteger[]required

Returns

BulkUnenrollResponse: Per-user unenroll summary: unenrolled, not_enrolled.

unenrolledinteger[]required
not_enrolledinteger[]required
Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "unenrolled": [
    0
  ],
  "not_enrolled": [
    0
  ]
}

Enroll user in course

POST/api/v1/admin/{org_slug}/enrollments/{user_id}/{course_uuid}
API tokenrequired (no session fallback)

Enroll a user in a course on their behalf. Creates the learning trail and trail run. The user must belong to the organization. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

TrailRead: User enrolled — returns the user's updated trail with all runs.

idinteger | null
trail_uuidstring | null
org_idintegerrequired
user_idintegerrequired
creation_datestring | null
update_datestring | null
runsTrailRunRead[]required
Show child attributes
idinteger | null
dataData
statusStatusEnum
STATUS_IN_PROGRESSSTATUS_COMPLETEDSTATUS_PAUSEDSTATUS_CANCELLED
trail_idinteger | null
course_idinteger | null
org_idinteger | null
user_idinteger | null
courseCourse | null
creation_datestring | null
update_datestring | null
course_total_stepsinteger
stepsTrailStep[]
Show child attributes
idinteger | null
completebooleanrequired
teacher_verifiedbooleanrequired
gradestringrequired
dataData
trailrun_idintegerrequired
trail_idintegerrequired
activity_idintegerrequired
course_idintegerrequired
org_idintegerrequired
user_idintegerrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 400 User is already enrolled
  • 404 User or course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "id": 1,
  "trail_uuid": "string",
  "org_id": 1,
  "user_id": 1,
  "creation_date": "string",
  "update_date": "string",
  "runs": [
    {
      "id": 1,
      "data": {},
      "status": "STATUS_IN_PROGRESS",
      "trail_id": 1,
      "course_id": 1,
      "org_id": 1,
      "user_id": 1,
      "course": {},
      "creation_date": "string",
      "update_date": "string",
      "course_total_steps": 0,
      "steps": [
        {
          "id": 1,
          "complete": false,
          "teacher_verified": false,
          "grade": "string",
          "data": {},
          "trailrun_id": 1,
          "trail_id": 1,
          "activity_id": 1,
          "course_id": 1,
          "org_id": 1,
          "user_id": 1,
          "creation_date": "string",
          "update_date": "string"
        }
      ]
    }
  ]
}

Unenroll user from course

DELETE/api/v1/admin/{org_slug}/enrollments/{user_id}/{course_uuid}
API tokenrequired (no session fallback)

Unenroll a user from a course. Removes the enrollment and all associated progress (trail steps). Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

UnenrollResponse: User unenrolled — trail steps for this course are deleted.

detailstringrequired
Error responses
  • 404 Enrollment not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string"
}

Get user enrollments

GET/api/v1/admin/{org_slug}/enrollments/{user_id}
API tokenrequired (no session fallback)

Get all course enrollments for a user in the organization, including trail runs and steps. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

TrailRead: The user's trail with every course enrollment and step.

idinteger | null
trail_uuidstring | null
org_idintegerrequired
user_idintegerrequired
creation_datestring | null
update_datestring | null
runsTrailRunRead[]required
Show child attributes
idinteger | null
dataData
statusStatusEnum
STATUS_IN_PROGRESSSTATUS_COMPLETEDSTATUS_PAUSEDSTATUS_CANCELLED
trail_idinteger | null
course_idinteger | null
org_idinteger | null
user_idinteger | null
courseCourse | null
creation_datestring | null
update_datestring | null
course_total_stepsinteger
stepsTrailStep[]
Show child attributes
idinteger | null
completebooleanrequired
teacher_verifiedbooleanrequired
gradestringrequired
dataData
trailrun_idintegerrequired
trail_idintegerrequired
activity_idintegerrequired
course_idintegerrequired
org_idintegerrequired
user_idintegerrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 404 User not found or not a member of this organization
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "id": 1,
  "trail_uuid": "string",
  "org_id": 1,
  "user_id": 1,
  "creation_date": "string",
  "update_date": "string",
  "runs": [
    {
      "id": 1,
      "data": {},
      "status": "STATUS_IN_PROGRESS",
      "trail_id": 1,
      "course_id": 1,
      "org_id": 1,
      "user_id": 1,
      "course": {},
      "creation_date": "string",
      "update_date": "string",
      "course_total_steps": 0,
      "steps": [
        {
          "id": 1,
          "complete": false,
          "teacher_verified": false,
          "grade": "string",
          "data": {},
          "trailrun_id": 1,
          "trail_id": 1,
          "activity_id": 1,
          "course_id": 1,
          "org_id": 1,
          "user_id": 1,
          "creation_date": "string",
          "update_date": "string"
        }
      ]
    }
  ]
}

Get user progress in course

GET/api/v1/admin/{org_slug}/progress/{user_id}/{course_uuid}
API tokenrequired (no session fallback)

Get a user's progress in a specific course including completion percentage and list of completed activity IDs. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

ProgressResponse: Progress summary (completion percentage + completed activity ids).

course_uuidstringrequired
user_idintegerrequired
total_activitiesintegerrequired

Total number of activities in the course

completed_activitiesintegerrequired

Number of activities the user has completed

completion_percentagenumberrequired

Completion percentage (0-100)

completed_activity_idsinteger[]required

IDs of completed activities

Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "course_uuid": "string",
  "user_id": 1,
  "total_activities": 0,
  "completed_activities": 0,
  "completion_percentage": 0,
  "completed_activity_ids": [
    0
  ]
}

Mark activity as completed

POST/api/v1/admin/{org_slug}/progress/{user_id}/activities/{activity_uuid}/complete
API tokenrequired (no session fallback)

Mark an activity as completed on behalf of a user. Automatically creates enrollment if needed. If this completes the entire course, a certificate is awarded (if configured). Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
activity_uuidstringrequired

Returns

ActivityCompletionResponse: Activity marked complete; includes whether this completed the course.

activity_uuidstringrequired
user_idintegerrequired
completedbooleanrequired
is_new_completionbooleanrequired

True if this was a new completion (not already completed)

course_completedbooleanrequired

True if this completion finished the entire course

Error responses
  • 404 Activity not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "activity_uuid": "string",
  "user_id": 1,
  "completed": false,
  "is_new_completion": false,
  "course_completed": false
}

Undo activity completion

DELETE/api/v1/admin/{org_slug}/progress/{user_id}/activities/{activity_uuid}/complete
API tokenrequired (no session fallback)

Remove a user's activity completion. Does not revoke certificates. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
activity_uuidstringrequired

Returns

ActivityUncompletionResponse: Activity completion removed.

activity_uuidstringrequired
user_idintegerrequired
completedboolean
Error responses
  • 404 Activity not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "activity_uuid": "string",
  "user_id": 1,
  "completed": false
}

Mark entire course as completed

POST/api/v1/admin/{org_slug}/progress/{user_id}/{course_uuid}/complete
API tokenrequired (no session fallback)

Mark all activities in a course as completed for a user. Skips activities that are already completed. Awards a certificate if configured. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

CourseCompletionResponse: All activities marked complete; indicates whether a certificate was awarded.

course_uuidstringrequired
user_idintegerrequired
completed_countintegerrequired

Number of newly completed activities

already_completed_countintegerrequired

Number of activities that were already completed

total_activitiesintegerrequired
course_completedbooleanrequired
certificate_awardedbooleanrequired

True if a certificate was awarded as a result

Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "course_uuid": "string",
  "user_id": 1,
  "completed_count": 0,
  "already_completed_count": 0,
  "total_activities": 0,
  "course_completed": false,
  "certificate_awarded": false
}

Get all user progress

GET/api/v1/admin/{org_slug}/progress/{user_id}
API tokenrequired (no session fallback)

Get a progress summary across all courses a user is enrolled in. Returns completion percentage and status for each enrollment. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

ProgressSummaryItem[]: One row per course enrollment with completion percentage and status.

course_uuidstringrequired
course_namestringrequired
statusstringrequired

Enrollment status (STATUS_IN_PROGRESS, STATUS_COMPLETED, etc.)

total_activitiesintegerrequired
completed_activitiesintegerrequired
completion_percentagenumberrequired
enrolled_atstringrequired
Error responses
  • 404 User not found or not a member of this organization
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "course_uuid": "string",
    "course_name": "Example name",
    "status": "string",
    "total_activities": 0,
    "completed_activities": 0,
    "completion_percentage": 0,
    "enrolled_at": "string"
  }
]

Get user trail with full progress breakdown

GET/api/v1/admin/{org_slug}/trails/{user_id}
API tokenrequired (no session fallback)

Return the user's trail in the organization with a full chapter-by-chapter and activity-by-activity progress breakdown for every course they are enrolled in. Each activity carries its completion state, teacher verification flag, grade, and completion timestamp. Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

UserTrailDetail: Full trail breakdown grouped by course → chapter → activity.

trail_uuidstring | null

Null if the user has never started a trail in this org

user_idintegerrequired
org_idintegerrequired
creation_datestring | null
update_datestring | null
coursesTrailCourseProgress[]required
Show child attributes
course_uuidstringrequired
course_idintegerrequired
course_namestringrequired
statusstring | null

TrailRun status (STATUS_IN_PROGRESS, STATUS_COMPLETED, …); null when there is no enrollment row

enrolled_atstring | null

ISO timestamp the user was enrolled; null when there is no enrollment row

total_activitiesintegerrequired
completed_activitiesintegerrequired
completion_percentagenumberrequired
chaptersTrailChapterProgress[]required
Show child attributes
chapter_uuidstringrequired
chapter_idintegerrequired
namestringrequired
orderintegerrequired
total_activitiesintegerrequired
completed_activitiesintegerrequired
activitiesTrailActivityProgress[]required
Show child attributes
activity_uuidstringrequired
activity_idintegerrequired
namestringrequired
activity_typestringrequired
activity_sub_typestringrequired
orderintegerrequired

Order of this activity within its chapter

publishedbooleanrequired
completedbooleanrequired
teacher_verifiedboolean

Whether a teacher has verified the completion (assignments)

gradestring

Grade/feedback recorded on the trail step, when set

completed_atstring | null

ISO timestamp when the activity was marked complete; null if not completed

Error responses
  • 403 API token lacks access to this organization
  • 404 User not found or not a member of this organization
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "trail_uuid": "string",
  "user_id": 1,
  "org_id": 1,
  "creation_date": "string",
  "update_date": "string",
  "courses": [
    {
      "course_uuid": "string",
      "course_id": 1,
      "course_name": "Example name",
      "status": "string",
      "enrolled_at": "string",
      "total_activities": 0,
      "completed_activities": 0,
      "completion_percentage": 0,
      "chapters": [
        {
          "chapter_uuid": "string",
          "chapter_id": 1,
          "name": "Example name",
          "order": 0,
          "total_activities": 0,
          "completed_activities": 0,
          "activities": [
            "…"
          ]
        }
      ]
    }
  ]
}

Get user trail breakdown for a single course

GET/api/v1/admin/{org_slug}/trails/{user_id}/courses/{course_uuid}
API tokenrequired (no session fallback)

Return the user's full chapter-by-chapter and activity-by-activity progress breakdown for a single course. Surfaces progress even when the user has no explicit enrollment row (status will be null in that case). Requires `courses.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

UserTrailDetail: Full breakdown for the requested course only.

trail_uuidstring | null

Null if the user has never started a trail in this org

user_idintegerrequired
org_idintegerrequired
creation_datestring | null
update_datestring | null
coursesTrailCourseProgress[]required
Show child attributes
course_uuidstringrequired
course_idintegerrequired
course_namestringrequired
statusstring | null

TrailRun status (STATUS_IN_PROGRESS, STATUS_COMPLETED, …); null when there is no enrollment row

enrolled_atstring | null

ISO timestamp the user was enrolled; null when there is no enrollment row

total_activitiesintegerrequired
completed_activitiesintegerrequired
completion_percentagenumberrequired
chaptersTrailChapterProgress[]required
Show child attributes
chapter_uuidstringrequired
chapter_idintegerrequired
namestringrequired
orderintegerrequired
total_activitiesintegerrequired
completed_activitiesintegerrequired
activitiesTrailActivityProgress[]required
Show child attributes
activity_uuidstringrequired
activity_idintegerrequired
namestringrequired
activity_typestringrequired
activity_sub_typestringrequired
orderintegerrequired

Order of this activity within its chapter

publishedbooleanrequired
completedbooleanrequired
teacher_verifiedboolean

Whether a teacher has verified the completion (assignments)

gradestring

Grade/feedback recorded on the trail step, when set

completed_atstring | null

ISO timestamp when the activity was marked complete; null if not completed

Error responses
  • 403 API token lacks access to this organization
  • 404 Course or user not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "trail_uuid": "string",
  "user_id": 1,
  "org_id": 1,
  "creation_date": "string",
  "update_date": "string",
  "courses": [
    {
      "course_uuid": "string",
      "course_id": 1,
      "course_name": "Example name",
      "status": "string",
      "enrolled_at": "string",
      "total_activities": 0,
      "completed_activities": 0,
      "completion_percentage": 0,
      "chapters": [
        {
          "chapter_uuid": "string",
          "chapter_id": 1,
          "name": "Example name",
          "order": 0,
          "total_activities": 0,
          "completed_activities": 0,
          "activities": [
            "…"
          ]
        }
      ]
    }
  ]
}

Get user certificates

GET/api/v1/admin/{org_slug}/certifications/{user_id}
API tokenrequired (no session fallback)

Get all certificates awarded to a user in the organization. Includes certification details and course information. Requires `certifications.action_read` permission.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

CertificateItem[]: All certificates awarded to the user in this org.

certificate_userCertificate Userrequired
certificationCertificationrequired
courseCertificateCourseInforequired
Show child attributes
idinteger | null
course_uuidstringrequired
namestringrequired
descriptionstring | null
thumbnail_imagestring | null
Error responses
  • 404 User not found or not a member of this organization
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "certificate_user": {},
    "certification": {},
    "course": {
      "id": 1,
      "course_uuid": "string",
      "name": "Example name",
      "description": "An example description",
      "thumbnail_image": "string"
    }
  }
]

Provision a user

POST/api/v1/admin/{org_slug}/users
API tokenrequired (no session fallback)

Create a user and attach them to the organization in one call. Designed for SSO/JIT provisioning — the user's email is auto-verified and the normal email-verification flow is skipped. If a user with the given email already exists in another organization, they are attached to this org (idempotent); the password/username/name fields in the request are ignored in that case.

Path parameters

org_slugstringrequired

Request bodyapplication/jsonrequired

emailstringrequired
usernamestringrequired
first_namestring
last_namestring
passwordstring | null

Optional — if omitted, treated as SSO user with empty password

role_idinteger

Role id for the org membership (default 4 = student)

extra_metadataExtra Metadata | null

Optional arbitrary JSON metadata attached to the user for headless integrations

Returns

UserRead: User created or attached to the org. Returns the user.

usernamestringrequired
first_namestringrequired
last_namestringrequired
emailstringrequired
avatar_imagestring | null
biostring | null
detailsDetails | null
profileProfile | null
extra_metadataExtra Metadata | null
idintegerrequired
user_uuidstringrequired
email_verifiedboolean
last_login_atstring | null
signup_methodstring | null
is_superadminboolean
Error responses
  • 400 Email already in this org, duplicate username, weak password, or invalid role_id
  • 403 Member limit reached, feature disabled, role belongs to another org, role is elevated (Admin/Maintainer), or token creator lacks privilege
  • 422 Validation Error: HTTPValidationError
  • 429 Too many provisioning requests for this token
Request
Response
{
  "username": "string",
  "first_name": "Example name",
  "last_name": "Example name",
  "email": "ada@example.com",
  "avatar_image": "string",
  "bio": "string",
  "details": {},
  "profile": {},
  "extra_metadata": {},
  "id": 1,
  "user_uuid": "string",
  "email_verified": false,
  "last_login_at": "string",
  "signup_method": "string",
  "is_superadmin": false
}

Update a user's profile

PATCH/api/v1/admin/{org_slug}/users/{user_id}
API tokenrequired (no session fallback)

Update profile fields of an org member. Supports partial updates — only fields present in the request body are changed. Duplicate email/username is rejected.

Path parameters

org_slugstringrequired
user_idintegerrequired

Request bodyapplication/jsonrequired

usernamestring | null
first_namestring | null
last_namestring | null
emailstring | null
avatar_imagestring | null
biostring | null
detailsDetails | null
profileProfile | null

Returns

UserRead: Updated user profile.

usernamestringrequired
first_namestringrequired
last_namestringrequired
emailstringrequired
avatar_imagestring | null
biostring | null
detailsDetails | null
profileProfile | null
extra_metadataExtra Metadata | null
idintegerrequired
user_uuidstringrequired
email_verifiedboolean
last_login_atstring | null
signup_methodstring | null
is_superadminboolean
Error responses
  • 400 Duplicate email or username
  • 404 User not in org
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "username": "string",
  "first_name": "Example name",
  "last_name": "Example name",
  "email": "ada@example.com",
  "avatar_image": "string",
  "bio": "string",
  "details": {},
  "profile": {},
  "extra_metadata": {},
  "id": 1,
  "user_uuid": "string",
  "email_verified": false,
  "last_login_at": "string",
  "signup_method": "string",
  "is_superadmin": false
}

Remove a user from the organization

DELETE/api/v1/admin/{org_slug}/users/{user_id}
API tokenrequired (no session fallback)

Remove a user's organization membership. The user account itself is preserved (it may belong to other orgs). Blocks removing the last admin.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

RemoveUserResponse: Membership removed. The user account is preserved.

detailstringrequired
Error responses
  • 400 User is the last admin
  • 404 User not in org
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string"
}

Look up a user by email

GET/api/v1/admin/{org_slug}/users/by-email/{email}
API tokenrequired (no session fallback)

Find a user by email within the organization. Returns 404 if the user does not exist or is not a member of this org.

Path parameters

org_slugstringrequired
emailstringrequired

URL-encoded email address

Returns

UserRead: The user matching the given email within this org.

usernamestringrequired
first_namestringrequired
last_namestringrequired
emailstringrequired
avatar_imagestring | null
biostring | null
detailsDetails | null
profileProfile | null
extra_metadataExtra Metadata | null
idintegerrequired
user_uuidstringrequired
email_verifiedboolean
last_login_atstring | null
signup_methodstring | null
is_superadminboolean
Error responses
  • 404 User not found in this organization
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "username": "string",
  "first_name": "Example name",
  "last_name": "Example name",
  "email": "ada@example.com",
  "avatar_image": "string",
  "bio": "string",
  "details": {},
  "profile": {},
  "extra_metadata": {},
  "id": 1,
  "user_uuid": "string",
  "email_verified": false,
  "last_login_at": "string",
  "signup_method": "string",
  "is_superadmin": false
}

Issue a magic sign-in link

POST/api/v1/admin/{org_slug}/auth/magic-link
API tokenrequired (no session fallback)

Generate a short-lived URL that, when opened in a browser, will log the target user in and optionally redirect them to a specific path. Token lifetime is clamped to 60–900 seconds.

Path parameters

org_slugstringrequired

Request bodyapplication/jsonrequired

user_idintegerrequired
redirect_tostring | null

Path to redirect to after the user lands on the consume endpoint

ttl_secondsinteger

Token lifetime in seconds (60–900)

Returns

MagicLinkResponse: Magic sign-in URL and underlying JWT. Token lifetime is already clamped.

urlstringrequired

Clickable URL to deliver to the user

tokenstringrequired

Raw JWT (for integrations that prefer to build their own URL)

expires_atstringrequired

ISO8601 timestamp when the token expires

Error responses
  • 400 redirect_to is not a same-origin path
  • 403 User not in this org
  • 404 User not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "url": "https://example.com",
  "token": "string",
  "expires_at": "string"
}

Consume a magic sign-in link (browser-facing)

GET/api/v1/admin/{org_slug}/auth/magic-consume
API tokenrequired (no session fallback)

Public endpoint — no API token required. Validates the magic-link JWT from the query string, sets authentication cookies, and redirects to the target path. On error, renders a friendly HTML page with a support link instead of a raw JSON error.

Path parameters

org_slugstringrequired

Query parameters

tokenstringrequired

Magic-link JWT

Error responses
  • 302 Success — cookies set and redirect to target
  • 410 Token invalid, expired, or user no longer a member (HTML page)
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Bulk enroll users in a course

POST/api/v1/admin/{org_slug}/enrollments/bulk
API tokenrequired (no session fallback)

Enroll a batch of users into a single course. Users who are already enrolled are reported in `already_enrolled`. Users who are not members of the org are reported in `skipped`.

Path parameters

org_slugstringrequired

Request bodyapplication/jsonrequired

course_uuidstringrequired
user_idsinteger[]required

List of user ids to enroll (max 500)

Returns

BulkEnrollResponse: Per-user enrollment summary: enrolled, already_enrolled, skipped.

enrolledinteger[]required

User ids that were newly enrolled

already_enrolledinteger[]required

User ids that already had an enrollment

skippedinteger[]required

User ids that were not members of the org

Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "enrolled": [
    0
  ],
  "already_enrolled": [
    0
  ],
  "skipped": [
    0
  ]
}

List users enrolled in a course

GET/api/v1/admin/{org_slug}/courses/{course_uuid}/enrollments
API tokenrequired (no session fallback)

Reverse lookup: get all users currently enrolled in a course, with pagination. Returns enrollment status and enrolled_at per user.

Path parameters

org_slugstringrequired
course_uuidstringrequired

Query parameters

pageinteger
limitinteger

Returns

CourseEnrollmentItem[]: One row per enrolled user in this course, with status and enrolled_at.

userUserrequired
enrolled_atstringrequired
statusstringrequired
Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "user": {},
    "enrolled_at": "string",
    "status": "string"
  }
]

Reset a user's progress in a course

POST/api/v1/admin/{org_slug}/progress/{user_id}/{course_uuid}/reset
API tokenrequired (no session fallback)

Delete all of a user's trail steps for a course, keeping the enrollment intact. The user can retake the course from scratch.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

ResetProgressResponse: Returns the number of trail steps deleted for this user/course.

course_uuidstringrequired
user_idintegerrequired
steps_deletedintegerrequired
Error responses
  • 404 User or course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "course_uuid": "string",
  "user_id": 1,
  "steps_deleted": 0
}

Manually award a certificate

POST/api/v1/admin/{org_slug}/certifications/{user_id}/{course_uuid}/award
API tokenrequired (no session fallback)

Award a certificate to a user bypassing the normal completion gate. Useful for migrations and manual overrides. The course must have a certification configured.

Path parameters

org_slugstringrequired
user_idintegerrequired
course_uuidstringrequired

Returns

AwardCertificateResponse: Certificate awarded; returns the new user_certification_uuid.

user_certification_uuidstringrequired
user_idintegerrequired
course_uuidstringrequired
Error responses
  • 400 User already has a certificate for this course
  • 404 Course or certification not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "user_certification_uuid": "string",
  "user_id": 1,
  "course_uuid": "string"
}

Revoke a user's certificate

DELETE/api/v1/admin/{org_slug}/certifications/{user_id}/{user_certification_uuid}
API tokenrequired (no session fallback)

Delete a certificate row. Does not affect course enrollment or progress.

Path parameters

org_slugstringrequired
user_idintegerrequired
user_certification_uuidstringrequired

Returns

RevokeCertificateResponse: Certificate revoked. The cert row is hard-deleted.

detailstringrequired
user_certification_uuidstringrequired
Error responses
  • 404 Certificate not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "user_certification_uuid": "string"
}

Add a user to a user group

POST/api/v1/admin/{org_slug}/usergroups/{usergroup_uuid}/members/{user_id}
API tokenrequired (no session fallback)

Add a user to a cohort/group. Both must belong to the token's org.

Path parameters

org_slugstringrequired
usergroup_uuidstringrequired
user_idintegerrequired

Returns

UserGroupMemberResponse: User added to the cohort.

detailstringrequired
usergroup_uuidstringrequired
user_idintegerrequired
Error responses
  • 400 User is already in this group
  • 404 User or group not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "usergroup_uuid": "string",
  "user_id": 1
}

Remove a user from a user group

DELETE/api/v1/admin/{org_slug}/usergroups/{usergroup_uuid}/members/{user_id}
API tokenrequired (no session fallback)

Remove a user's membership from a cohort/group. The user account itself is preserved.

Path parameters

org_slugstringrequired
usergroup_uuidstringrequired
user_idintegerrequired

Returns

UserGroupMemberResponse: User removed from the cohort.

detailstringrequired
usergroup_uuidstringrequired
user_idintegerrequired
Error responses
  • 404 User, group, or membership not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "usergroup_uuid": "string",
  "user_id": 1
}

Change a user's org role

PATCH/api/v1/admin/{org_slug}/users/{user_id}/role
API tokenrequired (no session fallback)

Change the user's role within the organization. Blocks demoting the last admin. The target role must belong to this org or be a global role.

Path parameters

org_slugstringrequired
user_idintegerrequired

Request bodyapplication/jsonrequired

role_idintegerrequired

Target role id

Returns

ChangeRoleResponse: User role updated.

user_idintegerrequired
role_idintegerrequired
Error responses
  • 400 Cannot demote the last admin
  • 403 Role does not belong to this organization
  • 404 User or role not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "user_id": 1,
  "role_id": 1
}

Create a user group

POST/api/v1/admin/{org_slug}/usergroups
API tokenrequired (no session fallback)

Create a cohort/user group owned by the organization.

Path parameters

org_slugstringrequired

Request bodyapplication/jsonrequired

namestringrequired
descriptionstring

Returns

UserGroupResponse: The newly created cohort.

idintegerrequired
org_idintegerrequired
usergroup_uuidstringrequired
namestringrequired
descriptionstringrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "id": 1,
  "org_id": 1,
  "usergroup_uuid": "string",
  "name": "Example name",
  "description": "An example description",
  "creation_date": "string",
  "update_date": "string"
}

Delete a user group

DELETE/api/v1/admin/{org_slug}/usergroups/{usergroup_uuid}
API tokenrequired (no session fallback)

Delete a user group and all its memberships and course links. The underlying users and courses are untouched.

Path parameters

org_slugstringrequired
usergroup_uuidstringrequired

Returns

DeleteUserGroupResponse: Cohort and all its memberships/course links deleted.

detailstringrequired
usergroup_uuidstringrequired
Error responses
  • 404 UserGroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "usergroup_uuid": "string"
}

List members of a user group

GET/api/v1/admin/{org_slug}/usergroups/{usergroup_uuid}/members
API tokenrequired (no session fallback)

Reverse lookup: list users belonging to a cohort, with pagination.

Path parameters

org_slugstringrequired
usergroup_uuidstringrequired

Query parameters

pageinteger
limitinteger

Returns

UserGroupMemberListItem[]: Members of the cohort, paginated.

userUserrequired
added_atstringrequired
Error responses
  • 404 UserGroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "user": {},
    "added_at": "string"
  }
]

List user groups a user belongs to

GET/api/v1/admin/{org_slug}/users/{user_id}/groups
API tokenrequired (no session fallback)

Reverse lookup: which cohorts is this user a member of?

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

UserUserGroupItem[]: Cohorts the user belongs to within this org.

usergroupUsergrouprequired
added_atstringrequired
Error responses
  • 404 User not in org
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "usergroup": {},
    "added_at": "string"
  }
]

Grant a cohort access to a course

POST/api/v1/admin/{org_slug}/usergroups/{usergroup_uuid}/courses/{course_uuid}
API tokenrequired (no session fallback)

Link a course to a user group — all members of the group gain the access rights configured for that group.

Path parameters

org_slugstringrequired
usergroup_uuidstringrequired
course_uuidstringrequired

Returns

UserGroupCourseResponse: Course linked to the cohort.

detailstringrequired
usergroup_uuidstringrequired
course_uuidstringrequired
Error responses
  • 400 Course already linked to this group
  • 404 Group or course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "usergroup_uuid": "string",
  "course_uuid": "string"
}

Revoke a cohort's access to a course

DELETE/api/v1/admin/{org_slug}/usergroups/{usergroup_uuid}/courses/{course_uuid}
API tokenrequired (no session fallback)

Unlink a course from a user group. Members of the cohort lose access unless granted through another path.

Path parameters

org_slugstringrequired
usergroup_uuidstringrequired
course_uuidstringrequired

Returns

UserGroupCourseResponse: Course unlinked from the cohort.

detailstringrequired
usergroup_uuidstringrequired
course_uuidstringrequired
Error responses
  • 404 Group or link not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "usergroup_uuid": "string",
  "course_uuid": "string"
}

Full GDPR data export for a user

GET/api/v1/admin/{org_slug}/users/{user_id}/export
API tokenrequired (no session fallback)

Return a JSON bundle containing the user's profile, org memberships, trails, runs, steps, certificates, and cohort memberships. Intended for GDPR Article 15 (Right of Access) compliance. All sub-collections are scoped to the caller's org.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

UserDataExportResponse: Bundle of all user data scoped to this org.

profileProfilerequired

The user's profile (scrubbed of sensitive fields)

membershipsobject[]required

Org memberships scoped to the caller's org

trailsobject[]required

Learning trails in the caller's org

trail_runsobject[]required

Course enrollments / trail runs

trail_stepsobject[]required

Activity completions

certificatesobject[]required

Certificates awarded in the caller's org

user_groupsobject[]required

Cohort memberships in the caller's org

exported_atstringrequired

ISO8601 timestamp when the export was generated

Error responses
  • 404 User not in org
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "profile": {},
  "memberships": [
    {}
  ],
  "trails": [
    {}
  ],
  "trail_runs": [
    {}
  ],
  "trail_steps": [
    {}
  ],
  "certificates": [
    {}
  ],
  "user_groups": [
    {}
  ],
  "exported_at": "string"
}

GDPR right-to-be-forgotten

POST/api/v1/admin/{org_slug}/users/{user_id}/anonymize
API tokenrequired (no session fallback)

Scrub a user's PII (email, name, avatar, bio, details, profile, password). Delete API tokens the user created. Keeps trails and certificates so course analytics remain accurate. Invalidates session cache.

Path parameters

org_slugstringrequired
user_idintegerrequired

Returns

AnonymizeUserResponse: User PII scrubbed; reports how many API tokens were revoked.

detailstringrequired
user_idintegerrequired
anonymized_emailstringrequired
api_tokens_revokedintegerrequired
Error responses
  • 404 User not in org
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "detail": "string",
  "user_id": 1,
  "anonymized_email": "ada@example.com",
  "api_tokens_revoked": 0
}

Aggregate stats for a course

GET/api/v1/admin/{org_slug}/courses/{course_uuid}/analytics
API tokenrequired (no session fallback)

Returns enrollment/completion counts, average completion percentage across all enrollees, and total certificates awarded.

Path parameters

org_slugstringrequired
course_uuidstringrequired

Returns

CourseAnalyticsResponse: Aggregate course stats: enrollment, completion, certificates, etc.

course_uuidstringrequired
enrollment_countintegerrequired
completed_countintegerrequired
in_progress_countintegerrequired
total_activitiesintegerrequired
average_completion_percentagenumberrequired
certificate_countintegerrequired
Error responses
  • 404 Course not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "course_uuid": "string",
  "enrollment_count": 0,
  "completed_count": 0,
  "in_progress_count": 0,
  "total_activities": 0,
  "average_completion_percentage": 0,
  "certificate_count": 0
}