Assignment drafts

An assignment brief turned into a reviewable EduMark assignment: tasks, marks and marking criteria.

Price5 credits (50p) per draft
Typical time20 s to 3 min
Scopeauthoring:write
Runs asA background job

Try it

Run assignment 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 the brief as a document or as brief_text. EduMark reads it the way the Assignment Studio's "Create with AI" does: tasks and questions, marks, marking criteria and where each came from in the brief. Missing information stays missing and is flagged for review; nothing is invented. The result has a short summary and the full assessment. Set save_to_lms to also create an unpublished draft in the Assignment Studio (the key needs assignments:write), ready for staff to check and publish.

Requires authoring:write. Costs 5 credits per draft. 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.

Assignment drafts

POST/v1/authoring/assignments

Scope authoring:write

Headers

Assignment 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

Assignment drafts: request body
Field	Details
`document`	FileReference or DocumentInput, optionalThe assignment brief as a PDF, DOCX or TXT: `{"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
`brief_text`	string, optionalThe assignment brief as text (at most 10,000 words): the tasks or questions, marks and any marking criteria.Up to 120,000 characters
`context_text`	string, optionalExtra guidance, such as the qualification's grading criteria. Used as context, never as wording to copy.Up to 60,000 characters
`title`	string, optionalThe assignment title. Taken from the brief when left out.Up to 200 characters
`save_to_lms`	booleanAlso create an unpublished assignment draft in the Assignment Studio (needs the assignments:write permission) and return its id.Default `false`

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/authoring/assignments' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "brief_text": "Unit 3: Cell biology report. Task 1 (P1): Describe the structure of a eukaryotic cell. Task 2 (M1): Explain the role of mitochondria in aerobic respiration."
}'

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

Finished job: resultJSON

{
  "status": "needs_review",
  "requires_review": true,
  "assignment": {
    "title": "Unit 3: Cell biology report",
    "instructions": "Write a report on cell structure and respiration. Answer every task.",
    "submission_instructions": "Submit one PDF or Word document.",
    "qualification": "BTEC Level 3 Applied Science",
    "unit": "Unit 3",
    "level": "3",
    "question_count": 2,
    "criteria_count": 2,
    "questions_needing_review": 0,
    "assessment": {
      "metadata": {
        "assessment_title": "Unit 3: Cell biology report",
        "qualification": "BTEC Level 3 Applied Science",
        "unit": "Unit 3",
        "level": "3",
        "assessment_instructions": "Write a report on cell structure and respiration. Answer every task.",
        "submission_instructions": "Submit one PDF or Word document."
      },
      "criteria": [
        {
          "id": "P1",
          "description": "Describe the structure of a eukaryotic cell."
        },
        {
          "id": "M1",
          "description": "Explain how mitochondria release energy in aerobic respiration."
        }
      ],
      "questions": [
        {
          "id": "q1",
          "label": "Task 1",
          "question_type": "long_text",
          "prompt": "Describe the structure of a eukaryotic cell, naming at least five organelles.",
          "criteria_ids": [
            "P1"
          ],
          "requires_human_review": false
        },
        {
          "id": "q2",
          "label": "Task 2",
          "question_type": "long_text",
          "prompt": "Explain the role of mitochondria in aerobic respiration.",
          "criteria_ids": [
            "M1"
          ],
          "requires_human_review": false
        }
      ]
    }
  },
  "lms_draft": null,
  "warnings": [],
  "notice": "This is an AI draft for a person to review. Nothing was published and learners cannot see it.",
  "provenance": {
    "engine": "edumark_assignment_studio",
    "page_count": 2,
    "sandbox": true
  }
}