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_URLis the API's address, andMMW_API_KEYis 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-Keyheader 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"
}