Migrating Content into LearnHouse

This section explains how to bring existing course content into LearnHouse using the public API. There are two supported approaches:

1. Programmatic Migration: you script every step (create the course, then chapters, then activities, then upload files). Use this when you need full control of the resulting structure. This is typical when migrating from another LMS where you already know the chapter/activity layout.
2. AI-Assisted Migration: you upload a folder of media (videos, PDFs, images, audio) and LearnHouse asks Gemini to propose a chapter/activity tree. You review and confirm, and a single endpoint creates the entire course in one transaction. Use this when you have a pile of files but no predefined structure.

Both approaches share the same underlying data model: a Course contains Chapters, and each Chapter contains an ordered list of Activities.

Authentication

Every migration call must be authenticated. There are two token types:

• JWT access tokens (POST /api/v1/auth/login): a user session, 8-hour lifetime, refreshable.
• API tokens (Pro plan): prefixed with lh_, issued per organization, no expiry.

Both are sent the same way:

curl http://localhost:1338/api/v1/courses/?org_id=1 \
  -H "Authorization: Bearer lh_your_api_token_here"

API tokens are bound to a single organization at creation time. Any attempt to operate on a different org_id is rejected at the auth layer, so a leaked token cannot reach across tenants.

# Mint a user JWT using your API token
curl -X POST 'http://localhost:1338/api/v1/admin/{org_slug}/auth/token' \
  -H 'Authorization: Bearer lh_your_api_token' \
  -H 'Content-Type: application/json' \
  -d '{"user_id": 1}'
# → { "access_token": "eyJ...", "token_type": "bearer", "user_id": 1, "user_uuid": "..." }

The blocks router has Depends(get_non_api_token_user) at the router level, so even though individual block handlers accept anonymous + JWT users, an lh_* API token is rejected with 403 "API tokens cannot access this resource". The same is true for the AI-assisted migration endpoints. For both, use the admin token-swap to mint a JWT first (see callout above).

See Authentication for token issuance.

The data model in one diagram

Organization (org_id)
└── Course (course_uuid, course_id)
    └── Chapter (chapter_uuid, chapter_id)
        └── Activity (activity_uuid, activity_id)
            └── (optional) Block (block_uuid)  ← media files referenced from a dynamic page

Two ID conventions to keep straight:

• *_uuid strings (e.g. course_uuid, activity_uuid, chapter_uuid) are the public identifiers used in URLs and most GET endpoints.
• *_id integers (e.g. course_id, chapter_id) are the internal primary keys. They are required when creating a child resource (a chapter needs course_id, an activity needs chapter_id).

Both are returned in every create response, so capture them as you go.

Activity types at a glance

The full per-type content JSON schemas, including the dynamic page block list, are documented in Activity Types Reference.

Quick start: the four building blocks

A complete migration boils down to four call types, in order:

1. Create a course. POST /api/v1/courses/?org_id={org_id} (multipart). Capture course_uuid and id from the response.
2. Create chapters. POST /api/v1/chapters/ (JSON), one per chapter, passing course_id and org_id. Capture each chapter’s id.
3. Create activities. Either the generic POST /api/v1/activities/ (JSON, for dynamic / embed / markdown / custom / assignment shells) or one of the typed endpoints /activities/video, /activities/external_video, /activities/documentpdf (multipart, for hosted media).
4. (Optional) Upload media blocks referenced from a dynamic page via /api/v1/blocks/{image,video,pdf,audio} (multipart) and embed them in the page’s TipTap content.

A copy-pasteable bash script for the full flow lives in Programmatic Migration.

Common pitfalls

Where to next

• Programmatic Migration: step-by-step guide with curl examples for each call.
• Activity Types Reference: the exact content JSON shape for every activity sub-type, including TipTap blocks for dynamic pages.
• AI-Assisted Migration: the three-call upload / suggest / create flow for bulk file imports.