API & agents

Import marked work

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

The import workflow

POST {title} to /marking/imports with an Idempotency-Key for standalone scans. For an owned saved Builder paper, send {savedPaper:{paperId,revision}} and additionally use papers:read. Save the returned session ID and sourceBinding map.
POST raw work and scheme files to /marking/imports/{id}/assets?kind=work|scheme&name=…. A saved-paper import supplies its frozen scheme and title: upload only completed work. Keep the asset IDs and page counts.
Build a wingman-marking-import-v2 submission with decisionBasis: local using the actual page images and matching scheme. Use the complete schema in OpenAPI. The downloadable V1 example remains a structural reference; V2 requires the new version and decisionBasis field.
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 <asset UUID>:p<one-based page number>, for example 11111111-1111-4111-8111-111111111111:p1. pageSelections contains only pages of this question's work and scheme assets. Work evidence must point to selected work pages; every rubric allocation must cite a selected scheme page. For a saved-paper import, use sourceBinding.questionPageIds directly as clean rubric context; these frozen reference pages are not uploaded work/scheme assets and must not be added to pageSelections.

Use an approximate useful region around the actual line group, paragraph, table or diagram. Each observation belongs to one cited page; split continuations across pages. For V2, a genuine observation with known page but unavailable useful bounds uses box: null, and geometry alone does not turn a settled mathematical mark into review. A region over 60% of a page is projected as page-only evidence; the original submitted payload is preserved.

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, genuine selected-work evidence and a check for every rubric condition. Condition indexes are zero-based; check decisions are met, not_met or uncertain. A saved-paper import must cover every frozen sourceBinding label and maximum, use its clean questionPageIds, and cite its unchanged schemeAssetId and exact schemePages.

What Wingman validates

The schema rejects unknown fields. Keep schemaVersion, coordinateSystem and pageBasis exactly as specified; V2 also requires decisionBasis: local. Saved-paper imports require V2 and all frozen occurrences with their trusted maxima and scheme. Standalone V1 remains supported with its original requirements. 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 and every condition is checked. V2 preserves genuine page-only evidence without changing mathematical decisions. V1 retains positive-area boxes for every decision and supplied condition-evidence item.
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.

Validation and completion summaries describe the submitted assessment. After later manual edits, read question.effectiveResult in the session for the current user-facing score. The original result, external provenance and review history remain intact, including after identical completion replay. Imported marking uses the normal evidence viewer, annotations and PDF export.

Evaluated local results include optional decisionBasis: local so automatic dependency blocking remains settled when a review is reset. The source's mathematical judgement remains externally attributed, rather than independently certified by Wingman.

Completion's optional profile receipt reports evidenceRecorded, mappingPending, sessionId, watermark and a session-filtered changes link. Marking is saved before profile refresh: evidenceRecorded=false or mappingPending=null means the durable feed needs recovery, while a positive count means skill classification is still running. With progress:read, inspect /skill-profile/changes for exact evidence changes and event detail for reconstructed Pathway impact. A later authorised profile/change read or identical completion replay recovers pending projection.

Wingman for AI assistants