Build a Learning Platform
LearnHouse is API-first. The official web app is just one client of a public REST API — which means you can build your own learning platform on top of the same API, with your own design, your own routing, and your own brand.
This guide takes you from an empty folder to a working headless learning platform: a Next.js app that lists your courses, plays your content, signs users in, enrolls them, and tracks their progress — all powered by the LearnHouse API. It’s the kind of result you’ll find in the learnhouse/headless-examples repository.
Pick your path
- Do it yourself — Follow the build step by step. Every command and file is provided, and the whole thing is tested end to end. This is the best way to actually understand how the API fits together.
- Let an agent build it — Hand a coding agent (Claude Code, Cursor, etc.) a self-contained spec and let it generate the app for you, then review and run it.
What you’ll build
A learning platform you reach in two stages — anonymous first, authenticated second. You’ll have a working public site before you touch a single token.
Stage 1 — Anonymous
No login, no tokens. Public content only:
- A course catalogue listing every public course in your organization.
- A course page showing chapters and activities.
- An activity viewer that renders dynamic pages, videos, and documents.
Architecture
Your Next.js app is a thin, fast client in front of the LearnHouse API. Reads happen in Server Components; anything involving a token goes through a Route Handler acting as a Backend-for-Frontend (BFF), so LearnHouse tokens never reach the browser. Media is streamed straight from the API’s content-delivery endpoint.
Reads happen in Server Components; anything with a token goes through a Route Handler acting as a Backend-for-Frontend, so tokens never reach the browser. Media (thumbnails, video, files) streams directly from the backend's content-delivery endpoint at /content/… (served at the root, not under /api/v1).
Using a server-side BFF isn’t just for security — it also sidesteps CORS entirely. Your browser only ever talks to your own Next.js origin, and your server talks to LearnHouse.
The resources you’ll touch
Everything in LearnHouse hangs off an Organization. Content is a tree of Course → Chapter → Activity. A learner’s progress is a separate tree: each User has a Trail, which holds a Run per enrolled course, which holds a Step per completed activity.
The two chains connect through enrollment: a Run records a learner's enrollment in a Course, and each Step records completion of an Activity.
| Resource | What it is | Key endpoint |
|---|---|---|
| Organization | Top-level tenant, addressed by org_slug | GET /api/v1/orgs/slug/{org_slug} |
| Course | A course, addressed by course_uuid | GET /api/v1/courses/org_slug/{org_slug}/page/{page}/limit/{limit} |
| Chapter + Activity | The course’s content tree | GET /api/v1/courses/{course_uuid}/meta |
| Trail / Run / Step | A learner’s enrollment & progress | GET /api/v1/trail/org/{org_id}/trail |
Prerequisites
- Node.js 18+ and a package manager (
npm,pnpm, orbun). - A running LearnHouse instance. Spin one up locally with the Quickstart or self-hosting guide, or use LearnHouse Cloud . The examples assume the API is at
http://localhost:1338. - Your organization slug and at least one public, published course with some content. Create one in the dashboard if you don’t have it yet.
- Basic familiarity with the API Reference.
Throughout this guide the API base URL is http://localhost:1338/api/v1. If your instance lives elsewhere (a custom port, a domain, or Cloud), substitute your own base URL — every example reads it from a single environment variable.
Ready? Head to Do It Yourself to start building, or Let an Agent Build It to delegate.
