Create an assessment

Uploads a paper and turns it into a markable assessment. Use this when the paper originates in your system: you own it, only your token can see it, and student hand-ins are marked against it once it is published.

Returns 202 Accepted and starts extraction in the background. Watch for the assessment.review_ready webhook, or poll the show endpoint.

Parameters

Name	Type	Required	Description
name	string	required	Human-readable paper name
subject_id	uuid	required	Must be available on your subscription
source_document	file or URL	required	The question paper (PDF)
solutions_document	file or URL	optional	The marking scheme (PDF). Extraction reads the answers, marks and criteria from it
assessment_type	string	optional	homework (default) or exam
external_reference	string	optional	Your own identifier for the paper
code	string	optional	Your own code. Must be globally unique; omit it and we generate one
topic_ids	array	optional	Topic ids belonging to the subject

Idempotency

Send an external_reference and a repeat of the same call returns the assessment you already created, with 200, instead of a second copy. This makes a timed-out request safe to retry.

Codes

code is unique across every assessment, so namespace yours (for example acme:2026:PMX:w27). A code already in use returns 409 with MARK_ERRORS::CODE_TAKEN. Omit code and we return a generated one for you to store.

Lifecycle

draft → extracting → review → published. A paper can only be marked against once it is published; hand-ins sent before then have no answer key and would fall through to ad-hoc marking. Publishing requires a person to confirm every question — see Review an assessment.