Quickstart

Prerequisites

You’ll need a Lectern tenant to authenticate against. If you don’t have one yet, start a free trial - provisioning takes about a minute. You’ll also need a terminal with curl on it (Node and Python examples are alongside on every page).

1. Create a tenant

After signing up, you’ll land on https://app.lectern.school/dashboard/<school-id>. The school ID is yours forever - it appears in API URLs and in every audit-log entry. Bookmark it.

2. Mint an API token

Open Settings → API in the dashboard and click Create token. Name it after the integration you’re building (e.g. terminus-import-2026) and pick a scope set. Tokens look like sk_live_lectern_…; treat them as secrets.

3. Make your first request

The API base URL is https://api.lectern.school/v1. Every request carries a bearer token and an explicit version header. Here’s the smallest call you can make - listing the schools the token can see:

$ curl https://api.lectern.school/v1/schools \
    -H "Authorization: Bearer sk_live_lectern_…" \
    -H "Lectern-Version: 2026-01-01"

{
  "data": [
    {
      "id": "sch_lectern_demo",
      "name": "St. Cuthbert's Academy",
      "tenant_type": "single",
      "created_at": "2026-01-12T08:14:22Z"
    }
  ],
  "has_more": false
}

If you got 200 OK, you’re wired up. Failures return JSON with a stable error.code - see Errors.

4. List your learners

Most reads are paginated with cursors. Pass ?limit=50&starting_after=<id> to page through. The default page size is 25 records.

$ curl https://api.lectern.school/v1/learners?limit=2 \
    -H "Authorization: Bearer sk_live_lectern_…" \
    -H "Lectern-Version: 2026-01-01"

{
  "data": [
    {
      "id": "lrn_8aJ4F",
      "name": "Sipho Dlamini",
      "grade_level": "10",
      "class": "10A"
    }
  ],
  "next_cursor": "lrn_8aJ4F",
  "has_more": true
}

5. Listen for events

Webhooks deliver real-time events - learner enrolled, fee reconciled, term report published. Register an endpoint in Settings → API → Webhooks or via the API:

$ curl https://api.lectern.school/v1/webhooks \
    -H "Authorization: Bearer sk_live_lectern_…" \
    -H "Lectern-Version: 2026-01-01" \
    -d '{"url": "https://hooks.example.com/lectern",         "events": ["learner.enrolled", "fee.reconciled"]}'         

Lectern signs every payload with HMAC-SHA256 using a shared secret. See Webhooks → Signing for how to verify.

What’s next?

You’re past the hard part. From here:

1. Read Authentication for scopes, rotation, and rate limiting.
2. Browse the API reference for every resource - Learners, Staff, Classes, Assessments, Attendance, Finance.
3. If you’re migrating from another system, see Data import & export.