Eulernen API für Entwickler und Agenten

Eulernen veröffentlicht seinen Katalog mit allen 22 Lernposter-Sets für die Grundschule über offene Schnittstellen. Alle sind öffentlich, nur lesend und ohne Anmeldung: Es gibt keine API-Schlüssel, kein Konto und keine Sandbox, weil keine Anfrage etwas verändert. Preise, Bestellung und Kauf gibt es nur bei Etsy.

Katalog-API

Eine JSON-Datei mit allen Sets: Fach, Klassen, Edition, Stil und Postertitel, dazu Lieferarten, Lizenz und Shop-Link. Gefiltert wird beim Client, auf dem Server filtert die Abfrage-API. Die OpenAPI-Beschreibung (OpenAPI 3.1, operationId getCatalog) beschreibt Antwort und Fehler mit Schemas. Cross-Origin-Abrufe sind erlaubt (Access-Control-Allow-Origin: *).

curl -s https://eulernen.de/api/v1/catalog.json

{
  "name": "Eulernen",
  "shop": "https://www.etsy.com/shop/Eulernen",
  "sets": [
    {
      "id": "mathe12",
      "name": "Mathe-Lernposter Klasse 1/2",
      "subject": "Mathe",
      "grades": [1, 2],
      "edition": null,
      "style": "Klassisch",
      "posterCount": 12,
      "posters": ["Zahlen bis 20", "Zahlen zerlegen", …]
    },
    …
  ]
}

Abfrage-API

Filtert die Sets auf dem Server. GET /api/v1/sets (operationId listSets) nimmt die optionalen Parameter subject (Mathe, Deutsch, Englisch, HSU), grade (1 bis 4), edition (Bayern, Allgemein) und style (Klassisch, Aquarell). Die Antwort enthält die passenden Sets ohne Postertitel, dazu Shop-Link und Verkaufsstand. GET /api/v1/sets/{id} (getSet) liefert ein Set mit allen Postertiteln. Unbekannte Parameter oder Werte ergeben 400, eine unbekannte id ergibt 404, beides als problem+json.

curl -s 'https://eulernen.de/api/v1/sets?subject=Mathe&grade=2&edition=Bayern'

{
  "sets": [
    {
      "id": "mathe12_bayern",
      "name": "Mathe-Lernposter Klasse 1/2 · Bayern",
      "subject": "Mathe",
      "grades": [1, 2],
      "edition": "Bayern",
      "style": "Klassisch",
      "posterCount": 16
    },
    …
  ],
  "shop": "https://www.etsy.com/shop/Eulernen",
  "availability": "Verkauft wird nur über Etsy; …"
}

curl -s https://eulernen.de/api/v1/sets/mathe12_bayern_aquarell

{
  "set": {
    "id": "mathe12_bayern_aquarell",
    "posterCount": 16,
    "posters": ["Zahlen bis 20", …],
    …
  },
  "shop": "https://www.etsy.com/shop/Eulernen",
  "availability": "…"
}

MCP-Server

Streamable HTTP unter https://eulernen.de/mcp, zustandslos, für die Protokollversionen 2026-07-28, 2025-11-25, 2025-06-18 und 2025-03-26. Ein MCP-Client braucht nur die URL, weder OAuth noch API-Schlüssel. Metadaten stehen in der MCP Server Card.

• list_sets: Sets suchen, optional nach subject (Mathe, Deutsch, Englisch, HSU), grade (1 bis 4), edition ("Bayern" oder null) und style (Klassisch, Aquarell)
• get_set: ein Set mit allen Postertiteln, Parameter id

curl -s https://eulernen.de/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {"name": "list_sets", "arguments": {"subject": "Mathe", "grade": 2, "edition": "Bayern"}}
}'

A2A-Agent

JSON-RPC unter https://eulernen.de/a2a mit SendMessage (A2A 1.0) und message/send (A2A 0.3). Der Agent liest Fach, Klasse, Bayern und Stil aus einer deutschen Anfrage, ohne Sprachmodell, und antwortet mit Text und JSON-Daten. Beschrieben in der A2A Agent Card.

curl -s https://eulernen.de/a2a -H 'Content-Type: application/json' -H 'A2A-Version: 1.0' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "SendMessage",
  "params": {"message": {"messageId": "1", "role": "ROLE_USER", "parts": [{"text": "Mathe Klasse 2 Bayern"}]}}
}'

WebMCP

Die Startseite lädt webmcp.js. In Browsern mit WebMCP (document.modelContext oder navigator.modelContext) registriert es die Tools list_sets und get_set; beide lesen /api/v1/catalog.json. Bei list_sets heißt die allgemeine Edition hier "Allgemein".

Discovery-Dateien

Fehler

Fehler unter /api/ kommen als application/problem+json nach RFC 9457 mit type, title, status, detail, instance und resolution, einem Hinweis, wie es weitergeht. In der OpenAPI-Beschreibung verweist jede Fehlerantwort auf dasselbe Schema Problem.

curl -i https://eulernen.de/api/v2/catalog.json

HTTP/2 404
content-type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Nothing is published at /api/v2/catalog.json.",
  "instance": "/api/v2/catalog.json",
  "resolution": "GET https://eulernen.de/api/v1/catalog.json returns the catalogue, …"
}

Andere unbekannte Adressen antworten ebenfalls mit 404: als HTML-Seite, mit Accept: text/markdown als Markdown mit Links zu llms.txt und Sitemap, mit Accept: application/json als problem+json. MCP und A2A melden Fehler als JSON-RPC-Fehlerobjekte.

Rate-Limit

Für /api/, /mcp und /a2a gilt zusammen ein Limit von 60 Anfragen pro 60 Sekunden je Client-IP. Jede Antwort dort nennt die Regel im Header RateLimit-Policy nach dem IETF-Entwurf draft-ietf-httpapi-ratelimit-headers (q = Anfragen, w = Sekunden):

RateLimit-Policy: "default";q=60;w=60

Darüber antwortet der Server mit 429 als application/problem+json und Retry-After: 60; nach dieser Wartezeit geht es normal weiter. Gezählt wird je Cloudflare-Standort und mit kurzer Verzögerung, die Grenze ist also ungefähr. Einen Header RateLimit mit den verbleibenden Anfragen gibt es nicht, weil der Zähler sie nicht ausweist.

Versionierung

• Die Hauptversion steht im Pfad: /api/v1/.
• Änderungen innerhalb von v1 bleiben abwärtskompatibel; neue Felder können hinzukommen.
• Eine inkompatible Änderung bekommt einen neuen Pfad, etwa /api/v2/. Der alte Pfad bleibt erreichbar und wird vor dem Abschalten mit den Headern Deprecation (RFC 9745) und Sunset (RFC 8594) angekündigt.
• /api/catalog.json ist ein Alias von /api/v1/catalog.json.
• MCP und A2A handeln ihre Protokollversion selbst aus (MCP-Protocol-Version, A2A-Version).

Zugang

Keine Anmeldung, kein API-Schlüssel, keine Sandbox: Die Schnittstellen sind öffentlich und nur lesend. Über keine von ihnen lässt sich etwas kaufen, bestellen oder ändern. Gekauft wird nur bei Etsy, und ein Agent kauft nichts ohne ausdrückliche Bestätigung von Artikel und Gesamtpreis durch den Nutzer. Details stehen in auth.md.

Kontakt

Fragen zu den Schnittstellen an info@eulernen.de.

← Zur Startseite