Workbook marking

Proposed marks and feedback for a completed spreadsheet: cells, formulas, charts and layout.

Price10 credits (£1.00) per submission
Typical time20 s to 4 min
Scopemarking:write
Runs asA background job

Try it

Run workbook marking 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 an XLSX or CSV workbook and the questions it answers. EduMark reads every filled cell with its saved value and formula, redraws charts from the data saved in the file and renders the original layout. Point a question at its answer cells with cells (for example Budget!B14:M14) and the formulas' source cells are read too; otherwise EduMark finds the answer. Formulas and macros are never run. The result is a proposal for a named person to review: official_result is always false and requires_review always true.

Requires marking:write. Costs 10 credits per submission. 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.

Workbook marking

POST/v1/marking/workbooks

Scope marking:write

Headers

Workbook marking: 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

Workbook marking: request body
Field	Details
`workbook`	FileReference or WorkbookInlineRequiredThe completed workbook: an uploaded XLSX or CSV file id, or inline base64.
`file_id`workbook.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`workbook.filename	stringRequiredWhen sending WorkbookInlineUp to 200 characters
`base64`workbook.base64	stringRequiredWhen sending WorkbookInlineUp to 27,962,028 characters
`mime_type`workbook.mime_type	string, optionalWhen sending WorkbookInlineUp to 150 characters
`questions`	array of WorkbookQuestionRequired1 to 30 items
`id`questions[].id	stringRequiredUp to 100 charactersPattern `^[A-Za-z0-9_.-]+$`
`question_text`questions[].question_text	stringRequiredUp to 12,000 characters
`max_marks`questions[].max_marks	integerRequired1 to 1,000
`marking_guide`questions[].marking_guide	string, optionalWhat a good answer contains and how marks are awarded. Draft one with POST /v1/marking/guides.Up to 16,000 characters
`criteria`questions[].criteria	array of CriterionOptional rubric. Criterion maxima must add up to max_marks.Up to 12 items
`id`questions[].criteria[].id	stringRequiredUp to 60 charactersPattern `^[A-Za-z0-9_.-]+$`
`title`questions[].criteria[].title	stringRequiredUp to 300 characters
`description`questions[].criteria[].description	string, optionalUp to 4,000 characters
`max_marks`questions[].criteria[].max_marks	integerRequired1 to 1,000
`cells`questions[].cells	array of stringWhere the answer is, for example `Budget!B2:B12`. Leave empty to let EduMark find it.Up to 20 items
`context_text`	string, optionalAssignment-wide marking rules or the task brief.Up to 60,000 characters
`feedback`	FeedbackPreferences, optionalHow feedback is written. Each field is optional; unset fields use your team's Assessment & feedback settings.
`tone`feedback.tone	enum, optionalprofessional_balanced, supportive_developmental, direct_concise or custom.One of `professional_balanced`, `supportive_developmental`, `direct_concise`, `custom`
`custom_tone`feedback.custom_tone	string, optionalDescribes the tone when tone is custom.Up to 500 characters
`length`feedback.length	enum, optionalbrief, standard or detailed.One of `brief`, `standard`, `detailed`
`address`feedback.address	enum, optionaldirect ('you') or third_person ('the learner').One of `direct`, `third_person`
`instructions`feedback.instructions	string, optionalExtra writing instructions. They shape wording only, never marks.Up to 2,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/marking/workbooks' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "workbook": {
    "file_id": "file_3f2a9c0b5d7e4a1b8c6d2e0f9a8b7c6d"
  },
  "questions": [
    {
      "id": "q1",
      "question_text": "Total each month'\''s spending and chart the trend across the year.",
      "max_marks": 6,
      "marking_guide": "3 marks for correct monthly totals using formulas; 3 marks for a titled, labelled line chart of the totals.",
      "cells": [
        "Budget!B14:M14"
      ]
    }
  ]
}'

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

Finished job: resultJSON

{
  "status": "needs_review",
  "reason": null,
  "official_result": false,
  "requires_review": true,
  "questions": [
    {
      "question_id": "q1",
      "label": "q1",
      "status": "needs_review",
      "proposed_marks": 5,
      "max_marks": 6,
      "feedback": "Your monthly totals use SUM correctly and the chart shows the trend clearly. Label the y axis with its units so the chart can be read on its own.",
      "rationale": "Totals are correct formulas over the right ranges; the chart is present but its value axis has no title.",
      "criteria": [
        {
          "ref": "overall",
          "band": "secure",
          "marks": 5
        }
      ],
      "evidence": [
        {
          "kind": "quote",
          "quote": "=SUM(B2:B13)",
          "location": {
            "cell": "Budget!B14"
          }
        },
        {
          "kind": "visual",
          "label": "Submitted evidence 1.xlsx",
          "criterion_ref": "overall",
          "observation": "A line chart of monthly spending with a title but no y-axis label."
        }
      ],
      "confidence": 0.84,
      "reason": null,
      "inferred_fields": [],
      "attention": [],
      "comments": []
    }
  ],
  "totals": {
    "proposed_marks": 5,
    "max_marks": 6,
    "complete": true
  },
  "workbook": {
    "sheets": [
      {
        "name": "Budget",
        "hidden": false,
        "rows": 14,
        "columns": 3,
        "cells": 41,
        "formulas": 13,
        "charts": 1,
        "pictures": 0
      }
    ],
    "truncated": false
  },
  "warnings": [],
  "feedback_style": {
    "tone": "professional_balanced",
    "length": "standard",
    "address": "direct",
    "instructions_applied": false,
    "source": "defaults"
  },
  "provenance": {
    "engine": "shared_workbook_marking",
    "sandbox": true
  }
}