Getting started

Base URL https://api.samas.school/v1 (beta, demo schools only: https://api-beta.samas.school/v1). Send JSON with Content-Type: application/json. Every response uses the same envelope: { "data": ..., "meta": { "request_id", "generated_at" } }, lists add page, errors return { "error": { "code", "message", "hint", "field", "request_id" } }.

Writes accept an Idempotency-Key header; recording a payment requires one. Unknown fields are rejected, strings have length limits, and every rule is listed next to its field in the reference. Machine-readable documents: me.json, school.json, also served at https://api.samas.school/v1/openapi/<api>.json.

School integrations get a key from the school admin under Settings, API keys. The office and platform APIs are internal and not documented here.

New here? Start with the Getting started guide, then the step-by-step guides for handing in homework, applying for admission, messages, permission slips, reporting a problem and importing students under Guides.

API data validation rules

Applies to every saMas School API (Student, School, Admin, Finance, Platform, Ops). The gateway validates every request against the OpenAPI document for its API before anything reaches the database; the database enforces the same rules again in its constraints and functions, so a rule cannot be bypassed by calling the database directly. When the two disagree, the database wins and the gateway is fixed.

The rule of thumb: strict on shape, lenient on presentation. A field is rejected when its meaning is ambiguous or its value is impossible. A field is normalised, never rejected, when the value is clearly right but written differently (spaces in a phone number, a trailing space in a name, an upper-case email). Every normalisation is listed here; anything not listed is not done.

1. Request envelope

Content type must be application/json; charset=utf-8 for every request with a body. Any other content type is rejected with 415 UNSUPPORTED_MEDIA_TYPE. Bodies must parse as a JSON object at the top level (never an array or scalar), except where the schema says an array (bulk marks, timetable draft, periods). Body size limit is 1 MB; file bytes never travel through the API (signed URLs instead). A malformed body is 400 MALFORMED_JSON with the parser position in hint.

Unknown fields are rejected, not ignored: every request object is additionalProperties: false. The error names the field (400 UNKNOWN_FIELD, hint: "field 'notes2' is not accepted here"). This is deliberate: a misspelt optional field silently dropped is how data goes missing.

Missing required fields are 400 MISSING_FIELD. Explicit null is accepted only where the schema lists null in the type; elsewhere null is INVALID_TYPE. An empty string is not the same as absent: for optional text fields the API treats "" as "clear this value" on PATCH and as absent on POST.

Duplicate keys in a JSON object are rejected (MALFORMED_JSON); the last-wins behaviour of most parsers is a source of injection bugs.

2. Headers

Authorization: Bearer <token> or X-Api-Key: <key>, exactly one. Both present is 400 AMBIGUOUS_CREDENTIALS. Tokens and keys are opaque; whitespace around them is trimmed; anything else is passed to the verifier untouched.

Idempotency-Key: 1 to 64 characters from A-Za-z0-9_- (anything else is 400 INVALID_CODE with field: /header/Idempotency-Key). Scoped to the caller (a key or a person) and to the route. A retry with the same key and the same body returns the stored response with Idempotent-Replayed: true; the same key with a different body is 409 IDEMPOTENCY_MISMATCH. Keys live 24 hours. On the School API it is required for POST /school/payments; elsewhere optional but honoured.

X-Request-Id: 1 to 64 characters from A-Za-z0-9_- (else 400 INVALID_CODE); echoed back. If absent the gateway makes one (UUID v4) and returns it. It appears in every error body.

Accept-Language: en or ur; anything else falls back to en. Affects only error.message, never error.code. Messages are English today; ur is accepted so clients can send it now.

3. Path and query parameters

Path ids are UUIDs (RFC 4122, any version, lower or upper case; returned lower case). Anything else is 400 INVALID_ID, not 404, so a client learns the difference between "you sent garbage" and "not visible to you".

Query parameters are strings by definition, so each has an exact grammar:

Unknown query parameters are rejected (400 UNKNOWN_PARAMETER). This is stricter than most APIs; it catches ?stauts= typos that would otherwise return the whole list.

Filters combine with AND. A filter that names an object the caller cannot see (a class_id from another school) is not an error: it simply matches nothing, so existence is never revealed.

4. Field families

Every request field belongs to one family below. The family sets the rule; the OpenAPI document repeats it as pattern, minLength, maxLength, minimum, maximum or enum so generated clients validate before sending.

Identifiers

UUID strings. Accepted in either case; stored and returned lower case. Never generated by the client; a client-supplied id in a create body is UNKNOWN_FIELD.

Codes and numbers the school reads

admission_no: 2 to 20 characters from A-Za-z0-9-, unique in the school, immutable after enrolment (PATCH with a different value is 409 IMMUTABLE_FIELD). section.name: one capital letter then up to 3 capitals or digits (A, B2); lower case is normalised to upper. fee_head.code and subject.code: upper-case letters, digits and underscore or hyphen, 2 to 12; lower case is normalised to upper. school.code: A-Z0-9-, 2 to 12, unique on the platform. Invoice and receipt numbers are never accepted as input; the server issues them.

Names

full_name, class names, family account names: 2 to 80 characters, letters, spaces, apostrophes and hyphens. Leading and trailing whitespace trimmed; runs of spaces collapsed; Unicode letters are accepted (Urdu names are common) but digits and symbols are not. Class names allow digits (Grade 5). Everything is stored as sent after normalisation; no title-casing, because Abdul Rehman and ABDUL rehman are both real spellings people chose.

Phone numbers

Accepted in any of: +92 300 0000000, +92-300-0000000, 0300 0000000, 03000000000, +923000000000. Normalised to E.164 (+923000000000): spaces, hyphens, dots and parentheses are removed; a leading 0 with no country code becomes the school's default country (+92 unless the school setting says otherwise); a leading 00 becomes +. Rejected if, after normalisation, it is not + followed by 7 to 15 digits, or the country code is not a real one (INVALID_PHONE). This is the one place the API is deliberately forgiving, because the alternative is parents locked out by a formatting habit.

Email

Lower-cased; whitespace trimmed. Must match one @, a non-empty local part up to 64 characters, a domain with at least one dot and a 2 to 24 letter top level. Display-name forms ("Ali" <[email protected]>) are rejected. Uniqueness per school is enforced on invite.

Identity number (CNIC)

Exactly 00000-0000000-0 (five digits, seven digits, one digit). The API also accepts the 13 digits without hyphens and inserts them; nothing else (INVALID_CNIC). Never appears in any list or search; never logged with its value; only reachable through the identity endpoints.

Dates and times

Dates are YYYY-MM-DD and must be real calendar dates (2026-02-30 is INVALID_DATE). Timestamps are RFC 3339 with an offset; the API returns UTC. Business rules on dates: date_of_birth between 2 and 25 years before today and, when the class has an age range, inside it (AGE_OUT_OF_RANGE, hint says the range); paid_on not after today in the school's timezone (FUTURE_DATE); on_date for attendance not after today and not before the academic year start; held_on within the academic year; valid_to not before valid_from; ends_at not before starts_at; expires_at after publish_at. "Today" is computed in the school's timezone setting, never in UTC, so a payment at 11 pm Karachi time is not "tomorrow".

Money

A string, digits, one dot, exactly two decimals: "12500.00". Rejected: numbers (JSON 12500), commas, currency symbols, more or fewer decimals, negative values except where the schema says an amount may be negative (invoice items, which the API never accepts as input anyway). Range 0.00 to 10000000.00. Currency is a separate 3-letter upper-case code and must equal the school's currency for every write (CURRENCY_MISMATCH); multi-currency is not supported and will not be silently converted. Why a string: JSON numbers are floating point in every mainstream client, and 0.1 plus 0.2 is a real bug in fee software.

Percentages

percent: number, greater than 0, at most 100, at most two decimals. second_approval_percent: 0 to 100.

Integers with ranges

capacity 1 to 60; roll_no 1 to 999; periods_per_week 1 to 10; max_marks 1 to 1000; marks 0 to max_marks of that column (MARKS_TOO_HIGH); due_day 1 to 28 (so every month has it); late_fee_after_days 0 to 60; days_overdue 0 to 180; weekday 1 to 7 with 1 as Monday; period_no 1 to 12, and 0 only on attendance where it means the whole day; size_bytes up to 5242880. Integers must be JSON integers; "5" is INVALID_TYPE.

Enumerations

Exact lower-case tokens as listed in the schema. No synonyms (partially_paid is not part_paid), no case folding, no numeric codes. An unknown value gets INVALID_ENUM with the allowed values in hint.

Free text

reason fields: 3 to 300 characters (5 to 500 for flags and disputes, 5 to 300 for discounts and holds). notes 500 on invoices and students, 300 on payments, 2000 on confidential notes. title 3 to 120 and body 10 to 4000 on announcements. template 10 to 600 with only the four placeholders {student}, {invoice}, {amount}, {due_date} allowed; any other {...} is INVALID_TEMPLATE. All free text: trimmed; control characters other than newline and tab removed; NFC normalised; no HTML interpretation anywhere (text is text; clients escape on render). Emoji are allowed.

Arrays

student_ids on a proof: 1 to 8 UUIDs, no duplicates, all from one family (MIXED_FAMILIES). invoice_ids on a payment: 0 to 50, all belonging to the named family and all open (INVOICE_NOT_OPEN). events on a webhook: 1 to all known events, no duplicates. rows on an attendance register: exactly the students of that section, each once (REGISTER_INCOMPLETE lists the missing ids; UNKNOWN_STUDENT lists the extra ones). Bulk marks: at most the students of the section. Every array has maxItems in the schema; the hard ceiling anywhere is 500.

Files

Every file goes to storage through a signed upload address, never through the API: declare the file (POST .../upload-url), PUT the bytes there with the same Content-Type within 15 minutes, then name the upload_id in the write. Homework, messages, admissions and staff documents take JPEG, PNG, WebP, PDF and Office files up to 20 MB (HomeworkUpload); a problem report's screenshot takes PNG, JPEG or WebP up to 5 MB; branding images up to 2 MB. A type outside the list is INVALID_ENUM, a size outside the range OUT_OF_RANGE, and more files than the field allows TOO_MANY.

Payment proofs are declared before upload: content_type one of image/jpeg, image/png, image/webp, application/pdf; size_bytes 1 to 5 MB; sha256 64 lower-case hex characters. The signed upload URL is bound to that content type and size; storage rejects a mismatch. After upload the server recomputes the hash; a mismatch is 409 CHECKSUM_MISMATCH and the proof is not created. Images are not resized or re-encoded by the API (the office wants the original slip). File names are never accepted from the client; the server names the object.

URLs (webhooks)

https:// only, no credentials in the URL, no private or link-local addresses (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16, IPv6 equivalents), no ports other than 443 unless the platform allow-lists the host. Verified once at creation by a signed ping event that the endpoint must answer with 2xx within 5 seconds (WEBHOOK_UNREACHABLE).

5. Business rules the API states up front

These are validated at the database and surface as 409 with the code shown, so a client can show the right message without parsing text.

6. Where the API is lenient, and why

Phone formatting (section 4), because parents type numbers the way their phone shows them. Upper and lower case in codes and UUIDs, because those are machine values with no meaning in case. Whitespace at the edges of text, because copy and paste adds it. The 13-digit CNIC without hyphens, because the national database prints it both ways. Dates for fee_month and period on any day of the month, because a client that says "September" may send the 15th. Nothing else. In particular the API does not guess a date format (01/02/2026 is rejected, not parsed), does not coerce strings to numbers or numbers to strings, does not accept synonyms for enum values, and does not drop unknown fields.

7. How a validation error is reported

One error per response, the first found, in this order: content type, JSON syntax, credentials, unknown fields and parameters, missing required fields, type and format per field in schema order, then business rules. error.field carries a JSON pointer (/rows/3/status, /query/size) so a form can highlight the input. error.hint is written for the person: what was expected, with the allowed values or range. See response-format.md for the envelope and schemas/error-codes.json for the full catalogue with HTTP statuses and whether a retry can help.

API response format

Every saMas School API answers with the same envelope, the same error shape and the same headers. There are six documents, all built from openapi/build.py and all served by one gateway under https://api.samas.school/v1: the Student API (/me, public), the School API (/school, public), and the internal Admin (/admin), Finance (/finance), Platform (/platform) and Ops (/ops) APIs. The machine-readable form of the envelope is schemas/envelope.schema.json (JSON Schema 2020-12) and every document references the same components. Clients should validate responses against the schema in their tests; the gateway checks its own responses against the contract in its tests and on staging, and logs any response that does not match.

1. Success

A single item:

{
  "data": { "id": "6f1c...", "invoice_no": "INV-2026-000123", "...": "..." },
  "meta": { "request_id": "req_01J8...", "generated_at": "2026-09-22T10:14:03Z" }
}

A list:

{
  "data": [ { "...": "..." }, { "...": "..." } ],
  "page": { "next": "eyJkdWVfZGF0ZSI6IjIwMjYtMDktMTAiLCJpZCI6Ii4uLiJ9", "size": 50 },
  "meta": { "request_id": "req_01J8...", "generated_at": "2026-09-22T10:14:03Z" }
}

An action with nothing to return: HTTP 204 and an empty body. Creates return 201 with the created item in data (a POST that returns a single item is 201 unless the operation says 200). Actions that change state and return the changed item (void, reverse, match) return 200.

data is always present on 200 and 201, never null. page is present on every paginated list, even when the list is empty (data: [], page: {"next": null, "size": 0}); a short list the document types as a plain array (a person's children, their applications, their slips) has no page. meta is present on every JSON response. There are no other top-level keys, ever; a client can rely on Object.keys(body) being a subset of data, page, meta, error.

Fields inside data follow these rules: names are snake_case; a field that is absent from the schema is never sent; a field that is in the schema is always sent, with null when it has no value (the API never omits keys to mean null, so a client can destructure safely); booleans are JSON booleans; money is a string with two decimals plus a sibling currency; dates are YYYY-MM-DD; timestamps are RFC 3339 in UTC with a Z; ids are lower-case UUIDs; enums are lower-case tokens; nested people are { "user_id", "full_name" } and never carry email or phone unless the schema says so (School API Person does; PersonRef does not).

Derived values are computed by the server and named as such: balance, is_overdue, on_hold, unallocated, percent. Clients should not recompute them.

2. Pagination

Cursor based, on every paginated list. size is 1 to 200, default 50 (anything else is 400 INVALID_PAGE_SIZE). The cursor is opaque and signed; it is valid for the same route, the same filters and the same caller for 24 hours. Changing a filter with an old cursor, or using one after it expired, is 400 INVALID_CURSOR with a hint to start from the first page. page.size is the number of items in this page. page.total is optional and appears only where counting is cheap (the audit trail); everywhere else there is no total, because counting is expensive and the number is stale by the time it is shown. Screens that need a count call the summary endpoints (dues, dashboard) which return counts by design.

Order is stable and documented per endpoint in the OpenAPI description; where nothing is said it is newest first by created_at, then by id. Sorting is not client selectable in v1.

Incremental sync uses updated_since on students and invoices: rows changed at or after the instant, ordered by updated_at, cursor paged. A client stores the generated_at of the last full page as its next updated_since.

3. Errors

{
  "error": {
    "code": "SECTION_FULL",
    "message": "This section is full (30 of 30 seats). Raise the capacity or pick another section.",
    "hint": "Section 6f1c... has capacity 30 and 30 active students.",
    "field": "/section_id",
    "request_id": "req_01J8...",
    "retryable": false,
    "docs": "https://api.samas.school/docs/errors#SECTION_FULL"
  }
}

code is the contract. It is stable, upper snake case, and the same string the database raises, so the web app, the mobile apps and a partner's integration all key their behaviour on it. message is for a person and may change wording and language (Accept-Language: ur is accepted and will return Urdu where a translation exists; messages are English today). Every key is always present: hint is extra detail or null; field is a JSON pointer into the request body (/rows/3/status), or /query/<name>, /path/<name> or /header/<name>, or null when the error is not about one field; request_id is the same value as the X-Request-Id header; retryable says whether the same request may succeed later without change (rate limits, expired tokens, upstream outages, maintenance); docs links the catalogue entry. There is exactly one error per response; the server does not return a list of all validation failures, because the first one usually explains the rest and because the order is defined (see validation-rules.md, section 7).

HTTP status carries the class of failure and nothing more:

A 404 for an id the caller cannot see is deliberate: a parent asking for another family's invoice learns nothing about whether it exists.

4. Headers on every response

X-Request-Id (echoed or generated). Content-Type: application/json on any body. Cache-Control: no-store on everything except the OpenAPI documents, the health endpoint and the gateway's key set. RateLimit-Limit and RateLimit-Reset (seconds to the next window) on every authenticated success, plus RateLimit-Remaining where the edge can count it; the limits are 600 requests a minute for a signed-in person, 1,200 for a school key and 3,000 for a platform key. Retry-After on 429 (60) and 503 (10). Idempotent-Replayed: true when a stored response was returned. ETag on single-item GETs; If-None-Match with the same value returns 304. Any endpoint scheduled for removal will carry Deprecation and Sunset headers at least 90 days ahead (none is scheduled). Security headers as on the web app (X-Content-Type-Options: nosniff, Strict-Transport-Security, X-Frame-Options: DENY).

5. Webhook payloads

Deliveries are POSTs with the same envelope discipline:

{
  "id": "evt_01J8...",
  "event": "payment.recorded",
  "occurred_at": "2026-09-22T10:14:03Z",
  "school_id": "49a4...",
  "data": { "...": "the Payment object as GET /school/payments/{id} would return it" },
  "meta": { "attempt": 1, "delivery_id": "dlv_01J8..." }
}

Headers: X-Samas-Event, X-Samas-Delivery, X-Samas-Timestamp (unix seconds), X-Samas-Signature: v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with the endpoint secret>. Receivers must verify the signature, reject timestamps older than 5 minutes, and treat delivery_id as the idempotency key (retries reuse it). Any 2xx within 10 seconds counts as delivered; otherwise retried at 1, 5, 30 minutes, 2, 6, 24 hours, then the endpoint is marked failing and the school admin is notified. Events are delivered at least once and in no guaranteed order; occurred_at orders them.

6. Versioning and change policy

/v1 is the contract; the documents carry info.version (1.0.0-draft until the first partner integrates). Within v1 the API may add fields, add enum values only on fields the schema marks x-extensible-enum: true (none yet; every enum is closed until a client can cope), add endpoints, and add optional request fields. It will not rename or remove fields, change a type, change a code, or tighten a rule on an existing endpoint. Anything of that kind is /v2. Every change is recorded in openapi/CHANGELOG.md with the date and the affected operations; generated clients pin a version of the document.

7. Files

build.py is the source of the six documents; npm run api:generate writes me, school, admin, finance, platform and ops as .yaml and .json, publishes the public site (public/api-docs, with docs/guides/*.md, this file and validation-rules.md), and regenerates the gateway's bundled contracts and the web client's types. schemas/envelope.schema.json: the success, list and error envelopes and the primitive formats (Money, Date, Timestamp, Id, Cursor). schemas/error-codes.json: every code with its HTTP status, retryable flag, default English message and docs link. Both are bundled into the gateway; a code raised by the database that is missing from the catalogue fails the gateway's own tests.

Error codes

215 codes. code is the contract; message may be reworded or translated.

API changelog

2026-10-27 (nine Nexus School reports)

• WeeklyPlan gains day_notes (one line per weekday, up to 300 characters) and WeeklyPlanDay gains note; PUT /admin/sections/{section_id}/weekly-plans/{week} accepts day_notes (replaces the whole list). Additive; the class teacher's plan for each day (TT63), reported as PRB-2026-0018.
• Announcement gains author (PersonRef or null) on GET /admin/announcements, /school/announcements and /me/announcements, so the office sees who posted it (PRB-2026-0013). created_by stays.
• StaffMember gains signed_in, so GET /admin/staff shows Invited the same way GET /admin/people does (PRB-2026-0006).
• Slip gains can_manage; GET /admin/slips and GET /admin/slips/{id} now also show a teacher, read-only, the slips that reach a child in a section they are class teacher of or teach (PRB-2026-0012). Change, remind, close and cancel stay with the office and the sender.
• POST /me/issues/{id}/messages and POST /platform/issues/{id}/messages take IssueMessageWrite: the body plus an optional picture_upload_id (one picture per message, from the matching upload-url operation). The picture is kept on the message (IssueMessage.pictures) and attached to the reporter's email on a reply (PRB-2026-0007). The office's POST /admin/issues/{id}/messages is unchanged until it has an upload-url of its own.

2026-10-27 (two add-ons: TOEFL course packs and Flash cards)

• AddOn.add_on, Session.add_ons and the What's new add_on filter gain toefl (the TOEFL course packs, PRD 5.20) and flashcards (picture flash card decks with spaced repetition, PRD 5.20.13). Additive: a school turns them on under Settings, School, Add-ons, or a platform key with write:schools switches them through PUT /platform/schools/{id}/add-ons/{add_on}. The TOEFL and flash card operations themselves arrive with the Learning API's phases.

1.0.0-draft, 2026-09-22

First draft of the Student (/v1/me), School (/v1/school), Admin (/v1/admin) and Platform (/v1/platform) contracts for review. Nothing is frozen yet; breaking changes are allowed until the first partner integrates, after which this file records every change with the affected operations.

1.0.0-draft, 2026-09-23

• Period.starts_at and Period.ends_at now require HH:MM (they were free text). Affects PUT /admin/periods.
• Gateway implementation landed under api/: every operation in the four documents has a handler, and api/test/coverage.test.ts keeps it that way.
• Added GET /admin/search and GET /me/search (schema SearchHit): one ranked list of students, people, families, invoices and receipts, typo tolerant, filtered by what the caller may see. Parameters q (2 to 80 characters), kind, limit (1 to 50).
• Added GET /me/session (schemas Session, SessionPerson, Membership, ViewAsSession) and POST /admin/view-as/extend. The web app's sign-in context now comes from the API.
• Added 14 error codes the database already raised but the catalogue lacked (NOT_INVITED, NOT_A_MEMBER, NO_SCHOOL, NO_SUCH_USER, DISABLED, ALREADY_ACTIVE, ALREADY_EXTENDED, NO_SESSION, BAD_MODE, BAD_ENTITY, BAD_PATH, NO_DELETE, TOO_OLD, NOT_SIGNED_IN) and IDEMPOTENCY_IN_PROGRESS. Previously these came back as INTERNAL.
• Contract corrected to match what the API always returned (found by the new response checks in the gateway tests): Person, Guardian and PersonRef name and contact fields may be null; Student.section.room and class_name may be null; Student gains section_id, phone and email; ChangeLogEntry.id is a string and actor and acting_as are names; ApiKey.role and created_by may be null.
• Added PATCH and DELETE /admin/subjects/{id}, DELETE /admin/section-subjects/{id}, DELETE /admin/assessments/{id}, PATCH /admin/calendar/{id} and GET /admin/timetable (a teacher's week, schema TeacherSlot). GET /admin/students/{id} returns StudentDetail (adds contact details). TimetableSlot gains section_subject_id, Announcement gains created_by, /admin/my-sections subjects gain subject_id and teacher_id.
• Changed (draft, no integrations yet): both student attendance endpoints return data: { records, summary } (AttendanceHistory) instead of a summary beside data, which the envelope could not carry; timetable clashes carry teacher_id.
• Contract corrected: Assessment.subject and TimetableSlot.subject are Subject objects (id, name, code) or null, as the API always returned.
• GET /me children gain section_id; Subject.code may be null.
• StudentWrite: optional fields accept null (to clear them), and user_id links the student's own sign-in.

1.0.0-draft, 2026-09-24 (finance screens on the API)

• Added GET /admin/holds (filters entity_type, entity_id, active).
• FamilyAccount.students items gain status; their admission_no, class_name and section_name may be null. GET /admin/families/{id} and GET /school/families/{id} now return open_invoices as documented.
• Invoice gains family_name and family_phone; payments items gain method and include reversed payments with their status, as documented. GET /admin/invoices/{id} now returns flags, holds and reminders as documented, and GET /me/invoices/{id} returns disputes. GET /admin/invoices?q= searches student names as well as invoice numbers, as documented.
• Payment gains family_phone; allocations items gain period_start and carry student_name.
• Adjustment gains student_admission_no, class_name, section_name, fee_head_name and created_at.
• Proof gains family_phone and students (id and name of each child on the proof).
• GET /admin/reminders/log items gain id and invoice_id.
• Contract corrected: GET /admin/fees/structure returns { heads, lines, settings } for one academic year (default: the current one), like GET /school/fees/structure; both now honour academic_year_id. PUT /admin/fees/structure without an id updates the existing line for the same year, class and head instead of failing.
• POST /me/proofs/upload-url accepts student_id, which sets up the family account when there is none yet and picks the right account for parents with children on more than one.
• POST /admin/fees/heads accepts is_active.
• Invoice gains voided_at; Payment gains reversed_at. ReminderRule.template is 10 to 600 characters (the database rule; the documented default of 200 was wrong).

1.0.0-draft, 2026-09-24 (settings and audit screens on the API)

• Added GET/POST /admin/webhooks, PATCH/DELETE /admin/webhooks/{id}, POST /admin/webhooks/{id}/test and GET /admin/webhook-deliveries, so the school admin manages webhooks in the app the same way a key with the webhooks scope does. PATCH /school/webhooks/{id} also accepts url. WebhookDelivery gains endpoint_id.
• Page gains an optional total; GET /admin/audit sets it.
• Fixed: GET /admin/audit/reveals and GET /admin/students/{student_id}/confidential failed in production (they joined to profiles through foreign keys that do not exist); names are now looked up. Reveals are paginated and name the person whose number was revealed.
• Fixed: GET /admin/people/{id}/history asked the database for the wrong record type and always came back empty.

1.0.0-draft, 2026-09-24 (platform screens on the API)

• Added GET /platform/stats (totals for the super admin home page), GET /platform/docs (product documents) and GET /admin/dashboard/school (totals for the office home page).
• Added POST /platform/schools/{id}/people: invite anyone to any school with any school role; an existing email or phone gets the role added. PATCH /platform/people/{id} accepts role and school_id to move a person's default school and role.
• GET /platform/people accepts pending (invited, not signed in yet) and items gain school_id, is_super_admin, signed_in and created_at.
• Added the design review endpoints under /platform/review (verify, feedback list, add, resolve, counts). They are the first operations marked x-signed-in-only: any signed-in person may call them without a school role; the shared access code goes in the X-Review-Code header.
• Fixed: GET /platform/audit joined to profiles through foreign keys that do not exist and would have failed; names are now looked up.
• School.settings returns only the documented keys (older schools carried extra keys the contract does not describe).
• Contract corrected: Person.role may be super_admin or null, as the API always returned for platform staff and for accounts with no school.
• q search text also drops double quotes (with %, _, \, commas and brackets), so it can never change a filter.

1.0.0-draft, 2026-09-24 (Ops API)

• New internal document openapi/ops.json (/v1/ops, super admins and platform keys): dependency health, alerts, API figures by route, API, school, status or hour, scheduled jobs and their runs with run-now, the email log with resend, webhook deliveries across schools with replay, and maintenance mode per school. Contact details are masked in lists.
• New error codes INVALID_STATE (409: the action does not apply to the record as it is) and MAINTENANCE (503, retryable: the school is in maintenance; writes are paused, reads work). Every write for a school in maintenance now returns MAINTENANCE, except for super admins.

1.0.0-draft, 2026-09-24 (Finance API, part 1)

• New internal document openapi/finance.json (/v1/finance): every fee operation (settings, structure, families, invoices, dues, payments, discounts, proofs, flags and holds, reminders) now lives here, with the same behaviour; /admin/dashboard/finance becomes /finance/dashboard. The Admin copies keep working and are marked deprecated. Only the school office (admin, principal, finance), school API keys and super admins may call it; teachers get 403.
• New reports: GET /finance/reports/collections (by day, month, method or class), /finance/reports/aging, /finance/reports/defaulters, /finance/reports/discounts, and the accounting export GET /finance/export/journal (dated debit and credit lines; every entry balances). Ranges are at most 366 days.

1.0.0-draft, 2026-09-24 (Finance API, part 2: refunds and month-end close)

• Refunds: POST /finance/payments/{id}/refunds, GET /finance/refunds, GET /finance/refunds/{id}, POST /finance/refunds/{id}/decide. Office only. Above the school's refund_approval_amount (new fee setting, default 10000.00) a refund waits for a different office person (SECOND_PERSON_REQUIRED if the requester tries). The receipt never changes; the refund gets its own number (RFD-2026-000001) when approved. A receipt with refunds cannot be reversed (INVALID_STATE).
• Payment (all documents, including /me/receipts) gains refunded and refunds; allocations and unallocated now show what the payment covers after refunds. A family sees only approved refunds.
• Month-end close: GET /finance/periods, GET /finance/periods/{month}, POST /finance/periods/{month}/close, POST /finance/periods/{month}/reopen (school admin, with a reason). A payment dated in a closed month is refused with the new code PERIOD_CLOSED (409).
• Reports: CollectionRow.refunded; the journal adds credit_applied (family credit applied to invoices on a later day, dated that day) and refund entries, so entries in a closed month never change.

1.0.0-draft, 2026-09-24 (school look, web addresses, View-as rules)

• Each school has a look and its own web address. New: GET /school/public/branding?host=|school= (School API, no credentials, cached 5 minutes), GET/PUT /admin/branding and POST /admin/branding/uploads (school admin), GET/PUT /platform/schools/{id}/branding and POST /platform/schools/{id}/branding/uploads (super admin, also sets subdomain). Colors are checked for readable contrast (new code LOW_CONTRAST, 400).
• Session (GET /me/session) gains branding (the active school's look) and memberships[].web_url.
• View-as never targets a school admin or a super admin. New GET /admin/view-as/targets and GET /platform/view-as/targets list who the caller may view as; POST /platform/view-as takes an optional school_id for people in several schools.
• Operations may be marked x-public (no credentials, read-only, rate-limited per address).

1.0.0-draft, 2026-09-24 (school MCP server)

• New: the school MCP server at https://api.samas.school/mcp (Streamable HTTP, stateless, read-only tools backed by the documented API with the caller's own permissions). OAuth 2.1 with PKCE: discovery at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, dynamic client registration at /oauth/register (or a client metadata URL as client_id), /oauth/authorize, /oauth/token, /oauth/revoke. School API keys also work as bearer tokens.
• Me API: GET /me/ai-connections, DELETE /me/ai-connections/{id}, and the approval step GET /me/ai-connections/requests/{request}, POST .../approve, POST .../deny.
• Admin API: GET/PUT /admin/ai-access (off by default; names hidden by default), GET /admin/ai-access/connections, DELETE /admin/ai-access/connections/{id}.

1.0.0-draft, 2026-09-24 (school picker and color mode)

• Added GET /me/schools (schema SchoolChoice): the schools the caller can switch to, with each school's name, main color, logo, web address and the caller's roles there. Super admins get every school.
• Added PUT /me/working-school: move into a school (a member in their default role or a named one; a super admin into any school, or null to leave). Returns the new Session. Refused during View-as.
• Added PUT /me/preferences with color_mode (schema ColorMode: light, dark or system). Session gains color_mode, the signed-in person's own choice.
• Contract corrected: Session.role and SessionPerson.role use SessionRole, which adds super_admin, as the API always returned for super admins.

1.0.0-draft, 2026-09-24 (dashboards)

• Added GET /admin/dashboard/overview (schema OfficeOverview): the office home page in one call.
• Added GET /admin/dashboard/teacher (schema TeacherOverview): today's lessons with register status, and the teacher's sections with 30-day attendance.
• Added GET /platform/dashboard (schemas PlatformOverview, PlatformSchool): every school with figures and a health light, totals and firing alerts.
• GET /finance/dashboard gains refunds_pending, aging (not due, 1 to 30, 31 to 60, 61 to 90, 91 and more days) and by_month[].invoiced; by_month now always has the last six months. Figures are for the caller's school only (a super admin working in a school no longer sees every school added together).

1.0.0-draft, 2026-09-25 (statements, documents, parents and AI)

• Added GET /finance/families/{id}/statement and GET /me/statement (schema FamilyStatement): one family account's charges, voids, payments, reversals and refunds between two dates, with opening, running and closing balances. Up to 366 days.
• Added the Documents tag in the Finance API: POST /finance/documents/upload-url, POST /finance/documents, GET /finance/documents, GET and PATCH /finance/documents/{id} (schema SchoolDocument). Bank statements are stored with bank, account, file format and the dates they cover; parsing and importing come later.
• AiAccess gains parents_enabled; PUT /admin/ai-access accepts it. With it on, parents may connect an assistant to the MCP server and read only their own children (family tools). Turning it off disconnects every parent's assistant.

1.0.0-draft, 2026-09-26 (reading bank statements)

• Added GET /finance/documents/{id}/format, GET and POST /finance/documents/{id}/lines, POST /finance/documents/{id}/lines/suggest, POST /finance/documents/{id}/lines/confirm, POST /finance/bank-lines/{id}/confirm and POST /finance/bank-lines/{id}/status (schemas BankMapping, BankLine). The deposits of a stored statement get a suggested family with a reason; a confirmed deposit becomes a normal bank-transfer receipt.
• SchoolDocument gains read_at, lines_total and lines_open.
• New error codes INVALID_LINE and DUPLICATE_DEPOSIT (409).

1.0.0-draft, 2026-09-27

• Labs (Platform API, tag Labs): GET /platform/labs/designs, PATCH /platform/labs/designs/{design}, GET /platform/labs/designs/{design}/history, GET /platform/labs/staff, GET and POST /platform/labs/comments, PATCH /platform/labs/comments/{id}, GET /platform/labs/comment-counts. Schemas Design, DesignWrite, DesignStage, DesignStageChange, DesignComment. Any signed-in person reaches them; the database lets in saMas staff and super admins only, and only super admins change a design.
• Removed (internal tool, no integrations): the /platform/review/* design review endpoints and the X-Review-Code header. Comments are kept and now come back as DesignComment (design_id instead of screen_id); the author is always the signed-in person.
• Session gains is_staff. GET /platform/people rows gain is_staff; PATCH /platform/people/{id} accepts is_staff and refuses fields it does not know (UNKNOWN_FIELD).
• Added GET /platform/labs/designs/{design}/spec (schema DesignSpec): the design's PRD and TDD with every validation rule and check, generated from the code by scripts/labs/sync-specs.mjs. Super admins only. Design gains has_spec.

1.0.0-draft, 2026-09-30 (homework, exams, insights)

• Homework (Admin API, tag Homework): POST /admin/homework/upload-url, GET /admin/section-subjects/{id}/assignments, POST /admin/assignments, GET, PATCH and DELETE /admin/assignments/{id}, PUT /admin/assignments/{id}/marks/{student_id}, POST /admin/assignments/{id}/return. Schemas Assignment, AssignmentCreate, AssignmentWrite, AssignmentDetail, HomeworkFile, HomeworkFileRef, HomeworkUpload, HomeworkSubmission.
• Homework for families (Student API): GET /me/students/{student_id}/homework (schema ChildHomework with a status), POST /me/homework/upload-url, PUT /me/assignments/{id}/submission.
• Exams (Admin API, tag Exams): GET and POST /admin/exams, GET, PATCH and DELETE /admin/exams/{id}, POST /admin/exams/{id}/papers, PATCH and DELETE /admin/exam-papers/{id}, POST /admin/exams/{id}/schedule, POST /admin/exams/{id}/classes/{class_id}/publish. Schemas ExamTerm, ExamTermCreate, ExamTermWrite, ExamTermDetail, ExamPaper, ExamPaperCreate, ExamPaperWrite, ExamClassStatus. Families: GET /me/students/{student_id}/exams (schema ChildExams).
• Insights: GET /admin/insights (schema Insight).
• Assessment gains exam_paper_id: exam columns take marks from teachers, but only the office publishes them (under Exams).

1.0.0-draft, 2026-09-27

• Session gains admin_site_url and admin_site_required (additive): where the signed-in person does admin work, and whether admin work is only accepted through that admin site.
• New error codes SECOND_FACTOR_REQUIRED and STEP_UP_REQUIRED (403): admin work needs a sign-in with a second factor, and sensitive actions (roles, API keys, View-as, refunds, closing or reopening a month, identity numbers, school flags and limits) need one within the last 10 minutes.
• File links (upload_url, file_url, logos) now point at the API itself (/v1/files/..., signed and short-lived) instead of the storage vendor.

1.0.0-draft, 2026-09-28

Found by the new end-to-end tests (every read, for every kind of person, checked against the contract). The API already answered this way; the contract now says so. - Section.room, Student.gender: may be null. - GET /admin/classes and GET /school/classes: items are the new ClassWithSections (a class's fields plus sections). - GET /me: school is null for a super admin in the platform view. - Invoice.student: null when the caller cannot see that student (a student seeing a sibling's invoice on the family account). - GET /platform/audit: school is null for platform-wide changes. - GET /me/notifications: now paged like every other list (page with next_cursor; cursor and size work). - GET /admin/dashboard/teacher: is_class_teacher is always true or false (was null for sections without a class teacher). - POST /admin/invoices, POST /finance/invoices, POST /school/invoices: answer 200 as documented (was 201).

1.0.0-draft, 2026-09-29 (help health)

• Added POST /me/help/events (schema HelpEvent): the web and mobile apps record how help does in real use (a ? panel opened, a guide opened or voted on, an anchor a guide could not find, a search with no results). Nothing is recorded during View as; at most 300 events a day per person.
• Added GET /platform/help/health (schema HelpHealth, parameter days, 1 to 365): the help health page for the saMas team.

1.0.0-draft, 2026-09-30 (getting started)

• Added GET /me/getting-started, POST /me/getting-started/items/{key} and POST /me/getting-started/view (schemas GettingStarted, GettingStartedItem, GettingStartedProgress): each staff member's getting started checklist, ticked by the app where it can see the step done.
• Added GET /admin/getting-started/team (schema TeamProgress): team progress for the principal and school admins.
• New error code ITEM_NOT_SKIPPABLE (409).

1.0.0-draft, 2026-09-30 (bulk import)

• Added POST /admin/imports/preview, POST /admin/imports, GET /admin/imports and GET /admin/imports/{id} (schemas ImportKind, ImportRow, ImportOptions, ImportPreviewWrite, ImportWrite, ImportRowResult, ImportSummary, ImportPreview, Import, ImportResult): a school office loads students with their guardians, or staff with their records, from a spreadsheet the browser has read. Rows are checked first; siblings sharing a guardian's phone or email share one parent account; existing admission numbers and staff emails are skipped, never changed. Up to 2000 rows.
• New error codes IMPORT_TOO_LARGE (400) and IMPORT_HAS_ERRORS (409).

1.0.0-draft, 2026-09-30 (report a problem)

• Added the Issues tag on the Student API: GET and POST /me/issues, POST /me/issues/upload-url, GET /me/issues/{id}, POST /me/issues/{id}/messages, POST /me/issues/{id}/reopen, POST /me/issues/{id}/confirm-fixed, DELETE /me/issues/{id}/screenshot (schemas Issue, IssueDetail, IssueWrite, IssueMessage, IssueEvent, IssueScreenshot, IssueUpload, IssueNote, IssueReason). Anyone signed in reports an app problem, an idea or a school matter and follows it; a reference PRB-YYYY-NNNN per school.
• Added the office inbox on the Admin API: GET /admin/issues, GET /admin/issues/{id}, POST .../messages, POST .../close, POST .../pass-to-samas, DELETE .../screenshot.
• Added triage on the Platform API: GET /platform/issues, GET /platform/issues/{id}, PATCH /platform/issues/{id} (priority, assignee, status), POST .../messages, POST .../fixed, POST .../send-to-school, and GET /platform/issues/removed-screenshots (schema ScreenshotRemoval).
• GettingStartedItem gains help (set while a report sent from that item is open). HelpEvent.kind gains report_opened.
• New error code ISSUE_LIMIT (429): ten reports a day per person.
• A DELETE with a request body in the contract now has its body read (removing a screenshot carries a reason).

1.0.0-draft, 2026-09-30 (docs site guides)

• The public docs site gains a Guides section (openapi/docs/guides/*.md, rendered by publish.py): getting started, hand in homework, apply for admission, messages, answer a permission slip, report a problem, import students. Each has the steps, a curl and a fetch example, and the answers a client can get. Linked as /api-docs#guides/<slug>.
• docs/response-format.md and docs/validation-rules.md brought in line with the gateway: the six documents, page.total on the audit trail, every error key always present (hint and field may be null), the 405 and 503 MAINTENANCE answers, the rate limits per credential, the header validation codes, and the upload rules for homework, message, admission and screenshot files. No contract change.

1.0.0-draft, 2026-09-30 (API keys and writes)

• API keys and writes: every Admin and Finance write either names the scopes a key needs (x-scopes, shown under "Who can call") or is for signed-in people only (x-people-only, security clerkToken only); a key on a people-only operation answers 403 NOT_ALLOWED. API keys, View-as, roles and identity numbers are people only whatever the method. Platform and Ops writes are people only.
• New scopes write:people, write:structure, write:imports, write:admissions and write:fees (schema Scope); the database's api_scopes() needs the same list before a key can be created with them.
• Money writes (payments, reversals, refunds, discount requests, proof matching, late fees, bank deposit confirmations) carry x-idempotency-required: Idempotency-Key is required (400 MISSING_FIELD), as it already was on POST /school/payments.
• POST /finance/documents/upload-url: content_type is now an enum (PDF, CSV, Excel, PNG, JPEG, WebP).

1.0.0-draft, 2026-10-01 (school roles and welcome emails)

• Added DELETE /admin/people/{id}/roles/{role} (take a role away) and POST /admin/people/{id}/welcome (send the welcome email again; outcome is queued or merged). POST /admin/people/{id}/roles gains notify (default true) and note. A school always keeps at least one school admin (403 NOT_ALLOWED).
• Adding a role now emails the person a welcome from the school listing every role they hold there; roles added within a minute make one email, at most 3 a day per person (429 RATE_LIMITED on a resend past that). Adding or removing a school admin, principal or finance role emails the school's other school admins.
• POST /admin/people: an email that already belongs to someone adds the role for them at this school instead of answering 409 DUPLICATE_ITEM. School admin, principal and finance roles cannot be given with an API key (403 NOT_ALLOWED).
• Imports: ImportOptions.send_welcome (default true) and ImportSummary.welcome_emails on previews.
• Platform API (internal): POST /platform/people/{id}/roles (school_id, role, notify, note; result is added or already), DELETE /platform/people/{id}/roles/{school_id}/{role}, POST /platform/people/{id}/welcome. Open to super admins and to platform keys with the new scope write:roles, which must expire within 30 days, only works where the gateway has ROLE_KEYS=on (beta), and emails the super admins on every use. ApiKey.expires_at and expires_at on POST /platform/platform-keys; an expired key answers 401 KEY_REVOKED.
• POST /platform/schools/{id}/people is open to platform keys with write:roles too, so a new person can be invited without a direct database write.
• Giving and taking roles, here and in the Platform API, and POST /platform/schools/{id}/people, need a two-step check in the last 10 minutes (STEP_UP_REQUIRED).
• Outside the contracts: POST /v1/access/evaluate/{school id | staff} and GET /v1/access/keys answer Cloudflare Access at sign-in to an admin site, so the sites follow roles without re-running the provisioning script.
• New guide: give and take school roles.

1.0.0-draft, 2026-10-07 (principals invite people)

• POST /admin/people, POST /admin/people/{id}/roles, DELETE /admin/people/{id}/roles/{role} and POST /admin/people/{id}/welcome are open to the school's principal as well as the school admin. Everything else about them is unchanged: the welcome email, the alert to the school's other admins, 3 emails a day per person, no admin roles through an API key, and a school keeping at least one school admin.
• POST /admin/people now needs a two-step check in the last 10 minutes for signed-in people (STEP_UP_REQUIRED), since it can give an admin role. API keys are not affected.
• The web app gains an Invite someone button on Users and roles and on Staff, built on these operations.
• Person gains signed_in on GET /admin/people (false while invited and not signed in), so the office can see who still needs to sign in and send the welcome again.
• POST /admin/people gains note (up to 300 characters): a line from the school in the welcome email, as POST /admin/people/{id}/roles already had.

1.0.0-draft, 2026-10-07 (the help buddy)

• Added the help buddy on the Student API (PRD H21 to H21d, TDD 6A.5, docs/help/buddy-api.md): POST /me/help/ask (schemas HelpAsk, HelpAnswer, HelpBlock), POST /me/help/ask/{id}/vote (HelpVote), POST /me/help/ask/{id}/report (HelpReport, HelpReportResult), GET /me/help/replies (HelpReply) and POST /me/help/replies/{id}/read. context carries ids only; the answer is validated against this build's help graph and the lookups that ran, and falls back to the plain steps otherwise. 20 questions a day per person, 10 a minute, never during View as, signed-in people only.
• Added GET and PUT /admin/help/quota (HelpQuota, HelpQuotaWrite): a school admin or principal raises one person's daily limit to 20 to 50 until a date.
• Added on the Ops API: GET /ops/help/stuck (HelpStuckRow), GET /ops/help/questions (HelpOpenQuestion) and POST /ops/help/questions/{id}/reply for the saMas help team.
• New error code HELP_VIEW_AS (403): the buddy is off while viewing as someone else.
• The school MCP server gains seven read-only tools, each a thin wrapper on an existing read: my_homework, section_gradebook, my_leave, my_threads (no message text), my_slips, my_getting_started, my_roles. my_threads, my_slips and my_roles are available to parents too.

1.0.0-draft, 2026-10-07 (the help buddy's screens)

• Added GET /me/help/buddy (HelpBuddyStatus): whether the button shows for this person, which character they get, questions left today, Less jokes, and replies waiting. The web app reads it on load and every few minutes.
• Added PUT /me/help/tone (HelpTone, HelpToneResult): Less jokes for 30 days, or back to the usual voice.
• Added GET and PUT /admin/help/buddy (HelpBuddySettings, HelpBuddySettingsWrite): the school's three switches (staff, parents, students). Reading is for the school admin and the principal; writing for the school admin.
• HelpEvent.kind gains the buddy's client-side kinds: stuck_offered, stuck_accepted, stuck_dismissed, walk_abandoned, ask_repeat_refusal.

1.0.0-draft, 2026-10-07 (the help team's view and the buddy's own checks)

• Added on the Ops API, for the saMas help team (PRD H21b, 5.8.5; TDD 6A.5b, 6A.5c): GET /ops/help/summary (HelpSummary: questions, unblocked rate, hand-off rate, no-guide rate, fallback rate, median time to unblock and model cost for the last 7 and 30 days, in all, per school and per role), GET /ops/help/fix-list and POST /ops/help/fix-list/build (HelpFixList, HelpFixRow: the weekly fix list the jobs Worker builds every night for the current week), GET /ops/help/eval-runs (HelpEvalRun: the nightly eval against the live model), and GET and PUT /ops/help/settings (HelpSettings, HelpSettingsWrite: the platform switch, the two models and the monthly cost cap, so the buddy can be switched off from the admin site).
• HelpStuckRow gains fix, the suggested fix read off the top path.
• OpsAlert.key lists the two keys that were already sent (admin_refusals, break_glass) and two new ones: help_unblocked_low (a role under 60% unblocked over three days with at least 20 votes) and help_eval_failed (the last nightly eval failed).
• Questions the nightly eval asks are marked and left out of the stuck moments, the open questions and the summary.

1.0.0-draft, 2026-10-08 (model routing through AI Gateway and the daily model council)

• HelpSettings and HelpSettingsWrite gain gateway_account, gateway_id, model_pool, council_models, quality_floor (HelpQualityFloor), council_cases_per_night and council_cap_usd; model_small and model_large are now gateway model strings (HelpModelString, provider/model, up to 120 characters). Affects GET and PUT /ops/help/settings.
• Added GET /ops/help/council (HelpCouncil, HelpCouncilStanding, HelpModelRun): every candidate model's last 7 nights, the pool, the floor, the gateway status and the last 14 nights per model. Added POST /ops/help/council/run (HelpCouncilRun, HelpCouncilRunResult): a small sitting now.
• OpsAlert.key gains help_council_empty (no model cleared the floor; the previous pool stays).

1.0.0-draft, 2026-10-08 (the hard-case council and the help team's dashboard)

• HelpSettings and HelpSettingsWrite gain council_hard (HelpHardCouncil, HelpHardCouncilWrite, HelpHardTriggers): the hard-case council's switch, its four triggers (unsure, failed checks, Not yet, no guide), the extra seats, the seat order, the per-question and per-day budgets, the tie rule and the pin. Affects GET and PUT /ops/help/settings.
• POST /me/help/ask/{id}/vote now answers 200 with HelpVoteResult (it answered 204): on Not yet, when the council sat and a seat passed, next_answer carries the new HelpAnswer to show in place.
• Added GET /ops/help/council/sittings (HelpCouncilSittings, HelpCouncilSitting, HelpCouncilSeat): every hard-case sitting with each seat's pass or fail reason, the model shown, the cost and the time, plus the period's counts and today's spend. Added POST /ops/help/council/compare (HelpCouncilCompare, HelpCouncilCompareResult, HelpCouncilCompareSide): replays the recent hard cases through two formations and scores them side by side.
• GET /ops/help/questions gains scope (open, the default, or all) and limit; HelpOpenQuestion gains answer, model, confidence, cost_usd and outcome. Added GET /ops/help/questions/{id} (HelpQuestionRecord: the full record with the sitting, the replies and the events) and POST /ops/help/questions/{id}/mark (HelpQuestionMark: the shown answer marked wrong joins the hard cases).

1.0.0-draft, 2026-10-08 (the owl is Smarty)

• The owl buddy is called Smarty in the app and in the voice. The buddy value stays hoot in HelpAnswer and HelpBuddyStatus (a rename there would break clients); only the display name changed.

1.0.0-draft, 2026-10-08 (Feedback from every screen)

• IssueWrite gains console_errors (up to 10 scrubbed browser error messages, 300 characters each) and IssueContext carries them back as console_errors. Affects POST /me/issues and every read of an issue. The web app's new Feedback button in the top bar opens the report form with a picture of the screen already attached and these messages listed, both shown to the person before sending.

1.0.0-draft, 2026-10-08 (View-as any person on the beta sites)

• Additive. Session gains view_as_open_targets (true on the beta sites only; always false on production). ViewAsTarget gains is_school_admin.
• On beta, GET /admin/view-as/targets and GET /platform/view-as/targets also list school admins, and POST /admin/view-as and POST /platform/view-as accept them as targets: a school admin may view as anyone at their school except a super admin; a super admin may view as anyone except another super admin. On production nothing changes: a school admin as a target is refused with 403 NOT_ALLOWED.
• Every change made during a View-as session is recorded in the change history under the real person, acting as the viewed person (ChangeLogEntry.actor and acting_as). Tables that previously wrote no history (attendance, marks, timetable, periods, admission seats, school maintenance, permission slip students) now do while a session is open.
• While viewing as someone (any mode, any environment), starting a conversation, adding people to one, sending a message, reporting a message and answering a permission slip answer 403 NOT_ALLOWED. Operations affected: POST /me/threads, POST /me/threads/{id}/messages, POST /me/messages/{id}/report and POST /me/slips/{id}/answer.

1.0.0-draft, 2026-10-09 (Timetables: any teacher's or class's week)

• Additive. New operations: GET /admin/timetable/week (one week of a class, teacher, subject or room, with filters days, subject_ids, room and show; schema TimetableWeek), GET /admin/timetable/search (TimetableSearch), GET /admin/timetable/free (TimetableFree), GET /admin/timetable/print-set (paged), POST /admin/timetable/print-log, and GET /me/students/{student_id}/timetable/week. A class's week is open to anyone in the school; a teacher's, subject's or room's week, free right now and search beyond classes are for staff; Print all is for the office. All of them are for signed-in people only.
• Security fix, no deprecation window: GET /admin/timetable and GET /admin/sections/{section_id}/timetable are now for signed-in people only (403 NOT_ALLOWED to API keys). The second one returns drafts, which a key should never read. Key holders read published timetables with GET /school/sections/{section_id}/timetable (scope read:timetable), which is unchanged. Schools with keys are told.

1.0.0-draft, 2026-10-09 (Timetable: shifts and dated changes)

• Additive. New operations: GET and POST /admin/shifts, PATCH and DELETE /admin/shifts/{shift_id}, POST /admin/shifts/{shift_id}/versions (Plan changes), PUT /admin/shifts/{shift_id}/sections (move sections), PUT /admin/shift-versions/{version_id}/bell-times, PUT /admin/shift-versions/{version_id}/day-rules, POST /admin/shift-versions/{version_id}/publish, DELETE /admin/shift-versions/{version_id} (Discard changes), and GET /me/students/{student_id}/shift. New schemas Shift, ShiftVersion, ShiftWrite, ShiftPatch, PeriodWrite, DayRule, TimetableClash, TimetableVersionRef, ChildShift. Every shift operation is for signed-in people only; GET /admin/shifts is for staff, with planned changes for the office.
• Period gains block_type, weekday, shift_id and version_id, and period_no goes up to 24. GET /admin/periods answers the main shift's bell times live today; PUT /admin/periods keeps working while a school has one shift and no planned changes, and answers VERSION_REQUIRED afterwards.
• GET, PUT /admin/sections/{section_id}/timetable and POST .../publish take an optional version_id (the live version by default). The GET answer gains version_id, shift_id and versions; clashes are TimetableClash (by the clock, across shifts, with kind, who, other_period_no and first_date); the PUT answer gains warnings; the publish answer gains version_id, carried and not_carried. A draft takes up to 168 lessons, on periods of the shift only (LESSON_NOT_ALLOWED).
• TimetableWeek gains shifts (each with its bell times and day kinds) and a shift_id filter; lessons gain shift; free periods gain shift_id, starts_at and ends_at; the summary gains shifts. TimetableFree.period gains shift.
• New error codes: SHIFT_LIMIT, SHIFT_IN_USE, SHIFT_MAIN, VERSION_EXISTS, VERSION_LIVE, VERSION_REQUIRED, HAS_LESSONS, BLOCK_ORDER, DATE_IN_PAST, LESSON_NOT_ALLOWED. CLASH now means a teacher would be in two places at overlapping clock times.

1.0.0-draft, 2026-10-09 (Timetable: timings, closures and notices)

• Additive. New operations: POST /admin/shifts/{shift_id}/timings, PATCH and DELETE /admin/timings/{timing_id}, GET and POST /admin/day-overrides, DELETE /admin/day-overrides/{id}, and GET /admin/timetable/notices. New schemas Timing, TimingTime, TimingWrite, DayOverride, DayOverrideWrite, TimetableNotice. All for signed-in people only; closures and timings are written by the office.
• Shift.timings and Shift.timing_today are typed; ChildShift gains timing_today and the closures and changed days of the next 14 days. TimetableWeek.shifts[].days gain on_date, closed, follows and timing; each weekday is shown for the next time it comes, with its closures, changed days and timing.
• New error code TIMING_TIMES. Families get a timetable_change notice (in the app and by email) the day before a change, or at once for today.

1.0.0-draft, 2026-10-09 (Timetable: rooms, doubles, lessons taught together)

• Additive. New operations: GET and POST /admin/rooms, PATCH and DELETE /admin/rooms/{room_id}, GET and PUT /admin/teachers/{teacher_id}/unavailable, POST /admin/sections/{section_id}/timetable/combine, POST /admin/sections/{section_id}/timetable/copy, POST /admin/shift-versions/{version_id}/copy-bell-times. New schemas Room, RoomWrite, UnavailableTime.
• Draft rows take span (2 or 3 for a double or triple), room_id and combined_key; TimetableSlot gains span, combined_key and room_id; TimetableLesson gains span and with (the classes taught together).
• TimetableClash.kind gains unavailable (the teacher is not at the school then), with other_section_id null; other_section_id is no longer required. Clashes now see one-class rooms, availability and timings.
• New error codes DOUBLE_BREAK and COMBINED_SHIFT.

1.0.0-draft, 2026-10-09 (Timetable: cover for absent teachers)

• Additive. New operations: GET /admin/cover (a day: absences, lessons needing cover, covers per teacher), POST /admin/cover/absences, DELETE /admin/cover/absences/{id}, GET /admin/cover/suggestions, PUT and DELETE /admin/cover/{on}/{section_id}/{period_no}, GET /admin/cover/sheet, GET /admin/cover/mine, GET and PUT /admin/settings/timetable. New schemas LessonCover, CoverAbsence, CoverLesson, CoverDay, CoverSuggestion, CoverSheet, MyCover, TimetableSettings.
• TimetableLesson gains on_date and cover; a teacher's week includes the lessons they cover. TeacherOverview.lessons[] gains cover, and includes lessons the teacher covers today. Staff see for whom; the class's students and families see the cover teacher only.
• New error code COVER_CLASH. New email kinds cover_assigned and cover_cancelled. Approved leave marks the teacher away; leave withdrawn clears its covers.

1.0.0-draft, 2026-10-09 (Timetable: teacher load, Stats, history, import)

• Additive. New operations: GET /admin/timetable/teachers (teacher load: filters q, shift_id, subject_id, load, weekends; sort), GET /admin/timetable/stats, GET /admin/sections/{section_id}/timetable/history. New schemas TeacherLoad, StatsKpi, TimetableStats, TimetableHistoryEntry. All office only and for people, not school keys.
• PUT /admin/settings/timetable takes weekly_limit (10 to 60). The first weekly limit may be set by anyone in the office; after that, the school admin changes either limit.
• Not built from the plan: format=csv on the teacher list. The screen builds the CSV from the JSON rows.
• Additive. New operations: POST /admin/timetable/imports/preview (each row's status and messages, a summary and the clashes the new drafts would have; nothing is saved) and POST /admin/timetable/imports (each class in the file gets a new draft, in one transaction; IMPORT_HAS_ERRORS unless skip_error_rows). New schemas TimetableImportRow, TimetableImportPreview, TimetableImportClash, TimetableImportResult. Rows take target (live or planned) instead of the planned version_id, since the classes in one file can be in different shifts.

1.0.0-draft, 2026-10-09 (Timetable: now and next, the school day, class boards)

• Additive. New operations: GET /admin/timetable/now (a class's now, next, later today, closures, cover and exam papers), GET /me/students/{student_id}/timetable/now, GET /admin/timetable/master (every teacher or class for one day; the whole day in one answer, not paged), GET and POST /admin/sections/{section_id}/board-links, DELETE /admin/sections/{section_id}/board-links/{id}, and the public GET /school/public/board/{token} (no sign-in, no student names, two reads a minute per link). New schemas NowLesson, TimetableNow, BoardLink, TimetableMaster.
• New error code BOARD_LINK_ENDED (410). Only a hash of a board token is kept or logged; the token is shown once.

1.0.0-draft, 2026-10-09 (Timetable: extra classes)

• Additive. New operations: POST /admin/extra-classes, PATCH /admin/extra-classes/{section_id}, GET and PUT /admin/sections/{section_id}/members. New schemas ClassMember, ExtraClassWrite. Section gains optional kind (normal, extra), label and shift_id; enrolled counts an extra class's members. GET /admin/my-sections rows gain kind and label.
• A child's week (GET /me/students/{student_id}/timetable/week) includes the lessons of the child's extra classes; target.sub names them. Timetable clashes gain kind student (a student in two of their classes at once). Notices and homework sent to an extra class reach its students and families.
• New error code NOT_EXTRA_CLASS. Extra classes are added through their own operation rather than POST /admin/sections with a kind, so the section form keeps its rules.

1.0.0-draft, 2026-10-09 (Timetable: option blocks)

• Additive. New operations: GET and PUT /admin/sections/{section_id}/timetable/options. New schema OptionBlock. TimetableLesson gains option; an option block is one lesson per option in week views. A child's week shows only the child's option; staff see every option.
• Clashes see every option's teacher. A student in two options of one period, or two options with the same teacher, is refused with CLASH.

1.0.0-draft, 2026-10-09 (Timetable: the balance check and team time)

• Additive. New operations: GET /admin/timetable/balance (filters shift_id, draft, section_id; office only), GET and POST /admin/timetable/team-time, DELETE /admin/timetable/team-time/{id}, GET /admin/timetable/team-time/suggestions (teacher_ids, comma separated, and shift_id). New schemas BalanceRuleSetting, BalanceResult, TeamTime, TeamTimeSlot.
• TimetableSettings gains balance_rules, hard_subject_ids, movement_subject_ids, young_class_ids and teen_class_ids; PUT /admin/settings/timetable accepts them (school admin only). An unknown rule or a value of the wrong kind is INVALID_TYPE; a number outside the rule's range is OUT_OF_RANGE.
• Clashes gain kind team_time: a teacher's lesson in protected team time. Protecting a time when a chosen teacher is not free is refused with CLASH.
• Query parameters with a pattern may now be longer than 64 characters up to their own maxLength (before, every pattern parameter was cut at 64).

1.0.0-draft, 2026-10-09 (Timetable: day shapes)

• Additive. New operations: GET /admin/shifts/shapes (office only), POST /admin/shifts/{shift_id}/preview (office only, saves nothing) and POST /admin/shift-versions/{version_id}/apply-shape. New schemas Shape, ShapeBlock, ShapeDayRule, ShapeWrite, ShapeStats, ShapePreview.
• A shape body gives a starting shape, or blocks (type and minutes), or both, from a start time; day_rules take after_period (the nth teaching period). Teaching periods keep the numbers the shift's periods have, in order, so lessons keep their period at the new time.
• The preview's balance is the same check as GET /admin/timetable/balance, with status_now for the live week. A day running past midnight is INVALID_TYPE; overlapping or too long blocks BLOCK_ORDER.
• The MCP server gains read-only tools balance_check and day_shapes.

1.0.0-draft, 2026-10-09 (Timetable: the weekly plan)

• Additive. New operations: GET /admin/weekly-plans, GET and PUT /admin/sections/{section_id}/weekly-plans/{week}, PUT .../goals/{section_subject_id}, POST .../copy-goals, POST .../publish, GET /me/students/{student_id}/weekly-plans/{week}, and POST and DELETE /me/students/{student_id}/weekly-plans/{week}/goals/{goal_id}/tick. {week} is any date in the week; the plan is for its Monday. New schemas WeeklyPlan, WeeklyPlanGoal, WeeklyPlanDay, WeeklyPlanSummary, PlanPublish, BringRule; new tag Weekly plan.
• TimetableSettings and PUT /admin/settings/timetable gain plan_publish ({ weekday, time } or null) and bring_rules ([{ subject_id or block_type, text }]).
• New error codes PLAN_EMPTY (409: publishing with no note and no goal) and TICK_CLOSED (409: ticking after the Monday after the week). A read of a plan that does not exist yet returns an empty draft and writes nothing. Families see only published plans.
• New notice kind weekly_plan (in the app and by email) when a plan is published.

1.0.0-draft, 2026-10-09 (Timetable: class duties)

• Additive. New operations: GET and PUT /admin/sections/{section_id}/duties and POST /admin/sections/{section_id}/duties/rota. New schemas ClassDuty and DutyRota. WeeklyPlanDay gains duties: every duty with its students for staff, only the child's own duties (with no names) for a family.
• New error code ROTA_TOO_LONG (400): a rota is at most 12 weeks. More than 8 duties is TOO_MANY.
• An absent student's duty is shown with the next name in school for that day only; the stored rota does not change.

1.0.0-draft, 2026-10-09 (Email: see and resend my emails)

• Additive. New operations GET /me/emails and POST /me/emails/{id}/resend. New schemas MyEmail and MyEmails. Anyone signed in sees the emails the school sent them in the last 30 days, whether each went and, in plain words, why not, and can send one that did not go again (3 a day, RATE_LIMITED).
• The person someone viewed as is now emailed afterwards (impersonation_notice joins the email lane), as the View-as rules always said.

1.0.0-draft, 2026-10-09 (Timetable: Flex time)

• Additive. New operations: GET and POST /admin/flex, GET /admin/flex/where, PATCH and DELETE /admin/flex/{id}, POST /admin/flex/{id}/requests, GET /admin/flex/{id}/roster, PUT /admin/flex/{id}/attendance, GET /me/students/{student_id}/flex and PUT /me/students/{student_id}/flex/{on}/{period_no}. New schemas FlexOffering, FlexOfferingWrite, FlexDay, FlexRoster, FlexWhere, StudentFlex; new tag Flex.
• TimetableSettings and PUT /admin/settings/timetable gain flex_cutoff (default 10:00).
• New error codes FLEX_CLOSED, FLEX_FULL and FLEX_REQUESTED (409). A full session takes waitlist: true to join its waiting list; a freed seat goes to the first student waiting.

1.0.0-draft, 2026-10-10 (Timetable: Montessori work plans)

• Additive. New operations: GET /admin/work-cycle, GET and POST /admin/small-group-lessons, PATCH and DELETE /admin/small-group-lessons/{id}, GET and PUT /admin/students/{student_id}/work-plans/{week}, GET and POST /admin/students/{student_id}/journal, GET /me/students/{student_id}/work-plans/{week} and POST /me/students/{student_id}/journal. New schemas CycleTime, WorkCycleSections, SmallGroupLesson, SmallGroupWrite, WorkPlanItem, JournalEntry, JournalWrite and WorkPlan; new tag Work cycle.
• New error code JOURNAL_CLOSED (409): a child adds to the journal only during a work cycle of their class today.

Planned, 2026-10-11 (saMas Scholars School and Learn)

• Nothing changes in this entry; it records what the next entries will add, so partners see the direction. PRD 5.11, TDD 6D, docs/learn/api.md and docs/integrations/samas-charity.md hold the detail.
• Student API (me), new tags Learn and Charity: /me/learn/home, /me/learn/courses and /{id}, /me/learn/notes with /{id}, /upload-url, /images, /read, /proposal, /accept; /me/learn/courses/{id}/map, /map/all, /map/list, /notes, /slots, /evaluation; /me/learn/map/topics/{id}; /me/learn/concepts/{id} with /merge and /path; /me/learn/exams with /{id}, /{id}/result, /{id}/plan, /datesheet-read; /me/learn/plan/tasks/{id}; /me/learn/prep-settings; /me/learn/practice with /{id}/answers and /{id}/finish; /me/learn/explain; /me/learn/posts with /{id}, /save, /versions, /diff, /publish; /me/learn/publishing with /connect and /disconnect; /me/learn/search, /history, /edits and /edits/{id}/undo, /export, /delete and /delete/undo, /road, /journey, /week; /me/charity, /me/charity/link, /me/charity/vouchers with /upload-url and /read; /me/students/{student_id}/learn/summary and /charity/vouchers.
• School API: /school/learn/students, /school/learn/settings, /school/learn/costs, /school/charity/links (GET and POST), /school/charity/vouchers. New scopes write:charity_links and read:learn_summary. POST /school/students is the second call of the charity's invite pair; nothing about it changes.
• Platform: /platform/schools/{id}/charity-sync, /platform/charity/replay, /platform/learn/students/{id} (and /notes, /map, /posts; read only, reason required, logged), /platform/trace. Learn and the charity link are add-ons (see the entry below), not flags; finer settings come with the phase that needs them.
• Outside the documents, like the Leonardo hook: POST /hooks/samas-charity, HMAC signed.
• New error codes (29) under LEARN_* and CHARITY_*, listed in docs/learn/api.md, each with help text when they land.
• Student gains charity: { linked, status, since }; GET /me gains learn and charity blocks. All additive.

2026-10-11, welcome letters and the paper look

• POST /admin/people/{id}/welcome gains letter (schema WelcomeLetter: the school's own words for one person, sent in the letter design, optionally with the whole letter in another language as text and as a picture) and cc (up to 3 addresses; TOO_MANY, INVALID_EMAIL). Additive.
• Added GET /admin/people/{id}/emails and GET /admin/people/{id}/emails/{email_id} (schema PersonEmail): the welcome emails on a person's record, with when each was first opened, whether they have signed in, and the email exactly as sent.
• Added GET /school/public/email-open/{token}: the open picture in welcome emails. No credentials; always the same 1 by 1 GIF.
• Branding and BrandingWrite gain style (BrandStyle: standard or paper). BrandFont gains hanken-grotesk. BrandingUpload.kind gains letter_image. Clients that switch on the font or upload kind should treat unknown values as the default.
• WelcomeLetter gains picture_image_upload_id: the school's own picture at the top of a letter (uploaded with kind letter_image). Additive.

1.0.0-draft, 2026-10-11 (Scholars School, phase 0b: add-ons, fonts, scopes)

• Additive. Two more add-ons beside madrasa: learn and charity. Session.add_ons, AddOn.add_on and the add_on path parameter of PUT /admin/settings/add-ons/{add_on} accept all three. ADD_ON_OFF now names the add-on that is off in its hint; its message is general.
• BrandFont gains bricolage, figtree and noto-nastaliq-urdu.
• School keys may carry read:learn_summary and write:charity_links (no operation uses them yet; they arrive with phases 1 and 3).

2026-10-11, Smarty's daily report

• Added GET /ops/help/daily-report (schema HelpDailyReport) and POST /ops/help/daily-report/send: the numbers for the last 24 hours against the week, each school by name, the questions to look at with the person's vote and Smarty's second try, and a send-now. The nightly job asks badly answered questions again with the large model and emails the report to super admins.
• View as: reason is no longer required by the contract on POST /platform/view-as and POST /admin/view-as. A super admin may leave it out for a quiet session, which is recorded but emails nobody; a school admin still gives one (REASON_REQUIRED). ViewAsSession.reason and the sessions list's reason may be null.

2026-10-11, Learn phase 2a: courses, notes, the week and History

• Added, Student API (tag Learn, add-on learn, ADD_ON_OFF when off): GET /me/learn/home, GET|POST /me/learn/courses, GET|PATCH /me/learn/courses/{course_id}, GET /me/learn/courses/{course_id}/notes, PUT /me/learn/courses/{course_id}/slots, GET /me/learn/week, POST /me/learn/notes, GET|PATCH /me/learn/notes/{note_id}, POST /me/learn/notes/{note_id}/upload-url, POST /me/learn/notes/{note_id}/pictures, DELETE /me/learn/notes/{note_id}/pictures/{picture_id}, GET /me/learn/history. Schemas LearnHome, LearnCourse, LearnCourseWrite, LearnCourseCreate, LearnSlot, LearnSlotInput, LearnWeek, LearnNote, LearnNoteDay, LearnPicture, LearnUpload, LearnUploadRequest, LearnPictureAdd, LearnEvent, LearnSettings.
• Added, Admin API (people only, school admins; a key is refused even for reads): GET /admin/learn/students/{student_id}, POST /admin/learn/students/{student_id}/courses, GET /admin/learn/students/{student_id}/week, GET /admin/learn/students/{student_id}/history, PATCH /admin/learn/courses/{course_id}, GET /admin/learn/courses/{course_id}/notes, PUT /admin/learn/courses/{course_id}/slots, POST /admin/learn/notes, GET /admin/learn/notes/{note_id}, POST /admin/learn/notes/{note_id}/upload-url, POST /admin/learn/notes/{note_id}/pictures, GET|PUT /admin/learn/settings.
• New error codes: LEARN_COURSE_TITLE, LEARN_COURSE_CODE_LONG, LEARN_TOO_MANY_PICTURES (409), LEARN_STAFF_ACCESS_OFF (403). All additive.

2026-10-11, the garden look

• BrandStyle gains garden: an ivory courtyard with a faint eight-point star lattice, Amiri headings and a deep green sidebar edged in gold. Accepted by PUT /admin/branding and PUT /platform/schools/{id}/branding, returned by every Branding. Additive.

2026-10-12, webhook deliveries for Quran reading apps

• Contract corrected: WebhookDelivery.event also lists link.approved, link.revoked, recitation.reviewed and ping, and WebhookDelivery.status also lists skipped_unlinked, as the API already returned for a school with a connected Quran reading app. GET /admin/webhook-deliveries failed its response check for such a school. Clients should treat unknown events and statuses as informational. WebhookEvent (what a school endpoint subscribes to) is unchanged.
• GET /admin/webhooks and GET /school/webhooks list only the school's own endpoints. A connected Quran reading app's endpoint (with its own events) was listed too and failed the response check; it is managed under Settings, Quran reading apps.
• GET /admin/staff/{user_id}/sanad answers NOT_FOUND for anyone who is not staff at the caller's school (it answered with empty fields for any id), and confirmed is false, not null, before a sanad is written. PUT refuses the same way.

2026-10-11, a notice by email (A16) and the super admin as incharge

• Added POST /admin/notices (people only): a short notice by email to up to 50 chosen people of the school, optionally with the same text in another language, copied to up to 3 addresses; answers who was queued and who was skipped and why. Notices appear on the person's record beside welcome emails (GET /admin/people/{id}/emails, kind school_notice). Additive.
• Learn: a super admin working inside the school may use the /admin/learn operations as a scholar's incharge, logged in her History like a school admin. No contract change.

2026-10-12, a picture in a notice

• POST /admin/notices takes an optional picture_upload_id (from POST /admin/branding/uploads, kind letter_image) and picture_caption (up to 500 characters, only with a picture). The picture is shown under the message. Unknown or expired upload ids answer NOT_FOUND. Additive.

2026-10-12, What's new on the Help page (H6)

• Added GET /me/help/whats-new (schema WhatsNewItem): short lines about what changed, newest first, only those for the caller's role (super admins also get the super admin lines) and only those whose add-on (madrasa, learn) the school has on. Each line may carry try_it (a screen and a help anchor) for Try it now. At most 10 (limit 1 to 10, default 10; OUT_OF_RANGE outside). The lines ship with each release, from src/help/catalog/whats-new.json. Additive.

2026-10-13, Report a problem from anywhere (phase 2)

• IssueWrite takes optional incident (schema IssueIncident: the error the person hit, with its reference), requests (up to 30 IssueRequestSeen: route pattern, status, time taken, reference), steps (up to 30, screen:<route> or tap:<help anchor>) and device (schema IssueDevice). IssueContext returns them. Additive.
• Added GET /ops/requests/{request_id}: the server's record of one request (route, status, time, error code, school). Additive.
• OpsAlert.key lists route_failing, cache_writes_refused, plan_usage and the new report_waiting. Additive.

2026-10-13, Readable stacks and the browser's console (phase 3)

• IssueWrite takes optional console (up to 100 IssueConsoleLine: errors, warnings and blocked loads, each once with a count, first and last time, and for errors our own stack frames). IssueIncident takes optional stack. IssueContext returns both. Additive.
• Added GET /ops/sourcemaps/{commit}: the web app's source maps for one build, gzipped, for the triage screen. Additive.

2026-10-13, Reports from outside the app (phase 4)

• Added POST /school/public/problem-reports (public, schema OutsideReportWrite): a problem report without signing in, for when the account or the app will not load. Answers { ref } (OUT-YYYY-NNNN). 5 a day from one address and 200 a day in all (ISSUE_LIMIT). Additive.
• Added GET /platform/outside-reports and POST /platform/outside-reports/{id}/close (schema OutsideReport). Additive.

2026-10-13, Errors nobody reports (phase 5)

• Added POST /me/client-errors (schema ClientErrorSeen): the web app sends each distinct browser error once per session. Answers { accepted, kept }. Additive.
• Added GET /platform/client-errors (schema ClientErrorGroup): the errors grouped, with hits, people, first and last time and versions. Additive.

2026-10-13, A fix is shown, and the school is told

• POST /platform/issues/{id}/fixed takes IssueFixedWrite: the note as before, and optional picture_upload_ids (up to 3, from the new POST /platform/issues/{id}/upload-url). The email to the reporter attaches the pictures and is copied to the super admin who marked it and to the school's admins. IssueMessage gains pictures. Additive.

2026-10-13, Everyone who can be a guardian is in the list

• Added GET /admin/guardian-choices (schema GuardianChoice): the people the office can link as a guardian, including staff who also hold the parent role at the school and parents whose account belongs to another school first, each with also saying what else they are. Parameter q (80 characters at most). Additive.
• The Platform Labs operations (signed in only) now pass the admin site check on the staff admin site; the database still checks saMas staff for each. No contract change.
• Added POST /platform/schools/{id}/update-email (schemas SchoolUpdateWrite, SchoolUpdateQueued): the saMas team tells a school's admins and principals, and the finance in-charge for finance changes, about a fix or a new feature, copied to the sender. Additive.
• Added POST /platform/schools/{id}/update-email/upload-url; SchoolUpdateWrite gains picture_upload_ids (up to 3) and SchoolUpdateQueued gains pictures: the update email to a school's admins carries pictures of the fix or feature as attachments. Additive.

2026-10-14, I have paid

• Added POST /me/invoices/{id}/paid (schema ClaimWrite): a parent answers a fee reminder with the day, method, amount and reference, slip optional. It is a payment proof of kind claim in the office's queue; finance is told at once; reminders pause for the invoice (GET /admin/reminders/skipped, new) and resume if the office returns it. Errors CLAIM_OPEN, REFERENCE_REQUIRED, INVALID_AMOUNT.
• Proof gains kind (slip or claim), invoice_id, invoice_no and paid_on; ProofWrite.upload_id is optional (a proof without a file is a claim). Additive.
• School.settings.fee_reply_to and the same key on PATCH /admin/settings: the school's fee contact; fee reminders and receipts carry it as Reply-To. Additive.
• New notification kind payment_claimed to every finance in-charge (school admins when there is none), in the app and by email, with a Match it link.

2026-10-14, data entry E1: the form system and the office home

• OfficeOverview gains tasks (schema OfficeTask: what needs a person today, computed on read, with kind, count, title, detail and link) and actions (schema OfficeAction: the six things the office does most with their 30-day save counts, most used first). Additive; GET /admin/dashboard/overview is the office home in one call.
• HelpEvent.kind gains save (a form was saved; screen says which), easy and not_easy (Was this easy? after the first saves on a reshaped screen). Additive.
• Every request may carry an X-Screen header (the page's screen key, ^[a-z0-9-]{2,60}$); the request log keeps it so refusals after Save can be counted per screen. Optional; other values are ignored.

2026-10-14, data entry phase E2 (enrol, attendance and marks)

• POST /admin/students takes StudentEnrol (every StudentWrite field, admission_no now optional, plus guardian, schema GuardianEnrol): the child and the family in one call. guardian.person_id links a parent already at the school; guardian.full_name with a phone or an email invites a new one through the same path as POST /admin/people (parent role, welcome email queued) and links them. One transaction. Without admission_no the next free one from the school's pattern is used. Errors ADMISSION_NO_TAKEN, ROLL_NO_TAKEN (who, masked, and the next free one in details) and GUARDIAN_PHONE_IN_USE (whose, masked, in details.person_id). Additive: today's callers keep working.
• Added GET /admin/students/next-admission-no (schema NextAdmissionNo) and GET /admin/sections/{section_id}/next-roll-no?roll= (schema NextRollNo): the numbers to offer, never reserved.
• GuardianChoice gains children (the students they are a guardian of here, with class and section) and signed_in. Additive.
• Error gains details: an object of facts beside the hint when the server has them (the next free number, who holds a phone, the next school day). Additive.
• PUT /admin/sections/{section_id}/attendance gains source (screen, yesterday, photo; default screen), kept on the day. A closed day or a holiday is refused with DAY_CLOSED and details.next_school_day. Additive.
• Added POST /admin/sections/{section_id}/attendance/upload-url (schema PhotoUpload, 10 MB, JPEG, PNG or WebP) and POST /admin/sections/{section_id}/attendance/read-photo (schema AttendancePhotoRead): a photo of the paper register read into one proposed status per roll with a confidence; nothing is saved; the picture is deleted after the read. Error ATTENDANCE_PHOTO_UNREADABLE.
• PUT /admin/assessments/{id}/marks rows and Mark gain exempt beside absent. Added POST /admin/assessments/{id}/upload-url and POST /admin/assessments/{id}/read-photo (schema MarksPhotoRead): a photo of the paper mark sheet read into one proposed value per roll. Additive.
• School.settings.admission_no_prefix and the same key on PATCH /admin/settings: letters, digits and hyphens (10 at most) in front of the admission numbers the school offers. Additive.

2026-10-14, The issue loop

• Platform keys may hold read:issues, write:issues and write:school_updates: POST /platform/issues/{id}/messages, /upload-url, /fixed and the new /link take a key with write:issues; POST /platform/schools/{id}/update-email and its upload-url take write:school_updates. ApiKey.notify_email and the same field on POST /platform/platform-keys plus PATCH /platform/platform-keys/{id}: the person copied on what a key sends.
• Added POST /platform/issues/{id}/link (duplicate_of): a report linked to an earlier one is fixed and closed with it; Issue.duplicate_of; event kinds linked and unlinked.
• Added GET /platform/issues/sweep (schema SweepRow): every open app report in piles for a machine.
• Added the fixer's runs under Ops: GET /ops/issues/fixer/runs, POST /ops/issues/fixer/runs and PATCH /ops/issues/fixer/runs/{id} (a key with write:issues), POST /ops/issues/fixer/run (ask for a run; super admin). Schema FixerRun.

2026-10-15, Issue fixer: gradebook, weekly plan, timetable

• PUT /admin/assessments/{id}/marks: feedback may be null (clears the note). The gradebook always sent null for a cell with no note and every save was refused with INVALID_TYPE (demo report PRB-2026-0004).
• Student.user_id (the student's own sign-in, or null) is on every student list, not only StudentDetail. Additive. Users and roles uses it to count enrolled students who have no sign-in (beta report PRB-2026-0008).
• GettingStarted.preparing_for: the roads whose school-wide items a finance in-charge sees and may tick or skip on behalf of the school (migration 20261116100200). Additive.

2026-10-20, Reports in one view, round one (PRD 5.15)

• Added GET /platform/issues/overview (schema IssuesOverview): tiles, one row per active school, reported against fixed per week, aging, top screens and roles, and what needs a person, for a window of 7, 30, 90 days or all. Super admins.
• GET /platform/issues gains filters: status=closed_stale, age (under_1d, d1_3, d3_7, over_7, open reports only) and private.
• Added POST /platform/issues/{id}/close-stale: closes a report marked fixed 14 days ago when the reporter said nothing, with one email; a platform key with write:issues may call it.
• GET /admin/issues gains owner (office, the default and unchanged; or samas: the app problems and ideas this school's people sent to the saMas team). GET /admin/issues/{id} and POST /admin/issues/{id}/messages work on those reports too (read and add a note). Added GET /admin/issues/summary (schema AdminIssuesSummary).
• Issue gains private_to_samas, closed_reason and, for the school office on a saMas report, priority_word (the office's priority and assignee are null there). IssueWrite gains private_to_samas. SweepRow gains private_to_samas. FixerRun.summary documents ideas_linked, ideas_proposed, closed_stale and reason.
• Added GET /ops/review-feed (schema ReviewRow): what needs a person, as rows with a stable key and done; super admins or a platform key with read:issues.
• Additive.

2026-10-20, Reports in one view, round two: the roadmap (PRD 5.15)

• Added the Roadmap tag. Platform: GET and POST /platform/roadmap, GET and PATCH /platform/roadmap/{id}, POST /platform/roadmap/{id}/stage, /confirm, /decline, /merge, /ideas, DELETE /platform/roadmap/{id}/ideas/{issue_id}, GET /platform/roadmap/{id}/history, POST /platform/roadmap/{id}/release/upload-url, GET /platform/roadmap/{id}/release/preview, POST /platform/roadmap/{id}/release. A platform key with read:issues reads the roadmap; with write:issues it proposes (from an idea, five per run, LIMIT) and links ideas; everything else is a super admin session. Schemas RoadmapStage, RoadmapItem, RoadmapItemDetail, RoadmapChange, RoadmapIdea, RoadmapItemWrite, RoadmapItemPatch, RoadmapRelease, RoadmapReleaseResult, RoadmapReleasePreview, RoadmapSchoolItem.
• Admin: GET /admin/roadmap (schema RoadmapSchoolItem). GET /admin/issues/summary's ideas_on_roadmap now counts.
• GET /platform/labs/roadmap-weights: how many items and schools point at each design.
• Issue gains roadmap_item; SweepRow gains roadmap_item_id (an idea on the roadmap leaves the sweep). GET /platform/issues gains roadmap_item_id.
• New error codes: PICTURE_REQUIRED, SAME_ITEM, LIMIT.
• Additive.

2026-10-21: Learn study guides and share links (PRD 5.11.10)

• Added PUT, PATCH and DELETE /admin/learn/notes/{note_id}/guide (schemas LearnGuideWrite, LearnGuide, LearnGuideSection, LearnGuideFormula, LearnGuideTable, LearnGuideCheck, LearnGuideFile): the incharge's structured study guide for a note, with its pictures, and the email to the scholar when notify is true.
• Added POST and DELETE /admin/learn/notes/{note_id}/share-link (schema LearnShareLink): one active magic link per note, answered with the token and the URL to copy.
• Added GET and PATCH /admin/learn/students/{student_id}/settings, GET and PATCH /me/learn/settings (schema LearnScholarSettings): the scholar's first-name consent for shared guides, with a reason when the incharge sets it.
• Added PATCH /me/learn/notes/{note_id}/guide: the scholar hides her guide from her own view.
• Added public GET /school/public/learn/n/{token} (schema LearnPublicGuide, LearnPublicPicture) and GET /school/public/learn/n/{token}/download/{kind}: the shared guide page and its PDF and ZIP, no credentials.
• LearnNote gains guide, share_link and guide_source_hash; LearnUploadRequest gains kind, role, ordinal, width, height and the content type application/zip (guide files only); LearnEvent.kind gains guide_added, guide_updated, guide_removed, share_link_created, share_link_revoked, share_link_viewed, share_name_changed; LearnSettings gains scholars_share_guides. All additive.
• New error codes: LEARN_LINK_INACTIVE, LEARN_GUIDE_NEEDS_PICTURES, LEARN_GUIDE_STALE, LEARN_GUIDE_PICTURES_MISSING.

1.0.0-draft, 2026-10-21 (Learn evening email)

• LearnScholarSettings gains daily_email, daily_email_changed_at and daily_email_changed_by_kind; PATCH /me/learn/settings and PATCH /admin/learn/students/{student_id}/settings accept daily_email (PRD 5.11.11, L77). share_name_publicly is now optional on both; send one or both fields (MISSING_FIELD with neither).
• LearnSettings gains daily_email and the copy list daily_email_cc_on, daily_email_cc, daily_email_cc_changed_at, daily_email_cc_changed_by (L79); PUT /admin/learn/settings accepts daily_email, daily_email_cc_on and daily_email_cc, and staff_access is now optional there (send any of them).
• LearnEvent.kind gains daily_email_changed.
• LearnGuideWrite.notify no longer emails at once: a replaced guide goes in the scholar's evening email (L74). New guides are always in it.
• POST /ops/jobs/{name}/run gains the job learn_daily_email (L80): run the evening email on demand for every school or one. Before 8 pm school time it sends yesterday's email; from 8 pm, today's. It is listed in GET /ops/jobs.

1.0.0-draft, 2026-10-21 (Learn by platform key)

• Scopes read:learn and write:learn, for platform keys only (a school key cannot be made with them). Every Learn operation of the Admin API (/admin/learn/...) now takes them (x-scopes, with x-platform-key-only) instead of being for signed-in people only; school and partner keys are refused there whatever their scopes (PRD L54, L81).
• Header X-School-Id on the Admin API: a platform key names the school it works in for that request. Without it, a platform key's call answers SCHOOL_REQUIRED (400, new code). People and school keys ignore it.
• GET /admin/students and GET /admin/people are also open to a platform key with read:learn (x-learn-lookup), to find a scholar; unchanged for everyone else.

1.0.0-draft, 2026-10-22 (scholar coordinators and Add notes)

• GET /me/learn/coordinating and POST /me/learn/coordinating/{student_id}/courses: the scholars I coordinate and a course for one of them (PRD L82, L83). A coordinator then uses POST /me/learn/notes and the upload and picture routes for her scholars' courses.
• GET, POST /admin/learn/students/{student_id}/coordinators and DELETE /admin/learn/students/{student_id}/coordinators/{user_id} (with a reason): her incharge names and removes coordinators (Learn key too). Schemas LearnCoordinator, LearnCoordinatorAdd, LearnCoordinatorRemove, LearnCoordinated.
• LearnPicture.sha256; LearnNote.picture_count, fingerprints and duplicate_of. Adding a picture already on the day answers 200 with duplicate_of instead of 201 (L85). LearnPicture.added_by_kind and LearnEvent.actor_kind gain coordinator; LearnEvent.kind gains coordinator_added and coordinator_removed.

1.0.0-draft, 2026-10-22 (a coordinator's copy of the evening email)

• PATCH /admin/learn/students/{student_id}/coordinators/{user_id} (schema LearnCoordinatorChange): her incharge turns a coordinator's copy of the scholar's evening email on or off (PRD L87). The copy carries only the study guides that have a share link. LearnCoordinator gains email_copy and has_email; LearnEvent.kind gains coordinator_email_changed.

1.0.0-draft, 2026-10-22 (course materials, rating study guides, the guide queue)

• GET, POST /me/learn/courses/{course_id}/materials, POST .../materials/upload-url, DELETE .../materials/{material_id}, and the same on /admin/learn/courses/{course_id}/materials (Learn key too): files from her books and classes, a PDF, PowerPoint or picture up to 20 MB, 40 a course; the same file twice answers 200 with duplicate_of (PRD L88 to L90). Schemas LearnMaterial, LearnMaterialUploadRequest, LearnMaterialAdd.
• GET, PUT /me/learn/notes/{note_id}/feedback, GET /admin/learn/notes/{note_id}/feedback, GET /admin/learn/feedback, POST /admin/learn/feedback/{feedback_id}/answer: she rates a study guide 1 to 5 and suggests changes; her incharge answers changed or kept (L91 to L93). Schemas LearnFeedback, LearnFeedbackWrite, LearnFeedbackAnswer.
• GET /admin/learn/guide-queue (schema LearnGuideQueueItem): the notes waiting for a study guide, read by the evening run (L94).
• LearnEvent.kind gains material_added, material_removed, guide_rated and feedback_answered.

1.0.0-draft, 2026-10-22 (overview tiles open the rows they count)

• GET /platform/issues gains severity, since, fixed_since and confirmed_since (additive), so every count on the overview opens the rows behind it (RV9).
• GET /platform/issues/overview is for signed-in super admins only (x-people-only): an API key is refused whatever its scopes, as the design always said; keys read the Queue and the review feed.
• IssuesOverview.tiles.unanswered_in_window (additive): the window's open reports with no first reply yet, shown beside the median first reply (review L4).

1.0.0-draft, 2026-10-23 (samas.school: the public site, school requests, set-up, the first run)

• School API, no credentials (docs/api/public-site.md, PRD 5.16): GET /school/public/site/home (schema SiteHome), GET /school/public/site/roadmap (SiteRoadmap, SitePublicItem), GET /school/public/site/updates (SiteUpdates), POST /school/public/site/requests (SiteRequestWrite, SiteRef), POST /school/public/site/ideas (SiteIdeaWrite), POST /school/public/site/roadmap/{id}/vote (SiteVote, SiteVoteResult). Writes answer 204 when the website field is filled.
• Admin API: GET, PATCH /admin/onboarding, PUT /admin/onboarding/samples, POST /admin/onboarding/finish (schema Onboarding); DELETE /admin/learn/students/{student_id}/first-run.
• Student API: GET, POST /me/learn/first-run (schema FirstRun).
• Platform API: GET /platform/site/requests, PATCH /platform/site/requests/{id} (SiteRequest, SiteRequestPatch), GET, POST /platform/site/quotes, PATCH /platform/site/quotes/{id} (SiteQuote, SiteQuoteWrite, SiteQuotePatch), PUT /platform/schools/{id}/public-listing (PublicListingWrite, PublicListing), PUT /platform/roadmap/{id}/public (RoadmapPublicWrite, RM13a), POST /platform/outside-reports/{id}/roadmap (OutsideReportRoadmap).
• Additive fields: RoadmapItem gains public, public_votes, public_wishes; RoadmapChange.kind gains public; OutsideReport gains kind (problem or idea), title, requester_kind and roadmap_item.
• Error codes SITE_LIMIT (429), SITE_NOT_ELIGIBLE (409), ONBOARDING_DONE (409).
• LearnEvent.kind gains first_run_seen and first_run_reset.
• PATCH /admin/settings body lists settings.email_receipts (on or off), which the database always took; the set-up steps switch it.

1.0.0-draft, 2026-10-24 (samas.school: the doors know who is signed in)

• School API, additive: GET /school/public/site/whoami (schema SiteWhoami: kind none, admin, scholar or other; school_subdomain and url for admin and scholar). Public; reads an optional bearer sign-in token; never cached. PRD 5.16 HM2, HM37.

1.0.0-draft, 2026-10-24 (samas.school: the hero register's names)

• School API, additive: SiteHome.hero_names (up to three {display}, empty until scholars agree; HM26).
• Platform API: GET, PUT /platform/site/hero-names (schemas SiteHeroNames, SiteHeroNamesWrite). Setting names needs agreed_on and consent_note (REASON_REQUIRED); an empty list clears them.

1.0.0-draft, 2026-10-24 (home v4: live-class links, I'm here, the first-day tour, hero brands)

• Admin API, additive: PUT /admin/sections/{section_id}/timetable/live-links (schemas TimetableLiveLinkWrite, TimetableLiveLink): the office or the lesson's teacher sets or clears one published lesson's live-class link, without republishing (HM38).
• Additive fields: TimetableLesson.live_url and TimetableSlot.live_url (optional, string or null) wherever a week, a section timetable, a child's timetable or a teacher's week is read, for staff and the class's own students and families; NowLesson.live_url and NowLesson.period_no (never on the public board). Period is unchanged.
• Student API, additive: POST /me/students/{student_id}/timetable/here (schemas SelfAttendanceWrite, SelfAttendance): I'm here, the student marks herself present while a live lesson is on (HM40).
• School.settings and the PATCH /admin/settings body gain self_attendance (on or off, off by default).
• Onboarding gains tour_seen_at, show_tour and self_attendance; PUT /admin/onboarding/tour ({seen}) marks the first-day tour seen or shows it again (HM41).
• School API, additive: SiteHome.brands (schema SiteBrand, six at most): each listed school's name, subdomain, address, colours, font, style and public crest (HM42).
• Error codes LIVE_LINK_HOST (400), SELF_ATTENDANCE_OFF (409), NOT_LIVE_NOW (409).

1.0.0-draft, 2026-10-24 (platform roles)

• Platform API, additive: GET /platform/platform-roles, GET /platform/platform-roles/events, POST /platform/platform-roles/{role}/members, DELETE /platform/platform-roles/{role}/members/{user_id} and POST /platform/platform-roles/{role}/members/{user_id}/welcome (schemas PlatformRole, PlatformRoleMember, PlatformRoleEvent): roles that live above schools, added by email to existing accounts only (NO_SUCH_USER), every change logged. Super admins, people only.

1.0.0-draft, 2026-10-25 (study guides on demand)

• Admin API, additive: POST /admin/learn/notes/{note_id}/guide-request (Make the study guide now, L97) and POST /admin/learn/notes/{note_id}/guide-skip (schema LearnGuideSkip, no guide needed, L98). Both answer the LearnNote.
• LearnNote gains guide_request (schema LearnGuideRequest: waiting, requested_at, skipped, skip_reason, skipped_at).
• LearnGuideQueueItem.reason gains requested, and the item gains requested_at; asked-for days come first. History event kinds gain guide_requested and guide_skipped.

1.0.0-draft, 2026-10-25 (weekly plan review)

• Admin API, additive: GET and POST /admin/sections/{section_id}/weekly-plans/{week}/comments and DELETE /admin/sections/{section_id}/weekly-plans/{week}/comments/{comment_id} (schemas WeeklyPlanReview, WeeklyPlanComment): staff comment on a section's weekly plan and the principal or the school admin marks it checked (TT74). Families never see the review.
• WeeklyPlanSummary gains checked and comments.

1.0.0-draft, 2026-10-25 (course links)

• Student API, additive: GET /me/learn/courses/{course_id}/where (schema LearnCourseWhere, L107): whose course a link is for and whether the caller opens it as the scholar or as her incharge, and in which school. Lets the evening email's links work for a school admin or super admin who opens them.

1.0.0-draft, 2026-10-27 (Live Sabaq count check and audit retention)

• Platform API, additive: POST /platform/live/reconcile also removes audit lines older than 2 years (LV55) and answers trimmed (per school: lines removed and the anchor); each chain in chains gains anchor. The day rows of GET /admin/live/usage now fill provider_minutes and difference_pct from the audio service's own events (LV46).

1.0.0-draft, 2026-10-27 (Live Sabaq recording is never silent)

• Admin API, additive: POST /admin/live/sessions/{session_id}/recording/status (the teacher's recorder says it is running, and gets the segment to record into, or that it failed and why). Each answer is a line in the session's audit trail: recorder_running, or recording_failed with the reason and the new code LIVE_NOT_RECORDING.
• POST /admin/live/sessions/{session_id}/recording/finish writes a recording_failed line (reason no_parts) when no part of the recording arrived.

1.0.0-draft, 2026-10-27 (Live Sabaq archive and delete)

• Admin API, additive: POST /admin/live/sessions/{session_id}/archive and POST /admin/live/sessions/{session_id}/unarchive (body { reason? }; school admins, principals and super admins; LV61, LV62). GET /admin/live/sessions gains the query archived (also list archived sessions, the office only) and answers archived_hidden; the staff session shape gains archived. New codes LIVE_ARCHIVED (a teacher or the family opening an archived session) and LIVE_NOT_OVER (archiving a session that is scheduled or live).
• Platform API, additive: GET /platform/live/sessions/{session_id} (look a session up in any school: what a delete removes and keeps, and whether it can go now) and POST /platform/live/sessions/{session_id}/delete (body { reason }, super admins only; LV63, LV64). New code LIVE_HELD (an open report or a held recording); LIVE_REASON_REQUIRED and LIVE_ALREADY_LIVE are reused. Session report answers gain session.deleted; audit lines gain session_gone.
• Partner API, behaviour only (no shape change): archived and deleted sessions are left out of GET /partner/live/sessions, and their join, token, review, play and report routes answer NOT_FOUND (contract.md change log).

1.0.0-draft, 2026-10-27 (payment processing fixes)

• Admin API, contract corrected: WebhookDelivery.event lists live.session.started and live.session.ended, which a connected Quran app's endpoint has received since Live Sabaq shipped; the delivery list answered INTERNAL for a school with those deliveries.
• GET /finance/dashboard gains claims_waiting_long (claims and slips waiting more than 7 days). The office home's task kind gains invoices_missing (active students with no invoice this month once the generate day has passed, and students with no section).
• Student API, meaning change of a field value: Proof.kind now follows the invoice, not the file. claim is a parent's "I have paid" on one invoice (POST /me/invoices/{id}/paid), with or without a slip attached; slip is a proof sent by month (POST /me/proofs), with or without a file, tied to no invoice. Before this a claim with a slip attached was reported as slip, and a month proof with no file as claim. Proof.invoice_id is set for a claim and null for a slip, as before; the descriptions say so.
• Student API, validation: POST /me/proofs and POST /me/invoices/{id}/paid now require Idempotency-Key (400 MISSING_FIELD, field /header/Idempotency-Key), like every other money write. The upload_id on either is one-time: submitting it again answers NOT_FOUND on /upload_id.
• Student API, behaviour: GET /me/statement without from and to returns the last 30 days up to the school's today (it refused with MISSING_FIELD before). Given dates are used as they are.
• School API, behaviour: GET /school/proofs honours the documented fee_month filter (any day in the month; it was ignored).
• Admin and Finance APIs, additive: GET /admin/payments and GET /finance/payments take status (confirmed or reversed).
• Finance API, validation: POST /finance/refunds/{id}/decide now requires Idempotency-Key. Its description names ALREADY_DECIDED for a refund decided before.
• Admin and Finance APIs, validation: the amounts a client writes (PaymentWrite.amount, RefundWrite.amount, ProofWrite.amount, ClaimWrite.amount) must be non-negative (^\d+\.\d{2}$, 400 INVALID_MONEY). Amounts the API returns keep the signed pattern.
• Finance API, text: PaymentWrite.reference says that on POST /school/payments an external_ref, when sent, is stored as the receipt reference and reference is ignored. SchoolDocument.status no longer says parsing comes later (lines are read into GET /finance/documents/{id}/lines). The Finance API description lists refunds, month close, documents and bank statement lines. The refund, refund decision and month close descriptions say a school API key with write:fees passes the gateway but the database refuses it (NOT_ALLOWED); these are a person's acts. ReminderRule.channel keeps whatsapp in the enum and says a rule with it is refused (INVALID_ENUM) until WhatsApp reminders ship.
• Gateway, behaviour: reversing a payment, voiding an invoice, releasing a hold and deciding a discount (on /finance and the deprecated /admin twins) now need a second factor within the last 10 minutes (STEP_UP_REQUIRED), like refunds and month close.

1.0.0-draft, 2026-10-27 (the Learning API)

• A new document, the Learning API (learning.json, /v1/learning): course packs, Assess (responses scored by expert models with the tutor as arbiter), Encourage (goals, streaks, leagues, badges, nudges, earned days) and the tutor, reusable by any course (PRD 5.20, docs/learning/api.md). Registered with no operations; each phase declares its operations when it builds them. Internal until then.

1.0.0-draft, 2026-10-27 (schools by platform key)

• Platform API, additive: a new scope write:schools (platform keys only) lets our own automation set a school up the way the Scholars school is made: POST /platform/schools, PUT /platform/schools/{id}/branding and the new PUT /platform/schools/{id}/add-ons/{add_on} are open to a platform key with it, besides super admins. The new operation (schema AddOn, body state on, trial or ended and trial_days 1 to 90) is the school admin's add-on switch for any active school (NOT_FOUND for an unknown add-on or an inactive school; INVALID_STATE as the admin switch answers), and every change is an audit row.