Fill the gaps

Fill-the-gaps notes: short passages with the key terms removed, plus answers, hints, reasons and a word bank.

Price1 credit (10p) per set
Typical time10 s to 60 s
Scopelearning:write
Runs asA background job

Try it

Run fill the gaps 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.

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.

Each passage is a list of segments in reading order: plain text, or a gap with a hint, the answer, other accepted_answers and why (show it after the learner checks). Joined together the segments read as natural prose. word_bank lists every answer, shuffled, for an easier mode.

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

Fill the gaps

POST/v1/fill-the-gaps

Scope learning:write

Headers

Fill the gaps: 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

Fill the gaps: 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"`

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/fill-the-gaps' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Photosynthesis for GCSE Biology"
}'

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

Finished job: resultJSON

{
  "status": "completed",
  "title": "Photosynthesis for GCSE Biology",
  "gap_count": 3,
  "passages": [
    {
      "heading": "How plants make food",
      "segments": [
        {
          "text": "Photosynthesis takes place in the "
        },
        {
          "gap_id": "gap_1",
          "hint": "a green organelle",
          "answer": "chloroplasts",
          "accepted_answers": [
            "chloroplasts",
            "chloroplast"
          ],
          "why": "Chloroplasts hold the chlorophyll."
        },
        {
          "text": " of plant cells. The green pigment "
        },
        {
          "gap_id": "gap_2",
          "hint": "it absorbs light",
          "answer": "chlorophyll",
          "accepted_answers": [
            "chlorophyll"
          ],
          "why": "Chlorophyll absorbs red and blue light."
        },
        {
          "text": " absorbs light energy, which turns carbon dioxide and water into "
        },
        {
          "gap_id": "gap_3",
          "hint": "a sugar",
          "answer": "glucose",
          "accepted_answers": [
            "glucose"
          ],
          "why": "Glucose stores the energy as chemical energy."
        },
        {
          "text": "."
        }
      ]
    }
  ],
  "word_bank": [
    "glucose",
    "chloroplasts",
    "chlorophyll"
  ],
  "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.