Search & build a paper

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.

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.

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.

{
  "id": "<new UUID; keep it for retries>",
  "title": "Complex numbers practice",
  "questions": ["<copy each chosen result’s full pin object here>"],
  "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.