API & agents

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, 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.wingman.st/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.wingman.st/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": "<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. The helper waits for a bounded interval and retains its selected pins and preparation state for resume. Do not create another paper after a timeout. A job response alone does not mean the files are ready, and generic job routes are not exposed by the public API. 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.

POST {} to /papers/{id}/revisions/{revision}/exports. A 200 response confirms readiness; 202 returns a background job.
After 202, poll GET /papers/{id}/revisions/{revision} until both questionPaper and markScheme export attachments are present. Keep the same frozen ID and revision.
GET /papers/{id}/revisions/{revision}/exports/question-paper with your key and save the PDF.
GET /papers/{id}/revisions/{revision}/exports/mark-scheme with your key and save the matching PDF.

Pathway, evidence & changes