Rate limits & pagination
Limits apply to specific endpoints (sign-in, token creation, search, provisioning), not to the API as a whole. List endpoints page with page and limit, or offset and limit.
Rate-limited endpoints
These limits are enforced by the open-source API with fixed windows stored in Redis. Endpoints that are not listed have no per-endpoint limit in the API itself; your hosting (a proxy, LearnHouse Cloud's edge) may add its own.
| Action | Endpoints | Limit | Counted per |
|---|---|---|---|
| Sign in | POST /auth/loginPOST /auth/magic-link/request | 30 per 5 minutes | IP address |
| Refresh a session | GET /auth/refresh | 600 per minute | IP address |
| Verify an email | POST /auth/verify-email | 5 per 5 minutes | email address |
| Sign up | POST /users/POST /users/{org_id}POST /users/{org_id}/invite/{invite_code} | 10 per hour | IP address |
| Accept an invite code | POST /users/{org_id}/invite/{invite_code} | 20 per 15 minutes | IP address and organization |
| Password reset | POST /users/reset_password/… | 5 per 5 minutes | email address |
| Create or regenerate an API token | POST /orgs/{org_id}/api-tokensPOST /orgs/{org_id}/api-tokens/{token_uuid}/regenerate | 10 per hour | IP address |
| Create or test a webhook | POST /orgs/{org_id}/webhooksPOST /orgs/{org_id}/webhooks/{webhook_uuid}/test | 20 per hour | organization, per action |
| Search | GET /search/org_slug/{org_slug}GET /folders/org/{org_id}/search | 60 per minute | user (a token counts as its creator) |
| Provision a user (headless) | POST /admin/{org_slug}/users | 30 per minute | API token |
| Look up a user by email (headless) | GET /admin/{org_slug}/users/by-email/{email} | 60 per minute | API token |
| Send org invites | Invite endpoints under /orgs | 100 per day | organization, and per inviting user |
When you hit a limit
The API answers 429 Too Many Requests. How long to wait comes either as a Retry-After header (seconds) or, on the sign-in endpoints, as detail.retry_after next to the RATE_LIMITED code. Wait at least that long before trying again; retrying sooner does not reset the window.
{
"detail": {
"code": "RATE_LIMITED",
"message": "Too many login attempts. Please try again in 4 minutes.",
"retry_after": 263
}
}The SDK does not retry 429 for you: it retries only GET requests on network errors, timeouts and 5xx. Catch the LearnHouseError and check err.status === 429. See Errors.
Batch sizes
Endpoints that take a list of users or resources in one call (adding users to a group, adding course contributors, removing org members) accept at most 100 items per request; more returns 400 with code BATCH_TOO_LARGE and the cap in max_batch_size. Invites are capped at 25 emails per request.
Pagination
There are no cursors. Most list endpoints return a plain array; a few (search, org members, submissions) return an object, so check the endpoint's response schema. page starts at 1, offset at 0. With arrays, keep requesting the next page until you get fewer items than limit. Endpoints use one of three styles:
- Path segments,
…/page/{page}/limit/{limit}(6 endpoints). - Query parameters,
?page=1&limit=10(7 endpoints). Where the schema sets a maximum, it is shown below. - Offset,
?offset=0&limit=20(3 endpoints).
# page 2, 20 courses per page
curl "https://api.learnhouse.io/api/v1/courses/org_slug/your-school/page/2/limit/20" \
-H "Authorization: Bearer lh_YOUR_API_TOKEN"curl "https://api.learnhouse.io/api/v1/search/org_slug/your-school?query=python&page=1&limit=10" \
-H "Authorization: Bearer lh_YOUR_API_TOKEN"// Fetch every course, 50 at a time, until a short page comes back.
const all = [];
for (let page = 1; ; page++) {
const batch = await lh.GET("/api/v1/courses/org_slug/{org_slug}/page/{page}/limit/{limit}", {
params: { path: { org_slug: "your-school", page, limit: 50 } },
});
all.push(...batch);
if (batch.length < 50) break;
}