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 — typical for 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.