Submit for automated marking
Upload, start a background job and bring the result back to the learner.
Create a draft
Save session.id. To use a saved Builder paper, POST {paperId, revision} to /marking/sessions/from-builder instead. It attaches the matching scheme; you still upload the completed student scan.
curl "https://api.wingman.st/v1/marking/sessions" \
-H "Authorization: Bearer $WINGMAN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: practice-paper-2026-01" \
-d '{"title":"My Core Pure practice"}'Upload the source files
Repeat with kind=scheme for the mark scheme, unless the saved-paper workflow supplied it. Send raw file bytes with the matching Content-Type, not multipart or base64. Upload responses include the asset ID and inspected page count.
File uploads are not idempotent. If an upload response is lost, inspect the session’s asset list before uploading again. Draft creation, marking starts and question requests require an Idempotency-Key.
curl "https://api.wingman.st/v1/marking/sessions/$SESSION_ID/assets?kind=work&name=work.pdf" \
-H "Authorization: Bearer $WINGMAN_API_KEY" \
-H "Content-Type: application/pdf" \
--data-binary @work.pdfPrepare and confirm marking
POST to /marking/sessions/{id}/start with a fresh Idempotency-Key for this operation. A 202 response accepts background preparation. Poll GET /marking/sessions/{id} about every five seconds, with backoff on errors. With credit billing enabled, prepared questions remain drafts until you confirm a quote.
POST {} to /marking/sessions/{id}/quote, or select prepared questionIds, then review the verified available marks and totalCredits. GET on the same quote endpoint reads recovery state without creating a new quote. Confirm only the exact reviewed quote within the user's explicit budget through /marking/sessions/{id}/quote/{quoteId}/confirm with a stable Idempotency-Key. Resume the same confirmation after an uncertain response; do not generate and confirm a replacement automatically. Even zero-credit quotes require confirmation.
To select pages explicitly, POST /marking/sessions/{id}/questions with label, workAssetIds, schemeAssetIds and pageSelections. Page selections use uploaded asset UUIDs as keys and one-based page numbers as values.
Report the actual outcome
Read every question’s status and result. completed, needs_review, failed and cancelled are terminal question states. Wait for indexing to finish before assuming the question list is complete.
Use effectiveResult, when present, for the current score and review flags after manual edits. The original result, review overrides and annotation review remain separately available; raw status may retain the original assessment state.
Keep needs_review results provisional. Present the score range and unresolved criteria. If some questions failed, say so; do not report the remaining score as a complete-paper result. The marked paper is also available in the owner’s Wingman Marking area.