Changelog
TL;DR: Every change to the public contract, newest first. Each entry records the SHA-256 of the OpenAPI document it describes, as committed in pretty-printed form, so no version of the contract goes out without an entry. The versioning policy says what may change.
20 November 2026, answer keys
Document SHA-256: 68e7534e3bf93d17de022ba48f8599185d6412fac8d4cf41005e6e039b2dc38a
- Answer keys (new).
POST /v1/answer-keysdrafts a key from two uploaded files, the blank worksheet and its solutions: each question with its right answer, its marks and how it is checked (exact,numeric,choice,expression,model, ornonefor an answer not on paper). A drafted key is never confirmed. A person edits it and confirms it with the same call (basedOnId,questions,confirmed: true), which makes a new key and keeps the old one. An API key may save an edit but may not confirm one: 403agent_not_allowed.GET /v1/answer-keys/{id}reads one andGET /v1/answer-keyslists them, newest first. A job whose file is still waiting for its pages waits for them. - Reading and marking with a key.
POST /v1/transcriptionstakesanswerKeyIdin place ofquestionIds, and its result gainsanswerKeyId, ablankflag on each answer andpageswith each page's id and its file's id.POST /v1/markingstakes{ answerKeyId, transcriptionId }: a question with a rule is marked by that rule, the rest by the model, and each question's result gainsanswerandmethod(rule,modelorblank). A key no person confirmed is refused with 409answer_key_not_confirmed(new). A transcription read with another key is refused with 422: read the pages again with the key you mark with. The read text is plain: LaTeX such as\circor\frac{3}{4}becomes°or3/4.GET /v1/markings(new) lists markings, withanswerKeyIdto show one key's only. A mark-scheme question sent inline may also carry a rule check.
20 November 2026, assignment sources
Document SHA-256: c55225743f1cd40059d38724e810ad89d7a1491cca63d67eaaf49876a1def38f
- Every assignment and programme names its source.
AssignmentandProgrammegainsource, the organisation that owns the programme: itsorganisationId,kind,displayName(its brand's display name, else its name) andlogoUrl(null when none is stored). Show it beside that work only, as attribution. - List one source's assignments.
GET /v1/assignmentstakes an optionalsource, an organisation id, and returns only the assignments of that organisation's programmes. It only narrows what you may already read: an organisation you have no work from gives an empty page. - A relationship names its counterparty.
RelationshipgainscounterpartyDisplayNameandcounterpartyBrand(display name, logo URL and primary colour, as the counterparty set them). Who may read relationships is unchanged.
19 November 2026, a teacher's assistant
Document SHA-256: 9b7831e40b26af908dae6c0a7bf91da1142fc3c02ba465acf1f7c79b022527cf
- A teacher can connect Claude or ChatGPT. The assistant signs in through Mark My Words with OAuth, and the teacher allows it while signed in.
POST /v1/mcp-connections(new) is that step,GET /v1/mcp-connectionslists the teacher's connections (a school admin sees the school's) andPOST /v1/mcp-connections/{id}/revokeends one. Only a signed-in person may call them; any other credential gets 403agent_not_allowed. - What a connected assistant may call.
POST /v1/upload-links(new) starts a class set and answers a link to it, which takes files from the teacher's own browser for 15 minutes.GET /v1/batch-summariesandGET /v1/batch-summaries/{id}(new) answer a class set's status and its counts of files, pages, bundles and items waiting. Every other call with an assistant's token gets 403agent_not_allowed. An API key cannot call these three.
19 November 2026, strict consent bodies
Document SHA-256: 2d8676dda6551e7b7a902bd49e9d6688236141ae1e504912f4f655fffb790778
- Two consent calls now document that they refuse unknown fields. The request bodies of
POST /v1/organisations/{id}/consentsandPOST /v1/organisations/{id}/consents/{consentId}/withdrawdeclareadditionalProperties: false, as every other body already did. The API refused unknown fields in these two calls before this change too, so no caller sees a different answer.
18 November 2026, rate limits and keys
Document SHA-256: 4b37692c77ec5f98ff3569380c44c542f9653b6f69f4e1e9a4dd6d3c68b3ca96
- Calls with an API key are rate limited. Every answer to a key carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. Over the limit, the answer is 429rate_limitedwithRetry-Afterin seconds. Limits count per key and per organisation each minute: 25 and 50 for a sandbox organisation, 100 and 300 for any other, unless MMW staff set your own (POST /v1/organisations/{id}/rate-limit, new). See Rate limits. - Keys say their kind, last use and scopes. A new key starts
mmwk_test_for a sandbox organisation andmmwk_live_for any other, and a test key works only for a sandbox organisation. TheApiKeyobject gainskind,lastUsedAtandscopes. Creating a key may passscopes, a list of the actions it may take; an action a key can never take is refused with 422. - A key reads only its own organisation.
GET /v1/organisationswith a key lists only the key's organisation, and reading another organisation by id isnot_found, even one that has granted the key's organisation access.
18 November 2026
Document SHA-256: e6caa240af2a5a20d2021922912419cbc24cb5a88a4bf0a7b2a7296fb3497f7f
- Errors point at the cause. Every error body gains
param(the dotted path of the first field that was wrong, or null),requestId(the same as therequest-idresponse header) anddocUrl(the code's entry on the error-code page).type,code,messageandretryableare unchanged. - The document is ready for a code generator. Every response a procedure returns is a named component, every operation is tagged with its resource and has an example request and answer, the bearer credential is declared once, every call with a body declares the
Idempotency-Keyheader, and every operation lists the 429 and 500 answers beside the errors it already listed.