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-keys drafts 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, or none for 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: 403 agent_not_allowed. GET /v1/answer-keys/{id} reads one and GET /v1/answer-keys lists them, newest first. A job whose file is still waiting for its pages waits for them.
  • Reading and marking with a key. POST /v1/transcriptions takes answerKeyId in place of questionIds, and its result gains answerKeyId, a blank flag on each answer and pages with each page's id and its file's id. POST /v1/markings takes { answerKeyId, transcriptionId }: a question with a rule is marked by that rule, the rest by the model, and each question's result gains answer and method (rule, model or blank). A key no person confirmed is refused with 409 answer_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 \circ or \frac{3}{4} becomes ° or 3/4. GET /v1/markings (new) lists markings, with answerKeyId to 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. Assignment and Programme gain source, the organisation that owns the programme: its organisationId, kind, displayName (its brand's display name, else its name) and logoUrl (null when none is stored). Show it beside that work only, as attribution.
  • List one source's assignments. GET /v1/assignments takes an optional source, 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. Relationship gains counterpartyDisplayName and counterpartyBrand (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-connections lists the teacher's connections (a school admin sees the school's) and POST /v1/mcp-connections/{id}/revoke ends one. Only a signed-in person may call them; any other credential gets 403 agent_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-summaries and GET /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 403 agent_not_allowed. An API key cannot call these three.

Document SHA-256: 2d8676dda6551e7b7a902bd49e9d6688236141ae1e504912f4f655fffb790778

  • Two consent calls now document that they refuse unknown fields. The request bodies of POST /v1/organisations/{id}/consents and POST /v1/organisations/{id}/consents/{consentId}/withdraw declare additionalProperties: 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-Remaining and RateLimit-Reset. Over the limit, the answer is 429 rate_limited with Retry-After in 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 and mmwk_live_ for any other, and a test key works only for a sandbox organisation. The ApiKey object gains kind, lastUsedAt and scopes. Creating a key may pass scopes, 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/organisations with a key lists only the key's organisation, and reading another organisation by id is not_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 the request-id response header) and docUrl (the code's entry on the error-code page). type, code, message and retryable are 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-Key header, and every operation lists the 429 and 500 answers beside the errors it already listed.