# A little more confidence. Find the practice you need, make a paper and learn from your working. ## Your workspace Create a Wingman account and verify your email to use the Builder, marking and connected tools. Your saved papers and uploaded work belong to your account. The published question bank currently covers Edexcel Further Maths Core Pure, Further Statistics 1 and Further Mechanics 1. Use the available course and topic filters to see what is ready to use. ## From a topic to useful feedback 1. Open Builder. Choose a module, search a topic and select the questions you want to practise. 2. Save your paper and download the question paper and its matching mark scheme. Choose the writing space that suits you. 3. Complete the questions, scan your work and open Marking. Upload your work with its scheme, or choose the saved Builder paper, then review the marks on your pages. ## Bring your own tools Connections & API lets you give a script or compatible AI agent permission to work in your account. Each key has its own permissions, expiry and usage history. An agent can find questions, save a practice paper and return both PDFs. It can also request Wingman marking, or submit work it has already marked with the evidence needed for the same review experience. --- # Paper Builder Turn published exam questions into a paper that fits your practice. ## Choose your questions Filter by course, board, module, topic, subtopic, difficulty or available marks. Search titles and indexed question metadata, or use a random selection for variety. Question bank search is a filtered text search. Your agent can translate a broad request into several focused searches, inspect the results and choose suitable questions. ## Build and save Arrange selected questions in the order you want. Choose smart spacing, no writing space, or a fixed number of writing pages per question. Large papers must fit within the page limit. Saved published papers retain their question versions and matching schemes. Saving changes creates a new revision, so an earlier revision remains reproducible. A grade guide, if included, is an estimate rather than an official grade boundary. ## Download both PDFs The question paper and mark scheme are generated from the same saved revision. The API uses Wingman’s existing print renderer and layout checks. API export is a separate preparation step after saving. Wait for it to finish, then download question-paper and mark-scheme. Both downloads require your key; a download URL alone does not share private access. ## Mark your completed paper In Marking, choose a saved Builder paper and upload the scan of your completed work. Wingman keeps the source paper and matching scheme tied to that exact revision. Only the completed student scan is work evidence. A clean question paper or a mark scheme must never be presented as evidence of a student’s answer. --- # Marking & review See each decision alongside the working it refers to. ## Start with clear source documents Upload your completed question paper as work and its mark scheme as scheme. Keep all relevant instructions and pages legible. PDF, PNG, JPEG and WebP are supported; each file can be up to 25 MiB. PDFs can contain up to 80 pages; images contain one page. A session can hold up to 100 files and 300 MiB in total. Marking a single question can use up to 12 work pages and 12 scheme pages. The paper workflow supports up to 24 questions. ## Request automated marking Wingman prepares a rubric from the supplied scheme, assesses the visible working against each allocation and calculates a result. Automated marking runs in the background and uses your account’s existing allowance. A queued or running response is not a finished result. Wait until the questions are completed, need review, failed or cancelled. If a question fails, inspect its error and source documents before starting again. ## Read the result Each allocation has a mark code, a decision, an explanation and supporting evidence. Select a mark to inspect its location on the scan. You can review decisions and add marks or comments using the normal paper viewer. An uncertain allocation stays visible as needing review. A score range shows awarded marks through possible marks; its upper end is not a confirmed score. Method dependencies and the rubric’s conditions affect the result. ## Externally marked work Papers marked by you or another AI can be imported. The source is recorded, and the same viewer displays their rubric, evidence, decisions and review state. Importing validates the structure and relationships in the submitted marking. It does not certify the mathematical judgement or independently re-mark the paper. Neither automated nor imported marking is an official Edexcel examination result. --- # Keys & permissions Give each connection a clear purpose and just enough access. ## Create a key 1. Open the Wingman Developers site, sign in with your Wingman account, then open Connections & API and select Create key. 2. Name the connection, choose its permissions and select an expiry of 30 days, 90 days or one year. 3. Copy the key once and store it in your tool’s secret store. Wingman stores a fingerprint and cannot reveal it again. Keep keys out of chat messages, public repositories, browser code and query strings. Enter the key through the agent’s secure connection or secret settings. ## Choose what it can do Permissions are independent. A practice-paper assistant usually needs questions:read, papers:write and papers:read. An automated marking assistant usually needs marking:submit and marking:read. Starting from a saved Builder paper also requires papers:read. Reading marked work covers the owner’s marking area, including drafts and in-progress work. API keys cannot manage other keys, change account details, or access administration. | Permission | Access | | --- | --- | | questions:read | Search published questions; read their content, schemes and diagrams. | | papers:read | Read your saved Builder papers and prepared PDFs. | | papers:write | Create and update papers; prepare PDFs. | | marking:read | Read your uploaded scans, marking sessions and results. | | marking:submit | Upload work and request Wingman automated marking. | | marking:import | Upload and submit externally marked work. | | marking:review | Edit existing mark decisions and annotations. | ## Authenticate a request Use the Authorization header on every request, including private file downloads. The public API does not accept a browser session as authentication. ```shell curl "https://api.wingmanmaths.com/v1/me" \ -H "Authorization: Bearer $WINGMAN_API_KEY" ``` ## Replace or revoke Create a replacement to change a key’s permissions. Move the connection to the replacement, then revoke the old key. You can have up to 20 active keys. Revocation stops new requests immediately; already accepted work may finish. Keys also stop working on expiry or when the account is no longer verified. Account restrictions still apply to API requests. ## Track usage The key list shows lifetime requests, errors and the last use time. Open Usage for a 30-day breakdown by UTC date, operation and response status. Usage records contain counts and timings, not keys, request bodies, scan content or search terms. These are API request counts, not model-token usage or a billing statement. --- # Search & build a paper A complete path from a topic to a question paper and mark scheme. ## Discover the available filters Read GET /questions/facets for course, board, module, topic and subtopic values. Use the returned IDs exactly; labels are for display. Choose the learner’s module before broadening a search. ```shell curl "https://api.wingmanmaths.com/v1/questions/facets" \ -H "Authorization: Bearer $WINGMAN_API_KEY" ``` ## Find relevant questions Results contain items and nextCursor. Each item includes a version pin, source metadata, a question summary and eligible module profiles. Read the question’s revision to inspect its full content and scheme. For another page, send nextCursor as cursor with the same filters. A null cursor means the end. random=true supports a varied sample and cannot be combined with cursor. Repeat excludeIds to avoid questions already selected. The maximum page size is 100. ```shell curl --get "https://api.wingmanmaths.com/v1/questions" \ -H "Authorization: Bearer $WINGMAN_API_KEY" \ --data-urlencode "module=core-pure" \ --data-urlencode "q=complex numbers" \ --data-urlencode "limit=6" ``` ## Save the selection POST this shape to /papers, replacing the placeholders with a UUID and the returned pin objects. Keep pin fields unchanged: Wingman checks question content and scheme versions before saving. Keep the response’s paper.id and paper.revision. Repeating the same creation ID and body returns the same paper. Reusing the ID with different content conflicts. PATCH /papers/{id} saves changes using the current revision. ```json { "id": "", "title": "Complex numbers practice", "questions": [""], "writingSpace": "smart", "gradeGuide": false } ``` ## Prepare and download Return both files to the learner. Do not expose your API key in links. A 409 means the exports are not ready or the revision cannot be exported; a 503 means the service is unavailable. Honour Retry-After on capacity errors. 1. POST {} to /papers/{id}/revisions/{revision}/exports. Allow up to 120 seconds for preparation. 2. GET /papers/{id}/revisions/{revision}/exports/question-paper with your key and save the PDF. 3. GET /papers/{id}/revisions/{revision}/exports/mark-scheme with your key and save the matching PDF. --- # 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. ```shell curl "https://api.wingmanmaths.com/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. ```shell curl "https://api.wingmanmaths.com/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.pdf ``` ## Start marking POST to /marking/sessions/{id}/start with a fresh Idempotency-Key for this operation. A 202 response means Wingman accepted background work. Poll GET /marking/sessions/{id} about every five seconds, with backoff on errors. 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. 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. --- # Import marked work Keep the full marking experience: source scans, precise evidence, allocations and reviewable feedback. ## The import workflow 1. POST {title} to /marking/imports with an Idempotency-Key. Save the returned session ID. 2. POST raw work and scheme files to /marking/imports/{id}/assets?kind=work|scheme&name=…. Keep the returned asset IDs and page counts. 3. 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. 4. POST the submission to /marking/imports/{id}/validate. Correct any 422 field errors; inspect returned scores and review flags. 5. 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 :p, 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 Let your assistant organise practice while your work stays in Wingman. ## Connect once The download is an agent skill, not an automatically installed ChatGPT or Claude connector. Your chosen client must support skills, secure secrets and HTTP or script tools. An OpenAPI schema and plain-text documentation are available for tool integrations. 1. Create a Wingman key with the permissions your assistant needs. 2. Download the Wingman skill and add it to an agent that supports skills and running tools. The bundle includes a Python helper with no third-party dependencies. 3. Set WINGMAN_API_KEY in the agent’s secret environment. Set WINGMAN_API_BASE to https://api.wingmanmaths.com/v1. Keep the key out of ordinary chat. 4. Ask the assistant to check the connection, then describe what you want to practise. ## Find the right practice Give the assistant questions:read, papers:write and papers:read. It should discover available filters, inspect the questions, preserve returned version pins, save the selection and download both PDFs. If it cannot find enough suitable questions, it should explain the gap. ```prompt I’m struggling with complex numbers in Further Maths Core Pure. Find me six relevant Edexcel questions, build a practice paper with writing space, and return the paper and its mark scheme. ``` ## Use Wingman’s marking This workflow needs marking:submit and marking:read and uses the account’s automated-marking allowance. The assistant should wait for the background work and distinguish confirmed marks from unresolved decisions. ```prompt I’ve attached my completed paper and the mark scheme. Submit them to Wingman for automated marking, wait for the results, and show me which marks need review. ``` ## Bring the assistant’s marking back This workflow needs marking:import and usually marking:read. The assistant must use the import schema, include every allocation, validate the submission and submit it to the account. A score summary or a flattened image with ticks is not a complete import. Only ask an assistant to do this if it can inspect the actual page images. If it cannot locate evidence reliably, it should explain the limitation rather than fabricate boxes or claim examiner accuracy. ```prompt Mark my attached scan against the supplied Edexcel scheme, allocation by allocation. Use precise evidence boxes on the original pages, flag uncertainty, and submit the marked paper and results to Wingman. ``` ## For an agent with a terminal The helper also supports search, uploading and submitting automated marking, reading results, and validating or completing imports. Run it with --help for commands. It keeps resumable workflow IDs in the selected output directory and never writes the API key there. ```shell python3 scripts/wingman.py check python3 scripts/wingman.py build \ --module core-pure --query "complex numbers" \ --count 6 --title "Complex numbers practice" \ --output ./practice ``` --- # Limits, errors & retries Keep requests efficient, recover safely and know when to stop. ## Request allowances These counters are shared across application servers. Creating extra keys does not bypass the account limit. Requests denied by a scope or validation check still consume the admitted allowance. Rate-limited requests appear in usage but do not consume another admission. Separate limits still apply to uploads, saved papers, PDF preparation and automated marking. A key grants permission; it does not add account allowance. The API exposes X-RateLimit-Remaining and X-RateLimit-Daily-Remaining, accounting for both key and account quotas. | Limit | Per key | Across your account | | --- | --- | --- | | All requests per minute | 120 | 300 | | Accepted requests per UTC day | 10,000 | 20,000 | | Write requests per minute | 20 | 40 | ## Read the error Keep X-Request-Id when investigating a failed request. Private resource IDs belonging to another user do not grant access. ```json { "error": { "code": "insufficient_scope", "message": "This API key does not have all the permissions required for this operation.", "requiredScopes": ["papers:write"] }, "requestId": "" } ``` | Status | Action | | --- | --- | | 401 | Supply a valid, unexpired, unrevoked key for a verified account. | | 403 | Check required scopes and account restrictions. Do not repeatedly retry. | | 404 | Check the path and owner-scoped resource ID. | | 409 | Inspect the existing resource or revision before retrying. | | 413 / 415 | Reduce the payload or send the expected content type. | | 422 | Correct the fields reported in error.details. | | 429 | Wait for Retry-After, then retry within the account’s limits. | | 503 | Service is unavailable or disabled. Back off; keep the same operation IDs. | ## Retry without duplicating work - Use a stable Idempotency-Key for session creation, Builder-to-marking imports, starting marking, question requests and external import completion. A different operation needs a different key. - For paper creation, keep the client-generated UUID and exact body. For paper updates and reviews, use the returned current revision; a stale revision conflicts. - A file upload can succeed even if its response is lost. Check the session’s assets before repeating it. - Retry reads, identical creations and export preparation after transient errors with bounded exponential backoff. Honour Retry-After. Stop after a few attempts and report the saved resource ID so work can be resumed. ## Versioning and discovery Public routes live under v1. Clients should tolerate additional response fields, and should use the published schemas for strict request bodies. A schema version identifies imported marking independently of the API path version. Read openapi.json for machine-readable operations and llms-full.txt for the plain-text guides. Keys and account management use the signed-in Wingman app; API credentials never authenticate those pages.