Changelog
Track external API changes and documentation updates over time.
How Versioning Works
The contract version lives in the URL: /api/external/v1. It only changes when something breaks backward compatibility, so a new path means you must act.
Within a contract version we ship dated releases. Releases add optional fields, new endpoints, and fixes. Existing integrations keep working without changes, so you can adopt a new capability whenever it suits you.
Practical rule: watch the version path for breaking changes, watch this page for new capabilities.
v1 — current contract, stable
Releases are listed newest first below
Anything marked Added is optional unless stated otherwise
Release 2026-11-02 — Chapter and lesson position
A chat can now be pinned to the chapter or lesson a student is actually on, and optionally held there. Previously a conversation carried the course and nothing deeper, so the tutor could not tell a chapter the student had reached from one they had not — which is why a student on a lesson page could get a full answer about material from later in the book.
No change is required to existing integrations. Send nothing new and conversations behave exactly as before. Note the level mapping before you start: your Chapter is our lesson_id and your Lesson is our section_id.
Added: optional
lesson_idon POST /chats — a chapter (our lessons table)Added: optional
section_idon POST /chats — a lesson (our sections table)Added: optional
sequence_policy—open(default) orfocusSend the deepest id you have; the course above it is resolved for you, and a
subject_idsent alongside must agreefocuskeeps the student on the current chapter while leaving earlier chapters and general maths questions fully openfocusis guidance, not a lock — see If Material Must Be Withheld on the Chats page for what can and cannot be enforcedThe policy is fixed when the chat is created and inherited by every later message
Changed:
course_idmay now accompanylesson_idorsection_id, not onlysubject_idUnchanged: v1 path, every existing request and response field
Release 2026-10-20 — Student data deletion
You can now request erasure of one student's data through the API, and check the state of that request. See the Student Data Deletion page.
No change is required to existing integrations. This closes the gap where the only way to ask was to email us.
Added: POST /students/{external_user_id}/deletion-request (requires
chat)Added: GET /students/{external_user_id}/deletion-request (requires
read)Filing is idempotent — an already-open request is returned rather than duplicated
Erasure completes within 30 days of
requested_at; usage totals are retained de-identified for accountingUnchanged: v1 path, every existing request and response field
Release 2026-10-20 — Usage analytics
GET /analytics returns daily usage for your tenant: active students, conversations created, messages, tokens and our estimated cost. See the Analytics page for the contract.
No change is required to existing integrations. The endpoint needs an API key with the analytics permission.
Added: GET /analytics with optional
fromandto(YYYY-MM-DD), defaulting to the last 30 daysDays without activity are omitted rather than returned as zeroes
active_studentsin totals counts each student once across the range, not once per active dayFigures are recomputed hourly;
meta.last_refreshed_atreports when, so the current day can be treated as provisionalUnchanged: v1 path, every existing request and response field
Release 2026-10-19 — external_user_id is now required
Creating a chat without external_user_id now returns 400. It identifies the student the conversation belongs to, and it is the only link between a conversation and one of your users: chats created through the API have no account on our side. Without it a conversation cannot be attributed, reported on, or deleted on that student's behalf.
Both live integrations already send it on every call, so in practice this changes nothing — it closes a gap where the omission failed silently instead of loudly.
Changed:
external_user_idis required on POST /chats (previously optional)Error:
INVALID_REQUESTwith status 400 when it is missingUse an identifier that is stable for the student and meaningful only to you — we never need their name or email
Unchanged: v1 path, every other request and response field
Release 2026-10-09 — Image input
Students can now send an image with a question — a photo of a handwritten problem, a textbook page, a diagram — and the tutor reads it and responds about what it sees. No change is required to existing integrations.
Added: optional
attachmentsarray on POST /chats/{chatId}/messagesAdded: images are returned with message history, so past turns keep their context
Images are sent as base64 data URLs, not links — see the Chats page for the contract and the reasoning
Limits: up to 4 images per message, 10MB each, JPEG/PNG/GIF/WebP/HEIC/HEIF
Unchanged: v1 path, all existing request and response fields
Baseline — v1 general availability
v1 external endpoints available under /api/external/v1
Tenant subject assignment with compatibility fallback
Idempotency on chat and message POST flows
Redis-backed rate limiting when Redis env vars are configured
Planned Docs Expansions
OpenAPI-generated reference pages
Multi-language code examples
SDK guides and quickstarts