Developer Guides

Deep-dive into everything you need to build integrations, tools, and apps on top of the HouseLearning ecosystem — from authentication to webhooks, from performance tuning to advanced API usage.

Authentication

Learn how to authenticate users and protect API routes safely.

Fetching Data

Query lessons, users, analytics, and more using REST endpoints.

Webhooks

React to real-time events like new lessons, profile changes, and analytics updates.

SDK Usage

Optional JavaScript helper functions for working with the API.

Rate Limits

Understand how rate limiting works and how to stay efficient.

Error Handling

Properly detect and respond to API error states.

Authentication

Authenticating with the HouseLearning API is simple: send the user’s token in the Authorization header.

GET /api/v1/user/me
Authorization: Bearer <token>

Tokens expire every 24 hours. Refresh tokens last 30 days.

Fetching Data

You can fetch any model using the REST endpoints. Here's a basic lesson fetch:

GET /api/v1/lessons?id=LSN-103
Authorization: Bearer <token>

Webhooks

Webhooks notify your server in real time when certain events occur.

user.created
user.updated
lesson.published
lesson.updated
analytics.hit

{
  "event": "lesson.published",
  "timestamp": "2024-04-10T18:21:00Z",
  "lessonId": "LSN-103"
}

SDK Usage

The optional SDK speeds up development:

import { HL } from "houselearning-sdk";

const hl = new HL("your_api_key");

const user = await hl.user.me();

Rate Limits

HouseLearning uses a rolling 1-minute window:

100 requests/min — Free Tier
600 requests/min — Pro Tier
Unlimited* — Enterprise

Error Handling

All errors follow a consistent schema:

{
  "error": true,
  "code": 403,
  "message": "Missing or invalid token"
}