Practice quiz

A self-marking practice quiz with answers and explanations, from a topic, your text or a document.

Price1 credit (10p) per session
Typical time15 s to 2 min
Scopelearning:write
Runs asA background job

Try it

Run practice quiz 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.

TopicA subject to study from general knowledge, for example "Photosynthesis for GCSE Biology".

Source TextYour own teaching text (at least 200 characters, at most 10,000 words). Material stays grounded in it.

TitleA name for your text or document, such as the lesson or chapter title.

FocusConcepts to concentrate on, in plain words.

LevelHow to pitch the material. Leave it out for upper-secondary to first-year university level.

AudienceWho the material is for, for example "Year 10 learners who find maths hard".

LanguageThe language to write in. British English unless you choose another.

CountHow many quiz items to make (3 to 20).

Difficultymixed, easy (recall), medium (apply) or hard (reason across ideas).

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.

Mixes multiple choice, true or false, fill the blank and short answer items. Every item carries its answer: the expected answer, the correct option or accepted answers, and an explanation that names the misconception behind a wrong answer. Hide answer from learners until they respond. An item may include a figure brief; its text always states everything needed to answer without it. For practice only, never an official grade.

Requires learning:write. Costs 1 credit per session. 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.

Practice quiz

POST/v1/practice/quizzes

Scope learning:write

Headers

Practice quiz: 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

Practice quiz: request body
Field	Details
`topic`	string, optionalA subject to study from general knowledge, for example "Photosynthesis for GCSE Biology".Up to 200 characters
`source_text`	string, optionalYour own teaching text (at least 200 characters, at most 10,000 words). Material stays grounded in it.Up to 120,000 characters
`document`	FileReference or DocumentInput, optionalA PDF, DOCX or TXT to study from: `{"file_id"}` from POST /v1/files, or inline base64.
`file_id`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`document.filename	stringRequiredWhen sending DocumentInputUp to 200 characters
`base64`document.base64	stringRequiredWhen sending DocumentInputUp to 27,962,028 characters
`mime_type`document.mime_type	string, optionalWhen sending DocumentInputUp to 150 characters
`title`	string, optionalA name for your text or document, such as the lesson or chapter title.Up to 200 characters
`focus`	stringConcepts to concentrate on, in plain words.Up to 500 charactersDefault `""`
`level`	enum, optionalHow to pitch the material. Leave it out for upper-secondary to first-year university level.One of `new_to_this`, `foundation`, `intermediate`, `advanced`, `exam_revision`, `deep_dive`
`audience`	string, optionalWho the material is for, for example "Year 10 learners who find maths hard".Up to 200 characters
`language`	enumThe language to write in. British English unless you choose another.One of `English`, `Welsh`, `Irish`, `Gaelic`, `French`, `Spanish`, `German`, `Italian`, `Portuguese`, `Dutch`, `Polish`, `Arabic`, `Urdu`, `Hindi`, `Punjabi`, `Bengali`, `Chinese`, `Mandarin`, `Cantonese`, `Japanese`, `Korean`, `Russian`, `Turkish`, `Greek`, `Swedish`, `Norwegian`, `Danish`, `Finnish`, `Romanian`, `Hungarian`, `Czech`, `Ukrainian`, `Farsi`, `Persian`, `Hebrew`, `Swahili`, `Somali`, `Tamil`, `Gujarati`, `Vietnamese`, `Thai`, `Indonesian`, `Malay`, `Tagalog`, `Latin`Default `"English"`
`count`	integerHow many quiz items to make (3 to 20).3 to 20Default `8`
`difficulty`	enummixed, easy (recall), medium (apply) or hard (reason across ideas).One of `mixed`, `easy`, `medium`, `hard`Default `"mixed"`

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/practice/quizzes' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Photosynthesis for GCSE Biology",
  "count": 8,
  "difficulty": "mixed"
}'

# 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": "practice_quizzes",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 1,
  "result_available": false
}

Finished job: resultJSON

{
  "status": "completed",
  "title": "Photosynthesis for GCSE Biology",
  "difficulty": "mixed",
  "item_count": 4,
  "items": [
    {
      "id": "q1",
      "type": "multiple_choice",
      "prompt": "Which gas do plants take in for photosynthesis?",
      "concept": "Reactants",
      "difficulty": "easy",
      "options": [
        {
          "id": "a",
          "label": "Oxygen"
        },
        {
          "id": "b",
          "label": "Carbon dioxide"
        },
        {
          "id": "c",
          "label": "Nitrogen"
        }
      ],
      "answer": {
        "expected": "Carbon dioxide",
        "correct_option_id": "b",
        "explanation": "Plants take in carbon dioxide and release oxygen. Choosing oxygen mixes up photosynthesis with respiration."
      }
    },
    {
      "id": "q2",
      "type": "true_false",
      "prompt": "Photosynthesis happens in the mitochondria.",
      "concept": "Cell structure",
      "difficulty": "easy",
      "options": [
        {
          "id": "true",
          "label": "True"
        },
        {
          "id": "false",
          "label": "False"
        }
      ],
      "answer": {
        "expected": "False",
        "correct_option_id": "false",
        "explanation": "It happens in the chloroplasts. Mitochondria are where respiration releases energy."
      }
    },
    {
      "id": "q3",
      "type": "fill_blank",
      "prompt": "The green pigment that absorbs light is called ____.",
      "concept": "Chlorophyll",
      "difficulty": "medium",
      "options": [],
      "answer": {
        "expected": "chlorophyll",
        "accepted_answers": [
          "chlorophyll"
        ],
        "explanation": "Chlorophyll absorbs mainly red and blue light, which is why leaves look green."
      }
    },
    {
      "id": "q4",
      "type": "short_answer",
      "prompt": "Name one factor that limits the rate of photosynthesis.",
      "concept": "Limiting factors",
      "difficulty": "medium",
      "options": [],
      "answer": {
        "expected": "Light intensity",
        "accepted_answers": [
          "light intensity",
          "light",
          "carbon dioxide",
          "temperature"
        ],
        "explanation": "Light, carbon dioxide and temperature can each limit the rate when in short supply."
      }
    }
  ],
  "language": "English",
  "source": {
    "kind": "topic",
    "title": "Photosynthesis for GCSE Biology",
    "truncated": false
  },
  "warnings": [],
  "provenance": {
    "engine": "edumark_study",
    "sandbox": true
  }
}

Files and errors

Product errors

SOURCE_REQUIREDHTTP 422. Provide exactly one of topic, source_text or document.
SOURCE_TOO_SHORTHTTP 422. source_text needs at least 200 characters to study from.
INPUT_TOO_LARGEHTTP 422. source_text supports at most 10,000 words.
MODEL_RESULT_INVALIDOn the finished job. The generated material did not pass EduMark's checks. No charge was applied.
PROCESSING_UNAVAILABLEOn the finished job. Processing could not complete safely. No complete result was issued.
DOCUMENT_READ_FAILEDOn the finished job. The document could not be read safely.