API-referentie

Alles wat jouw AI — of jij — kunt aanroepen: schoolcurricula, de quiz zelf, plaatjes, pdf’s en een seintje dat er nog gewerkt wordt.

Zo meld je een verzoek aan

Quiz-aanroepen hebben Authorization: Bearer plus de quizsleutel nodig. Stuur If-Match met de huidige versie, zodat twee opslagacties elkaar niet overschrijven. Deze antwoorden worden nooit in de cache gezet.

Open het volledige schema

Basis-URL

https://quiz.ai/api/v1

Zo meld je een verzoek aan

Authorization: Bearer <quiz-scoped-key>

API-kaart

GET
/api/v1

Een kaart van de API en de links die volgen.

Geen sleutel nodig
GET
/api/v1/openapi.json

Het complete OpenAPI 3.1-schema — handig voor tools die het kunnen lezen.

Geen sleutel nodig

Schoolcurricula

GET
/api/v1/curricula

Lijst de schoolcurricula die we kennen.

Geen sleutel nodig
GET
/api/v1/curricula/{curriculumId}

Lees de details van één curriculum.

Geen sleutel nodig
GET
/api/v1/curricula/{curriculumId}/objectives?subject=math&grade=5&limit=100&offset=0

Zoek leerdoelen van een curriculum op vak en leerjaar.

Geen sleutel nodig

De quiz

GET
/api/v1/target

Zie voor welke quiz deze sleutel mag schrijven.

Quizsleutel
GET
/api/v1/quizzes/{quizId}

Lees de huidige quiz en het versienummer.

Quizsleutel
PUT
/api/v1/quizzes/{quizId}

Vervang de hele quiz in één opslag. Stuur If-Match zodat je nieuwer werk niet overschrijft.

Quizsleutel
POST
/api/v1/quizzes/{quizId}/publish

Check de quiz en maak hem openbaar. Stuur If-Match zodat je nieuwer werk niet overschrijft.

Quizsleutel

Plaatjes

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

Upload een PNG, JPEG, GIF of WebP. Wij slaan een schoon, statisch WebP op.

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

Teken een vraagtplaatje uit een sjabloon, of bekijk een voorbeeld als PNG of SVG.

Quizsleutel
GET
/api/v1/quizzes/{quizId}/images/{imageId}

Download een opgeslagen plaatje. Range-verzoeken worden ondersteund.

Quizsleutel
DELETE
/api/v1/quizzes/{quizId}/images/{imageId}

Verwijder een plaatje dat geen vraag meer gebruikt.

Quizsleutel
Vragenplaatjes

Pdf’s en activiteit

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

Start, ververs of stop het 90 seconden durende “nog aan het werk”-signaal.

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

Download een printbaar antwoordblad. Je kunt namen, een klas en een antwoordsleutel toevoegen.

Quizsleutel

Sla de hele quiz op

Jouw AI stuurt titel, beschrijving, taal en elke vraag in één keer. Dezelfde geldige quiz twee keer sturen is veilig.

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."
    }
  ]
}

Regels voor vragen

  • Elke vraag heeft een duidelijke formulering en twee tot zes ingevulde keuzes nodig.
  • Grenzen: titel 140 tekens, beschrijving 1.000, 1–100 vragen, formulering 500, elke keuze 240, uitleg 1.000.
  • correctChoiceIndex is de nulgebaseerde index van de juiste keuze.
  • De volgorde van de vragen is de volgorde in de lijst — de eerste is vraag 1.
  • Stuur het nieuwste versienummer in de If-Match-header zodat twee opslagacties elkaar niet in de weg zitten.

Publiceer als het klopt

Publiceren checkt de quiz nog eens en geeft je een stabiele openbare link. Mist er iets, herstel het, sla opnieuw op en publiceer.

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