API quickstart

TL;DR: With a sandbox API key, three requests show the whole shape of the API: create a job, see what a key is refused, and read the job by its id.

Before you start

  • A sandbox key. MMW staff make your sandbox organisation and invite your admin. The admin signs in and makes a key with POST /v1/api-keys. The answer shows the key once; only its hash is stored, so keep it somewhere safe. A sandbox runs on the stand-in engine, unless MMW points it at a real model for a trial, and can hold no real student work.
  • Two variables. MMW_API_URL is the API's address, and MMW_API_KEY is your key.
  • Every request sends the key as Authorization: Bearer <key>. The key says which organisation is calling, so no request names one.
  • Every create sends an Idempotency-Key header of your choosing. Send the same request again with the same header and nothing is made twice.
  • Every refusal has the same body, { "error": { type, code, message, param, requestId, docUrl, retryable } }. The codes and fields are in API error codes.
  • The whole contract is the OpenAPI document at GET /v1/openapi.json, which needs no credential.

1. Create a marking

Mark answers against a mark scheme. The answer is a job. A sandbox runs on the stand-in engine, so the job has succeeded already, names model fake and costs nothing; with a real model it answers queued and you read it again until it is done. Every marking is unreviewed: the API never moves it further.

POST /v1/markings

curl -sS -X POST "$MMW_API_URL/v1/markings" \
  -H "Authorization: Bearer $MMW_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"answers":[{"questionId":"1a","text":"Sleep deprivation."},{"questionId":"1b","text":"Caffeine use was not controlled."}],"externalId":"script-17","markScheme":{"questions":[{"criteria":"Names the independent variable.","id":"1a","maxMarks":1},{"criteria":"Explains one confound.","id":"1b","maxMarks":3}]}}'

The answer is 200 and holds at least:

{
  "engine": {
    "model": "fake"
  },
  "kind": "marking",
  "object": "job",
  "result": {
    "reviewState": "unreviewed",
    "usage": {
      "costUsd": 0
    }
  },
  "status": "succeeded"
}

2. See that a key cannot approve

A key never approves or releases a mark. Only a signed-in teacher or school admin does, in the app, so this is refused for any submission and whatever a school has granted you.

POST /v1/submissions/{id}/approvals

curl -sS -X POST "$MMW_API_URL/v1/submissions/sub_any/approvals" \
  -H "Authorization: Bearer $MMW_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"inputHash":"any","judgementIds":["jdg_any"]}'

The answer is 403 and holds at least:

{
  "error": {
    "code": "agent_not_allowed",
    "retryable": false,
    "type": "permission_error"
  }
}

3. Read the marking

Read the marking by its id. This is how you learn a job has finished: the API calls no address of yours. Another organisation's key gets 404 not_found for the same id.

GET /v1/markings/{id}

curl -sS -X GET "$MMW_API_URL/v1/markings/<id from step 1>" \
  -H "Authorization: Bearer $MMW_API_KEY"

The answer is 200 and holds at least:

{
  "kind": "marking",
  "result": {
    "reviewState": "unreviewed"
  },
  "status": "succeeded"
}