API & agents

Import marked work

Keep the full marking experience: source scans, precise evidence, allocations and reviewable feedback.

The import workflow

POST {title} to /marking/imports with an Idempotency-Key. Save the returned session ID.
POST raw work and scheme files to /marking/imports/{id}/assets?kind=work|scheme&name=…. Keep the returned asset IDs and page counts.
Build a wingman-marking-import-v1 submission using the original page images and supplied scheme. Use the complete schema in OpenAPI and the downloadable example.
POST the submission to /marking/imports/{id}/validate. Correct any 422 field errors; inspect returned scores and review flags.
POST the same submission to /marking/imports/{id}/complete with an Idempotency-Key. Wingman revalidates and saves all questions atomically to the normal marking area.

Import-only access does not enqueue automated marking or PDF-detection jobs. Creating and uploading a draft is separate from saving the final results.

Locate evidence on the original page

Set coordinateSystem to normalized-top-left and pageBasis to displayed-page. Use the page as the Wingman viewer displays it, after the PDF’s page rotation or the image’s display orientation. Do not crop or resize the coordinate reference to just an answer.

A page ID is <uploaded asset UUID>:p<one-based page number>, for example 11111111-1111-4111-8111-111111111111:p1. Declare each referenced page in pageSelections. Work evidence must point to selected work pages; every rubric allocation must cite a selected scheme page.

json

{
  "pageId": "11111111-1111-4111-8111-111111111111:p1",
  "quote": "The student writes the correct factorisation.",
  "box": { "x": 0.12, "y": 0.34, "width": 0.56, "height": 0.08 }
}

Field	Meaning
x, y	Left and top position, divided by the displayed page width and height.
width, height	Positive rectangle dimensions, divided by page width and height.
Bounds	x ≥ 0, y ≥ 0, x + width ≤ 1, y + height ≤ 1.
quote	A faithful transcription or brief description of what is visible in this region.

For a 1000 × 1400 displayed page, a rectangle at (120, 476) with size 560 × 112 becomes x=0.12, y=0.34, width=0.56, height=0.08. Use real evidence, not invented rectangles. Blank work can be located to its actual answer space and described as blank.

Describe each mark

Split the rubric into parts and individual one-mark criteria. Each part’s maximum must equal its criteria count. Each criterion needs an ID, partId, code, requirement, conditions, conditionMode, dependsOn, maxMarks: 1 and sourcePageIds.

Use M1 for a method mark, A1 for accuracy and B1 for an independent mark. Canonical modifiers are a d prefix and ft or * suffixes where the scheme uses them. Store the allocation code with 1 even when withholding it; the decision carries the zero. A d code must specify its dependencies. Do not infer every dependency from the code: record the actual scheme’s prerequisites.

Submit exactly one grade decision for every criterion: awarded, withheld or uncertain. Include its reason, located evidence and a check for every rubric condition. Condition indexes are zero-based; check decisions are met, not_met or uncertain.

What Wingman validates

The schema rejects unknown fields. Keep schemaVersion, coordinateSystem and pageBasis exactly as specified. An import supports up to 24 questions, 100 marks per question and a 4 MiB JSON body.

All uploaded files and referenced pages belong to this import and have the correct work or scheme role.
Every criterion has a decision, every condition is checked, and every decision has a positive-area evidence box. Supplied condition evidence also needs boxes.
Parts, one-mark allocations and declared whole-paper coverage agree; question labels and criterion IDs are unique in their respective scopes.
Dependencies point to existing criteria and form no cycles. Wingman applies them when calculating totals.
No submitted total or completion flag can override the result. Conflicting conditions, unresolved issues and uncertainty remain visible for review.

Preserve the source and retry safely

Identify source.kind as human or ai, source.name and source.markedAt as an ISO timestamp. AI imports must also name source.model. Imported marking is attributed to that source, and is not labelled as Wingman’s automated judgement.

A completed import is immutable. Repeating the identical payload is safe; changing it returns 409. To correct individual decisions afterwards, use Wingman’s review interface or a key with marking:review. To replace the original submission, create a new import.

Wingman for AI assistants