# Motje API Documentatie voor AI Agents

Motje (https://www.huiswerkspel.nl) is een kindvriendelijk overhoorplatform voor schoolvakken zoals talen (Duits, Frans) en topografie/kennisvragen.

Met deze API kunnen AI-agents zelfstandig nieuwe vragen- en woordenlijsten aanmaken op basis van bronmateriaal (zoals foto's van huiswerkboeken of werkbladen).

---

## 1. Authenticatie
Authenticeer elk API-verzoek met de HTTP header `X-API-Key` of `Authorization`:
```http
X-API-Key: motje_sk_xxxxxxxxxxxxxxxx
```
of:
```http
Authorization: Bearer motje_sk_xxxxxxxxxxxxxxxx
```
*API-sleutels worden beheerd door de beheerder in het beheerpaneel en hebben een maximale geldigheid van 1 jaar.*

---

## 2. Lijst Importeren: `POST /api/lists/import`

Endpoint: `POST https://www.huiswerkspel.nl/api/lists/import`  
Content-Type: `application/json`

### JSON Payload Velden
- `name` (string, **verplicht**): De naam van de lijst (bijv. "Duits: Kapitel 3 - Wohnen" of "Topografie: Hoofdsteden van Europa").
- `subject` (string of integer, optioneel): De naam of het ID van het schoolvak (bijv. "Duits", "Topografie", "Frans").
- `description` (string, optioneel): Korte beschrijving van de inhoud.
- `term_label` (string, optioneel): Label voor de vraag/term (bijv. "Duits", "Vraag"). Standaard overgenomen van het schoolvak.
- `definition_label` (string, optioneel): Label voor de vertaling of oplossing (bijv. "Nederlands", "Antwoord").
- `audio_lang` (string of null, optioneel): BCP-47 taalcode voor spraakuitspraak (bijv. "de-DE", "fr-FR", of `null`).
- `shared_image_base64` (string, optioneel): Een Base64-geëncodeerde afbeelding (bijv. een overzichtskaart) die automatisch aan **alle** vragen in deze lijst wordt gekoppeld.
- `items` (array, **verplicht**): Een lijst van vraag-/woordobjecten:
  - `term` (string, **verplicht**): Het te leren woord of de vraag.
  - `definition` (string, **verplicht**): De Nederlandse vertaling of het antwoord.
  - `category` (string, optioneel): Categorie voor groepering (bijv. "der-woorden", "Werkwoorden", "Noord-Europa").
  - `hint` (string, optioneel): Extra hint of voorbeeldzin.
  - `image_base64` (string, optioneel): Een unieke Base64-afbeelding specifiek voor dit item (overschrijft eventueel `shared_image_base64`).

*Opmerking: Geïmporteerde lijsten worden aangemaakt zonder automatische gebruikerskoppeling, zodat de beheerder de inhoud eerst kan controleren.*

---

## 3. Beschikbare Schoolvakken
- **Frans** (🥐): `term_label`: "Frans", `definition_label`: "Nederlands", `audio_lang`: "fr-FR"
- **Topografie** (🗺️): `term_label`: "Vraag", `definition_label`: "Antwoord", `audio_lang`: null
- **Duits** (🇩🇪): `term_label`: "Duits", `definition_label`: "Nederlands", `audio_lang`: "de-DE"

---

## 4. Voorbeelden

### Voorbeeld A: Woordenlijst (Duits)
```json
{
  "name": "Duits: Kapitel 3 - Wohnen & Wortschatz",
  "subject": "Duits",
  "description": "Woorden over het huis, meubels en werkwoorden.",
  "items": [
    {
      "term": "der Balkon (die Balkons)",
      "definition": "het balkon",
      "category": "Het huis: der-woorden",
      "hint": ""
    },
    {
      "term": "aufräumen",
      "definition": "opruimen",
      "category": "Werkwoorden",
      "hint": ""
    }
  ]
}
```

### Voorbeeld B: Topografie met gedeelde overzichtskaart
```json
{
  "name": "Topografie: Hoofdsteden van Europa",
  "subject": "Topografie",
  "description": "Oefen alle 45 Europese hoofdsteden.",
  "shared_image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "items": [
    {
      "term": "Welke stad hoort bij nummer 1 op de kaart?",
      "definition": "Reykjavik",
      "category": "Noord-Europa",
      "hint": "Hoofdstad van IJsland"
    },
    {
      "term": "Welke stad hoort bij nummer 2 op de kaart?",
      "definition": "Oslo",
      "category": "Noord-Europa",
      "hint": "Hoofdstad van Noorwegen"
    }
  ]
}
```

---

## 5. Antwoordformaat

### Succes (HTTP 201 Created)
```json
{
  "success": true,
  "list_id": 8,
  "name": "Topografie: Hoofdsteden van Europa",
  "subject": "Topografie",
  "item_count": 45,
  "message": "Lijst succesvol aangemaakt! De beheerder kan deze nu toewijzen aan leerlingen."
}
```

### Foutmelding (HTTP 400 of 401)
```json
{
  "success": false,
  "error": "Foutomschrijving"
}
```

---

## 6. Machine-leesbare OpenAPI specificatie
Een formele OpenAPI 3.0 specificatie en Swagger UI worden automatisch gegenereerd via DTO-annotaties:
- OpenAPI JSON: `https://www.huiswerkspel.nl/docs/openapi.json` (ook via `https://www.huiswerkspel.nl/openapi.json` of `/api/openapi.json`)
- Interactieve Swagger UI: `https://www.huiswerkspel.nl/docs/swagger`
- Interactieve Redoc: `https://www.huiswerkspel.nl/docs/redoc`