API reference

Everything your AI — or you — can call: school curricula, the quiz itself, pictures, PDFs, and a working indicator.

How to authenticate

Quiz calls need Authorization: Bearer plus the quiz key. Send If-Match with the current revision so two saves cannot overwrite each other. These responses are never cached.

Open the full schema

Base URL

https://quiz.ai/api/v1

How to authenticate

Authorization: Bearer <quiz-scoped-key>

API map

GET
/api/v1

A map of the API and the links that follow.

No key needed
GET
/api/v1/openapi.json

The complete OpenAPI 3.1 schema — handy for tools that can read it.

No key needed

School curricula

GET
/api/v1/curricula

List the school curricula we know about.

No key needed
GET
/api/v1/curricula/{curriculumId}

Read the details for one curriculum.

No key needed
GET
/api/v1/curricula/{curriculumId}/objectives?subject=math&grade=5&limit=100&offset=0

Search a curriculum’s learning objectives by subject and year group.

No key needed

The quiz

GET
/api/v1/target

See which quiz this key is allowed to write.

Quiz key
GET
/api/v1/quizzes/{quizId}

Read the current quiz and its version number.

Quiz key
PUT
/api/v1/quizzes/{quizId}

Replace the whole quiz in one save. Send If-Match so you don’t overwrite newer work.

Quiz key
POST
/api/v1/quizzes/{quizId}/publish

Check the quiz and make it public. Send If-Match so you don’t overwrite newer work.

Quiz key

Pictures

POST
/api/v1/quizzes/{quizId}/images

Upload a PNG, JPEG, GIF, or WebP. We store a clean static WebP.

Quiz key
POST
/api/v1/quizzes/{quizId}/images/templates

Draw a question picture from a template, or preview it as PNG or SVG.

Quiz key
GET
/api/v1/quizzes/{quizId}/images/{imageId}

Download a stored picture. Range requests are supported.

Quiz key
DELETE
/api/v1/quizzes/{quizId}/images/{imageId}

Delete a picture that no question is using.

Quiz key
Question pictures

PDFs and activity

POST
/api/v1/quizzes/{quizId}/activity

Start, refresh, or stop the 90-second “still working” signal.

Quiz key
GET
/api/v1/quizzes/{quizId}/sheet.pdf?names=Alice,Bob&class=5B&key=0

Download a printable answer sheet. You can add names, a class, and an answer key.

Quiz key

Save the whole quiz

Your AI sends the title, description, language, and every question in one go. Sending the same valid quiz twice is safe.

HTTP
PUT /api/v1/quizzes/qz_7KF2M9qTx3aB
Authorization: Bearer <quiz-scoped-key>
Content-Type: application/json
If-Match: "0"

{
  "title": "A quick tour of the Solar System",
  "description": "Ten friendly questions for curious adults.",
  "language": "en-gb",
  "questions": [
    {
      "prompt": "Which planet has the shortest year?",
      "choices": ["Mercury", "Venus", "Earth", "Mars"],
      "correctChoiceIndex": 0,
      "explanation": "Mercury orbits the Sun in about 88 Earth days."
    }
  ]
}

Question rules

  • Every question needs a clear prompt and two to six non-empty choices.
  • Limits: title 140 characters, description 1,000, 1–100 questions, prompt 500, each choice 240, explanation 1,000.
  • correctChoiceIndex is the zero-based index of the right choice.
  • Question order is the array order — first in the list is question 1.
  • Send the latest version number in the If-Match header so two saves cannot clobber each other.

Publish when it looks right

Publishing double-checks the quiz and gives you a stable public link. If something’s missing, fix it, save again, and publish.

HTTP
POST /api/v1/quizzes/qz_7KF2M9qTx3aB/publish
Authorization: Bearer <quiz-scoped-key>
If-Match: "1"