Marking guide drafts

Draft the question type, maximum marks and marking guide for questions that are missing them.

Price1 credit (10p) per request
Typical time5 s to 60 s
Scopemarking:write
Runs asA background job

Try it

Run marking guide drafts in the sandbox

No key and nothing to pay. The sandbox returns a realistic example in a couple of seconds; no AI runs and no data is kept.

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Send questions without answers. Any of question_type, max_marks or marking_guide you leave out is drafted; what you supply is kept exactly. drafted_fields lists what was drafted. Drafts are suggestions for a person to check before marking with them: requires_review is always true.

Requires marking:write. Costs 1 credit per request. Send a unique Idempotency-Key; reuse it with the identical body when retrying. Returns 202 with a job: poll GET /jobs/{job_id}, stream GET /jobs/{job_id}/events, or use a signed webhook.

Marking guide drafts

POST/v1/marking/guides

Scope marking:write

Headers

Marking guide drafts: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new operation; reuse it with the identical body when retrying.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Marking guide drafts: request body
Field	Details
`questions`	array of GuideQuestionRequiredLeave out any of question_type, max_marks or marking_guide to have it drafted.1 to 50 items
`id`questions[].id	stringRequiredUp to 100 charactersPattern `^[A-Za-z0-9_.-]+$`
`question_text`questions[].question_text	stringRequiredUp to 12,000 characters
`question_type`questions[].question_type	enum, optionalOne of `short_text`, `long_text`, `single_choice`, `numeric`
`max_marks`questions[].max_marks	integer, optional1 to 1,000
`marking_guide`questions[].marking_guide	string, optionalLeave empty to have one drafted. A supplied guide is kept exactly.Up to 16,000 characters
`options`questions[].options	array of QuestionOptionUp to 12 items
`id`questions[].options[].id	stringRequiredUp to 40 characters
`label`questions[].options[].label	stringRequiredUp to 2,000 characters
`context_text`	string, optionalThe brief, specification or level the questions belong to.Up to 60,000 characters
`context_document`	FileReference or DocumentInput, optionalThe brief or specification as a PDF, DOCX or TXT.
`file_id`context_document.file_id	stringRequiredThe id returned by POST /v1/files, after POST /v1/files/{id}/complete reported ready.When sending FileReferencePattern `^file_[a-f0-9]{32}$`
`filename`context_document.filename	stringRequiredWhen sending DocumentInputUp to 200 characters
`base64`context_document.base64	stringRequiredWhen sending DocumentInputUp to 27,962,028 characters
`mime_type`context_document.mime_type	string, optionalWhen sending DocumentInputUp to 150 characters

Responses

Status	Meaning
202	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
402	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/marking/guides' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "questions": [
    {
      "id": "q1",
      "question_text": "Explain why plants need light."
    }
  ],
  "context_text": "GCSE Biology, photosynthesis."
}'

# Then poll until the job finishes (wait poll_after_seconds between calls)
curl 'https://api.edumark.ai/v1/jobs/job_01JB7Q8M4X2V9R' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Response 202JSON

{
  "id": "job_0123456789abcdef0123456789abcdef01234567",
  "product": "marking_guides",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 1,
  "result_available": false
}

Finished job: resultJSON

{
  "status": "needs_review",
  "requires_review": true,
  "official_result": false,
  "questions": [
    {
      "id": "q1",
      "question_text": "Explain why plants need light.",
      "question_type": "short_text",
      "max_marks": 3,
      "marking_guide": "1 mark for stating that light provides the energy for photosynthesis. 1 mark for naming glucose (or sugar) as the product made. 1 mark for linking glucose to growth or respiration. Do not credit \"plants eat light\".",
      "options": [],
      "drafted_fields": [
        "question_type",
        "max_marks",
        "marking_guide"
      ]
    }
  ],
  "warnings": [],
  "provenance": {
    "engine": "shared_marking_inference",
    "sandbox": true
  }
}