Document reading

Read photos, scans and handwriting into text: verbatim transcripts, a learner's working, or teaching notes.

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

Try it

Run document reading 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 up to 20 images (PNG, JPEG or WebP) and/or a PDF document with the pages to read. read_as picks the reading: transcript (every word, mark, tick and table exactly as written, [illegible] where unsure), working (a learner's handwritten working and final answer, never solved or corrected) or notes (teaching material as headed sections, diagrams described). Every page is read as an image, so handwriting on typed pages is kept. A finished job also has reading.txt. Readings are evidence to check against the original, never marks.

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

Document reading

POST/v1/documents/read

Scope learning:write

Headers

Document reading: 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

Document reading: request body
Field	Details
`images`	array of FileReference or InlineFilePhotos or scans to read (PNG, JPEG or WebP), in order.Up to 20 items
`file_id`images[].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`images[].filename	stringRequiredWhen sending InlineFileUp to 200 characters
`base64`images[].base64	stringRequiredWhen sending InlineFileUp to 27,962,028 characters
`mime_type`images[].mime_type	string, optionalWhen sending InlineFileUp to 150 characters
`document`	FileReference or InlineFile, optionalA PDF to read pages from. Say which with pages.
`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 InlineFileUp to 200 characters
`base64`document.base64	stringRequiredWhen sending InlineFileUp to 27,962,028 characters
`mime_type`document.mime_type	string, optionalWhen sending InlineFileUp to 150 characters
`pages`	array of integer, optionalThe PDF pages to read, numbered from 1, for example [1, 2, 3]. You pay per page you list.1 to 20 items
`read_as`	enumtranscript: every word, mark and table exactly as written, handwriting included. working: a learner's handwritten working step by step and their final answer. notes: teaching material as headed sections, with diagrams described.One of `transcript`, `working`, `notes`Default `"transcript"`
`question`	string, optionalFor working: the question the working answers, so the reading is in context.Up to 4,000 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/documents/read' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "images": [
    {
      "filename": "answer-photo.png",
      "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAGklEQVR42mP8//8/AymAiYFEMKphVMPQ0QAAVW0DHfeH1GIAAAAASUVORK5CYII=",
      "mime_type": "image/png"
    }
  ],
  "read_as": "transcript"
}'

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

Finished job: resultJSON

{
  "status": "completed",
  "read_as": "transcript",
  "requires_review": true,
  "page_count": 1,
  "read_count": 1,
  "summary": "1 of 1 page was read. Check what was read against the original.",
  "pages": [
    {
      "label": "Image 1",
      "status": "read",
      "handwritten": true,
      "legible": true,
      "text": "Q1. Photosynthesis makes glucose and oxygen ✓ 2/2\nQ2. It happens in the [illegible] of the cell",
      "index": 1
    }
  ],
  "warnings": [],
  "provenance": {
    "engine": "edumark_document_reading",
    "sandbox": true
  }
}

Files and errors

Files on the finished job

reading.txtEverything read, page by page.

Download with GET /v1/jobs/{id}/files/{name}.

Product errors

PAGES_REQUIREDHTTP 422. Say which PDF pages to read with pages, for example [1, 2, 3].
TOO_MANY_PAGESHTTP 422. Read up to 20 pages and images per request.
PAGE_OUT_OF_RANGEOn the finished job. A listed page does not exist in the PDF. No charge was applied.
IMAGE_UNREADABLEOn the finished job. An image could not be decoded.
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.