Build

API reference

Every Lectern resource follows the same conventions: REST, JSON, cursor pagination, predictable errors, idempotent writes.

Conventions

Before diving into resources, three patterns worth committing to memory:

Pagination - cursor-based via ?starting_after=<id> and ?limit=N. Responses include next_cursor and has_more.
Idempotency - pass an Idempotency-Key header on writes; we cache responses for 24 hours per key, so retries are safe.
Soft archive- most resources can’t be hard-deleted. DELETEarchives them; data is retained per your tenant’s POPIA settings.

Pagination

List endpoints return up to 25 records by default, max 100. Page forward with the cursor from the previous response.

cURLPaginating learners

Copy

$ curl "https://api.lectern.school/v1/learners?limit=50&starting_after=lrn_8aJ4F" \
    -H "Authorization: Bearer sk_live_lectern_…"

Response200 OK

application/json

{
  "data": [...],
  "next_cursor": "lrn_8aJ4G",
  "has_more": true
}

Idempotency

Send Idempotency-Key: <uuid> on any write request. Lectern stores the response for 24 hours; identical retries return the same result without performing the operation twice.

Resources

Click through to each resource for the full schema, every endpoint, and example payloads.

Learners12 endpoints

Student records, enrollments, guardians, medical notes.

Staff9 endpoints

Teachers, admins, invitations, roles, qualifications.

Classes11 endpoints

Grade levels, subjects, classes, enrollments per term.

Timetable7 endpoints

Slots, periods, room assignments, teacher allocations.

Attendance6 endpoints

Daily attendance, tardiness, excused absences.

Assessments14 endpoints

Assessments, grades, term reports, publishing.

Finance18 endpoints

Invoices, payments, bursaries, ledger entries.

Discipline5 endpoints

Behavior incidents, follow-ups, parent notifications.

Communication8 endpoints

Announcements, parent comms, message templates.

Audit log3 endpoints

Read-only access to every change ever made in your tenant.

A worked example

Updating a single learner’s grade level demonstrates the full pattern - PATCH for partial updates, idempotency on writes, and the soft-archive convention:

cURLPATCH /v1/learners/{id}

Copy

$ curl -X PATCH https://api.lectern.school/v1/learners/lrn_8aJ4F \
    -H "Authorization: Bearer sk_live_lectern_…" \
    -H "Lectern-Version: 2026-01-01" \
    -H "Idempotency-Key: 5f3c0e2a-9b2d-4a8e-bf45-c6d7e890fa12" \
    -d '{"grade_level": "11", "class":         "11A"}'

Response200 OK

application/json

{
  "id": "lrn_8aJ4F",
  "name": "Sipho Dlamini",
  "grade_level": "11",
  "class": "11A",
  "updated_at": "2026-05-07T11:42:08Z"
}