API reference
Published questions. Your papers. Your marked work. Every operation uses a scoped bearer key and respects your account’s access.
Download OpenAPI schemaBase URL
https://api.wingman.st/v1Expand an operation for its request parameters and schema. The full OpenAPI document includes response schemas. IDs are owner-scoped; requests for another user’s private resources fail. Errors include an error code, message and request ID.
Connection
GET/meCheck your connection
Required permissions: any active key.
PermissionsAny active keySuccess: 200
View full response and error schemasquestions
GET/questions/facetsDiscover courses and topics
Required permissions: questions:read.
Permissionsquestions:readSuccess: 200
View full response and error schemasGET/questionsSearch the question bank
Published questions only. Use returned pins unchanged when creating a paper. Cursor pagination; random selection has no cursor.
Permissionsquestions:readSuccess: 200
Parameters
[
{
"name": "q",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
{
"name": "module",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
{
"name": "level",
"in": "query",
"schema": {
"type": "string",
"enum": [
"as-level",
"a-level",
"international-as-level",
"international-a-level"
]
}
},
{
"name": "subject",
"in": "query",
"schema": {
"type": "string",
"enum": [
"maths",
"further-maths"
]
}
},
{
"name": "board",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
{
"name": "year",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1900,
"maximum": 2100
}
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
{
"name": "topic",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
{
"name": "subtopic",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
{
"name": "difficulty",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5
}
},
{
"name": "minMarks",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 100
}
},
{
"name": "maxMarks",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 100
}
},
{
"name": "excludeIds",
"in": "query",
"schema": {
"default": [],
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"style": "form",
"explode": true
},
{
"name": "random",
"in": "query",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"name": "favouritesOnly",
"in": "query",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"name": "availableOnly",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "frequency",
"in": "query",
"schema": {
"type": "string",
"enum": [
"frequent",
"occasional",
"rare"
]
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
{
"name": "browseSeed",
"in": "query",
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"default": 30,
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
]GET/questions/{questionId}/revisions/{revision}Read a question and mark scheme
Required permissions: questions:read.
Permissionsquestions:readSuccess: 200
Parameters
[
{
"name": "questionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "revision",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
}
]GET/questions/{questionId}/revisions/{revision}/assets/{assetId}Download a question diagram
Required permissions: questions:read.
Permissionsquestions:readSuccess: 200
Parameters
[
{
"name": "questionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "revision",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"name": "assetId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]papers
GET/papersList your saved Builder papers
Required permissions: papers:read.
Permissionspapers:readSuccess: 200
View full response and error schemasPOST/papersSave a paper from question pins
Generate a UUID for id and reuse it with the identical body on retries. Saving does not prepare PDFs.
Permissionspapers:writeSuccess: 201
JSON Schema · request body
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"coverContext": {
"type": "string",
"enum": [
"composed-paper",
"topic-assessment"
]
},
"questions": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"questionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"contentRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"schemeVersionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"schemeSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"catalogueRevision": {
"anyOf": [
{
"type": "object",
"properties": {
"resourceId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"resourceId",
"revisionId",
"revision"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"questionId",
"contentRevision",
"contentSha256",
"schemeVersionId",
"schemeSha256",
"catalogueRevision"
],
"additionalProperties": false
}
},
"writingSpace": {
"type": "string",
"enum": [
"smart",
"none",
"standard",
"extra",
"pages:1",
"pages:2",
"pages:3",
"pages:4",
"pages:5",
"pages:6",
"pages:7",
"pages:8",
"pages:9",
"pages:10"
]
},
"gradeGuide": {
"default": false,
"type": "boolean"
}
},
"required": [
"id",
"title",
"questions",
"writingSpace"
],
"additionalProperties": false
}GET/papers/{id}Read your latest paper revision
Required permissions: papers:read.
Permissionspapers:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]PATCH/papers/{id}Save a new paper revision
Send the current revision for optimistic concurrency. A stale revision returns 409.
Permissionspapers:writeSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"revision": {
"type": "integer",
"minimum": 1,
"maximum": 2147483646
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"coverContext": {
"type": "string",
"enum": [
"composed-paper",
"topic-assessment"
]
},
"questions": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"questionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"contentRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"schemeVersionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"schemeSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"catalogueRevision": {
"anyOf": [
{
"type": "object",
"properties": {
"resourceId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"resourceId",
"revisionId",
"revision"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"questionId",
"contentRevision",
"contentSha256",
"schemeVersionId",
"schemeSha256",
"catalogueRevision"
],
"additionalProperties": false
}
},
"writingSpace": {
"type": "string",
"enum": [
"smart",
"none",
"standard",
"extra",
"pages:1",
"pages:2",
"pages:3",
"pages:4",
"pages:5",
"pages:6",
"pages:7",
"pages:8",
"pages:9",
"pages:10"
]
},
"gradeGuide": {
"default": false,
"type": "boolean"
}
},
"required": [
"revision",
"title",
"questions",
"writingSpace"
],
"additionalProperties": false
}GET/papers/{id}/revisions/{revision}Read a frozen paper revision
Required permissions: papers:read.
Permissionspapers:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "revision",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
}
]POST/papers/{id}/revisions/{revision}/exportsPrepare both printable PDFs
Uses the same print renderer as Builder. Returns 200 when prepared synchronously or 202 with a background export job. Poll GET /papers/{id}/revisions/{revision} until both questionPaper and markScheme are present, then download. Preparation is safe to retry for the same frozen revision; do not create a replacement paper. Requires configured server PDF export service.
Permissionspapers:writeSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "revision",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
}
]JSON Schema · request body
{
"type": "object",
"properties": {},
"additionalProperties": false
}GET/papers/{id}/revisions/{revision}/exports/{kind}Download a prepared PDF
Required permissions: papers:read.
Permissionspapers:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "revision",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"name": "kind",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"question-paper",
"mark-scheme"
]
}
}
]Marking & imports
GET/marking/sessionsList your uploaded papers
Returns the 50 most recent papers as lightweight summaries. Read a session for full results.
Permissionsmarking:readSuccess: 200
View full response and error schemasPOST/marking/sessionsCreate an automated marking draft
Required permissions: marking:submit.
Permissionsmarking:submitSuccess: 201
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"title"
],
"additionalProperties": false
}POST/marking/sessions/from-builderMark a saved Builder paper
Required permissions: marking:submit, papers:read.
Permissionsmarking:submitpapers:readSuccess: 201
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"paperId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"sessionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483647
}
},
"required": [
"paperId",
"revision"
],
"additionalProperties": false
}GET/marking/sessions/{id}Read scans, results and feedback
Required permissions: marking:read.
Permissionsmarking:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]POST/marking/sessions/{id}/assetsUpload a scan or mark scheme
Required permissions: marking:submit.
Permissionsmarking:submitSuccess: 201
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "kind",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"work",
"scheme"
]
}
},
{
"name": "name",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 180
}
}
]Send raw PDF, PNG, JPEG or WebP bytes with the matching Content-Type. Maximum 25 MiB; up to 80 PDF pages. Set kind and name in the query string.
View full response and error schemasPOST/marking/sessions/{id}/startPrepare a complete paper for marking
Upload work and a scheme first. Starts bounded indexing to verify question marks. With credit billing enabled, questions remain drafts until you review and confirm a quote. Legacy deployments retain automatic marking.
Permissionsmarking:submitSuccess: 202
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]POST/marking/sessions/{id}/questionsPrepare selected question pages for marking
Preserves the selected work/scheme pages and question label. With credit billing enabled, returns an indexing run and preparationRequired=true; review and confirm a quote after preparation. Legacy deployments return a queued question.
Permissionsmarking:submitSuccess: 202
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"workAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"schemeAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"pageSelections": {
"type": "object",
"propertyNames": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"additionalProperties": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 80
}
}
}
},
"required": [
"label",
"workAssetIds",
"schemeAssetIds"
],
"additionalProperties": false
}GET/marking/sessions/{id}/quoteRead the current marking quote and spendable credits
Reads recovery state only. Does not create a quote or start marking.
Permissionsmarking:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]POST/marking/sessions/{id}/quoteQuote prepared questions without starting marking
Optionally select prepared question IDs. Cost comes from verified available marks; no client price or free-baseline claim is accepted.
Permissionsmarking:submitmarking:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"questionIds": {
"minItems": 1,
"maxItems": 24,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"additionalProperties": false
}POST/marking/sessions/{id}/quote/{quoteId}/confirmConfirm a reviewed marking quote and reserve its credits
Confirm only the exact reviewed quote within the user's authorised credit budget. Reuse the same Idempotency-Key after an uncertain response. Insufficient balance queues no marking work. Do not automatically generate and confirm a replacement quote.
Permissionsmarking:submitmarking:readSuccess: 202
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "quoteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]JSON Schema · request body
{
"type": "object",
"properties": {},
"additionalProperties": false
}GET/marking/assets/{id}Download one of your private scans
Required permissions: marking:read.
Permissionsmarking:readSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]PATCH/marking/questions/{id}Review individual mark decisions
Required permissions: marking:review.
Permissionsmarking:reviewSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"overrides": {
"type": "object",
"propertyNames": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"additionalProperties": {
"type": "string",
"enum": [
"awarded",
"withheld"
]
}
},
"revision": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"overrides",
"revision"
],
"additionalProperties": false
}PATCH/marking/questions/{id}/annotationsSave marks and comments on scans
Required permissions: marking:review.
Permissionsmarking:reviewSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]JSON Schema · request body
{
"type": "object",
"properties": {
"revision": {
"type": "integer",
"minimum": 0,
"maximum": 2147483646
},
"annotations": {
"maxItems": 200,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"assetId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"page": {
"type": "integer",
"minimum": 1,
"maximum": 80
},
"box": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"kind": {
"type": "string",
"enum": [
"mark",
"comment"
]
},
"criterionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 120
},
{
"type": "null"
}
]
},
"code": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 40
},
{
"type": "null"
}
]
},
"decision": {
"anyOf": [
{
"type": "string",
"enum": [
"awarded",
"withheld"
]
},
{
"type": "null"
}
]
},
"comment": {
"type": "string",
"maxLength": 2000
}
},
"required": [
"id",
"assetId",
"page",
"box",
"kind",
"criterionId",
"code",
"decision",
"comment"
],
"additionalProperties": false
}
},
"completed": {
"type": "boolean"
}
},
"required": [
"revision",
"annotations"
],
"additionalProperties": false
}POST/marking/importsCreate an external marking draft
Create with {title} for standalone scans, or {savedPaper:{paperId,revision}} for an owned frozen Builder paper. The saved-paper branch additionally requires papers:read and attaches its trusted scheme and source; upload only completed work. Neither branch starts provider calls or charges credits.
Permissionsmarking:importSuccess: 201
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]JSON Schema · request body
{
"anyOf": [
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"title"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"savedPaper": {
"type": "object",
"properties": {
"paperId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483647
}
},
"required": [
"paperId",
"revision"
],
"additionalProperties": false
}
},
"required": [
"savedPaper"
],
"additionalProperties": false
}
]
}POST/marking/imports/{id}/assetsUpload source pages for an import
Required permissions: marking:import.
Permissionsmarking:importSuccess: 201
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "kind",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"work",
"scheme"
]
}
},
{
"name": "name",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 180
}
}
]Send raw PDF, PNG, JPEG or WebP bytes with the matching Content-Type. Maximum 25 MiB; up to 80 PDF pages. Set kind and name in the query string.
View full response and error schemasPOST/marking/imports/{id}/validateCheck an external marking submission
Validates without saving any results. Returns server-calculated scores and review flags; reports field-level errors with 422.
Permissionsmarking:importSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]JSON Schema · request body
{
"oneOf": [
{
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-marking-import-v1"
},
"coordinateSystem": {
"type": "string",
"const": "normalized-top-left"
},
"pageBasis": {
"type": "string",
"const": "displayed-page"
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"human",
"ai"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"markedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"required": [
"kind",
"name",
"markedAt"
],
"additionalProperties": false
},
"coverage": {
"type": "object",
"properties": {
"questionCount": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"totalMarks": {
"type": "integer",
"minimum": 1,
"maximum": 2400
}
},
"required": [
"questionCount",
"totalMarks"
],
"additionalProperties": false
},
"questions": {
"minItems": 1,
"maxItems": 24,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"workAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"schemeAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"pageSelections": {
"type": "object",
"propertyNames": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"additionalProperties": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 80
}
}
},
"rubric": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-rubric-v1"
},
"questionLabel": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"parts": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxMarks": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"id",
"label",
"maxMarks"
],
"additionalProperties": false
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"partId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"requirement": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"conditions": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 3000
}
},
"conditionMode": {
"type": "string",
"enum": [
"all",
"any"
]
},
"dependsOn": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"conditionDependencies": {
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"dependsOn": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"conditionIndex",
"dependsOn"
],
"additionalProperties": false
}
},
"maxMarks": {
"type": "number",
"const": 1
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"id",
"partId",
"code",
"requirement",
"conditions",
"conditionMode",
"dependsOn",
"maxMarks",
"sourcePageIds"
],
"additionalProperties": false
}
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"sourcePageIds": {
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"sourcePageIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"questionLabel",
"parts",
"criteria",
"sourcePageIds",
"issues"
],
"additionalProperties": false
},
"grade": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-grade-v1"
},
"unattemptedPartIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"criterionId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"decision": {
"type": "string",
"enum": [
"awarded",
"withheld",
"uncertain"
]
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
},
"conditionChecks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"decision": {
"type": "string",
"enum": [
"met",
"not_met",
"uncertain"
]
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
}
},
"required": [
"conditionIndex",
"decision",
"evidence"
],
"additionalProperties": false
}
}
},
"required": [
"criterionId",
"decision",
"reason",
"evidence",
"conditionChecks"
],
"additionalProperties": false
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"criterionIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"criteria",
"issues"
],
"additionalProperties": false
}
},
"required": [
"label",
"workAssetIds",
"schemeAssetIds",
"pageSelections",
"rubric",
"grade"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"coordinateSystem",
"pageBasis",
"source",
"coverage",
"questions"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-marking-import-v2"
},
"decisionBasis": {
"type": "string",
"const": "local"
},
"coordinateSystem": {
"type": "string",
"const": "normalized-top-left"
},
"pageBasis": {
"type": "string",
"const": "displayed-page"
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"human",
"ai"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"markedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"required": [
"kind",
"name",
"markedAt"
],
"additionalProperties": false
},
"coverage": {
"type": "object",
"properties": {
"questionCount": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"totalMarks": {
"type": "integer",
"minimum": 1,
"maximum": 2400
}
},
"required": [
"questionCount",
"totalMarks"
],
"additionalProperties": false
},
"questions": {
"minItems": 1,
"maxItems": 24,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"workAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"schemeAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"pageSelections": {
"type": "object",
"propertyNames": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"additionalProperties": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 80
}
}
},
"rubric": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-rubric-v1"
},
"questionLabel": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"parts": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxMarks": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"id",
"label",
"maxMarks"
],
"additionalProperties": false
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"partId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"requirement": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"conditions": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 3000
}
},
"conditionMode": {
"type": "string",
"enum": [
"all",
"any"
]
},
"dependsOn": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"conditionDependencies": {
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"dependsOn": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"conditionIndex",
"dependsOn"
],
"additionalProperties": false
}
},
"maxMarks": {
"type": "number",
"const": 1
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"id",
"partId",
"code",
"requirement",
"conditions",
"conditionMode",
"dependsOn",
"maxMarks",
"sourcePageIds"
],
"additionalProperties": false
}
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"sourcePageIds": {
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"sourcePageIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"questionLabel",
"parts",
"criteria",
"sourcePageIds",
"issues"
],
"additionalProperties": false
},
"grade": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-grade-v1"
},
"unattemptedPartIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"criterionId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"decision": {
"type": "string",
"enum": [
"awarded",
"withheld",
"uncertain"
]
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
},
"conditionChecks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"decision": {
"type": "string",
"enum": [
"met",
"not_met",
"uncertain"
]
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
}
},
"required": [
"conditionIndex",
"decision",
"evidence"
],
"additionalProperties": false
}
}
},
"required": [
"criterionId",
"decision",
"reason",
"evidence",
"conditionChecks"
],
"additionalProperties": false
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"criterionIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"criteria",
"issues"
],
"additionalProperties": false
}
},
"required": [
"label",
"workAssetIds",
"schemeAssetIds",
"pageSelections",
"rubric",
"grade"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"decisionBasis",
"coordinateSystem",
"pageBasis",
"source",
"coverage",
"questions"
],
"additionalProperties": false
}
]
}POST/marking/imports/{id}/recognizeRecognize the published source of imported marking
Rechecks owned uploaded PDFs against exact registered publication revisions. Preserves marks and reviews; never trusts a filename or cover alone. No model calls or credit charges.
Permissionsmarking:importSuccess: 200
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]POST/marking/imports/{id}/completeSave externally marked work to your account
Validates again and saves every question atomically. An identical submission can be replayed; changed submissions conflict. External provenance remains visible.
Permissionsmarking:importSuccess: 201
Idempotency-Key is required. Keep the same key for retries of this operation.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
},
"description": "Reuse for retries of the same operation. Keys are isolated per API key. Completed imports are also immutable per session and payload."
}
]JSON Schema · request body
{
"oneOf": [
{
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-marking-import-v1"
},
"coordinateSystem": {
"type": "string",
"const": "normalized-top-left"
},
"pageBasis": {
"type": "string",
"const": "displayed-page"
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"human",
"ai"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"markedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"required": [
"kind",
"name",
"markedAt"
],
"additionalProperties": false
},
"coverage": {
"type": "object",
"properties": {
"questionCount": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"totalMarks": {
"type": "integer",
"minimum": 1,
"maximum": 2400
}
},
"required": [
"questionCount",
"totalMarks"
],
"additionalProperties": false
},
"questions": {
"minItems": 1,
"maxItems": 24,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"workAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"schemeAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"pageSelections": {
"type": "object",
"propertyNames": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"additionalProperties": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 80
}
}
},
"rubric": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-rubric-v1"
},
"questionLabel": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"parts": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxMarks": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"id",
"label",
"maxMarks"
],
"additionalProperties": false
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"partId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"requirement": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"conditions": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 3000
}
},
"conditionMode": {
"type": "string",
"enum": [
"all",
"any"
]
},
"dependsOn": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"conditionDependencies": {
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"dependsOn": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"conditionIndex",
"dependsOn"
],
"additionalProperties": false
}
},
"maxMarks": {
"type": "number",
"const": 1
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"id",
"partId",
"code",
"requirement",
"conditions",
"conditionMode",
"dependsOn",
"maxMarks",
"sourcePageIds"
],
"additionalProperties": false
}
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"sourcePageIds": {
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"sourcePageIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"questionLabel",
"parts",
"criteria",
"sourcePageIds",
"issues"
],
"additionalProperties": false
},
"grade": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-grade-v1"
},
"unattemptedPartIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"criterionId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"decision": {
"type": "string",
"enum": [
"awarded",
"withheld",
"uncertain"
]
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
},
"conditionChecks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"decision": {
"type": "string",
"enum": [
"met",
"not_met",
"uncertain"
]
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
}
},
"required": [
"conditionIndex",
"decision",
"evidence"
],
"additionalProperties": false
}
}
},
"required": [
"criterionId",
"decision",
"reason",
"evidence",
"conditionChecks"
],
"additionalProperties": false
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"criterionIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"criteria",
"issues"
],
"additionalProperties": false
}
},
"required": [
"label",
"workAssetIds",
"schemeAssetIds",
"pageSelections",
"rubric",
"grade"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"coordinateSystem",
"pageBasis",
"source",
"coverage",
"questions"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-marking-import-v2"
},
"decisionBasis": {
"type": "string",
"const": "local"
},
"coordinateSystem": {
"type": "string",
"const": "normalized-top-left"
},
"pageBasis": {
"type": "string",
"const": "displayed-page"
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"human",
"ai"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"markedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"required": [
"kind",
"name",
"markedAt"
],
"additionalProperties": false
},
"coverage": {
"type": "object",
"properties": {
"questionCount": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"totalMarks": {
"type": "integer",
"minimum": 1,
"maximum": 2400
}
},
"required": [
"questionCount",
"totalMarks"
],
"additionalProperties": false
},
"questions": {
"minItems": 1,
"maxItems": 24,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"workAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"schemeAssetIds": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"pageSelections": {
"type": "object",
"propertyNames": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"additionalProperties": {
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 80
}
}
},
"rubric": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-rubric-v1"
},
"questionLabel": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"parts": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxMarks": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"id",
"label",
"maxMarks"
],
"additionalProperties": false
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"partId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"requirement": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"conditions": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 3000
}
},
"conditionMode": {
"type": "string",
"enum": [
"all",
"any"
]
},
"dependsOn": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"conditionDependencies": {
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"dependsOn": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"conditionIndex",
"dependsOn"
],
"additionalProperties": false
}
},
"maxMarks": {
"type": "number",
"const": 1
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"id",
"partId",
"code",
"requirement",
"conditions",
"conditionMode",
"dependsOn",
"maxMarks",
"sourcePageIds"
],
"additionalProperties": false
}
},
"sourcePageIds": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"sourcePageIds": {
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"sourcePageIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"questionLabel",
"parts",
"criteria",
"sourcePageIds",
"issues"
],
"additionalProperties": false
},
"grade": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "wingman-grade-v1"
},
"unattemptedPartIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"criteria": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"criterionId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"decision": {
"type": "string",
"enum": [
"awarded",
"withheld",
"uncertain"
]
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
},
"conditionChecks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"conditionIndex": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"decision": {
"type": "string",
"enum": [
"met",
"not_met",
"uncertain"
]
},
"evidence": {
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"quote": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"box": {
"anyOf": [
{
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"pageId",
"quote",
"box"
],
"additionalProperties": false
}
}
},
"required": [
"conditionIndex",
"decision",
"evidence"
],
"additionalProperties": false
}
}
},
"required": [
"criterionId",
"decision",
"reason",
"evidence",
"conditionChecks"
],
"additionalProperties": false
}
},
"issues": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 3000
},
"criterionIds": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
}
},
"required": [
"message",
"criterionIds"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"criteria",
"issues"
],
"additionalProperties": false
}
},
"required": [
"label",
"workAssetIds",
"schemeAssetIds",
"pageSelections",
"rubric",
"grade"
],
"additionalProperties": false
}
}
},
"required": [
"schemaVersion",
"decisionBasis",
"coordinateSystem",
"pageBasis",
"source",
"coverage",
"questions"
],
"additionalProperties": false
}
]
}