API für KI-Agenten

Lass ChatGPT, Claude & Co. aus deinen Folien, einem PDF oder einem Artikel ein Handzeichen-Deck bauen. Der Agent bekommt einen Link zum Präsentieren, den Teilnahme-Code und einen QR-Code zurück.

Deck anlegen

curl -X POST https://handzeichen.com/api/v1/decks \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Photosynthese – kurzer Check",
  "settings": {
    "mode": "live",
    "showResults": true
  },
  "slides": [
    {
      "type": "choice",
      "question": "Wo findet die Lichtreaktion statt?",
      "options": [
        "Thylakoid",
        "Stroma",
        "Zellkern"
      ],
      "correct": 0
    },
    {
      "type": "scale",
      "question": "Wie sicher fühlst du dich im Thema?",
      "labels": {
        "lo": "unsicher",
        "hi": "sehr sicher"
      }
    },
    {
      "type": "cluster",
      "question": "Wo stehst du?",
      "labels": {
        "lo": "Theorie",
        "hi": "Praxis",
        "top": "motiviert",
        "bottom": "müde"
      }
    },
    {
      "type": "wordcloud",
      "question": "Ein Wort zu Pflanzen?"
    }
  ]
}'

Antwort (201): code, host_url, participant_url, mitmach_url (nur bei mode "async"), qr_svg, host_token. Den host_url im Browser öffnen und präsentieren.

Deck lesen und bearbeiten

curl https://handzeichen.com/api/v1/decks/CODE -H 'Authorization: Bearer HOST_TOKEN'
curl -X PATCH https://handzeichen.com/api/v1/decks/CODE \
  -H 'Authorization: Bearer HOST_TOKEN' -H 'Content-Type: application/json' \
  -d '{"title": "…", "slides": [{"id": "a1b2c3d4e5f6"}, {"type": "wordcloud", "question": "…"}]}'

GET liefert alle Folien mit id. PATCH schickt die komplette neue Folienliste in der gewünschten Reihenfolge: Folien mit id werden angepasst (gleicher Typ und gleiche Optionen: Antworten bleiben erhalten), nur {"id"} behält die Folie unverändert, Folien ohne id sind neu, weggelassene werden gelöscht. Code und Links bleiben gleich.

Ergebnisse abrufen

curl https://handzeichen.com/api/v1/decks/CODE/results \
  -H 'Authorization: Bearer HOST_TOKEN'

Nur zusammengefasste Ergebnisse je Folie (Anzahlen, Durchschnitte, Wortwolke, Ideen). Keine Teilnehmer-IDs, keine Namen.

Folientypen

`choice`	Auswahl, 2–10 options; mit correct (Index ab 0) wird es ein Quiz
`quiz`	Alias für choice, correct ist Pflicht
`scale`	Skala 1–5, labels.lo/hi
`emoji`	Stimmung 😡–😍
`slider`	Regler, Standard 0–100 %; eigener Bereich mit range {min, max, step, unit}, z. B. {"min": 0, "max": 12, "step": 0.5, "unit": "Stunden"}; labels.lo/hi
`cluster (map, 2d)`	2D-Karte zum Positionieren, labels.lo/hi/top/bottom
`scales`	mehrere Aussagen (options 1–10), je 1–5
`ranking`	Rangfolge, options 2–10
`wordcloud`	Wortwolke
`ideas`	offene Ideen mit Upvotes
`text (freetext, open)`	Freitext-Antworten: jede Person schreibt eine freie Antwort, ohne Upvotes, neueste zuerst
`info`	Hinweisfolie ohne Abstimmung
`media (video)`	Video zeigen und reagieren lassen: video (YouTube- oder Vimeo-Link), react "comment" (Freitext, Standard), "scale" (1–5, labels.lo/hi) oder "none". Bildergalerien gehen nur im Editor (eigene Uploads).

Frage max. 200 Zeichen, Option max. 100, Beschriftung max. 30, Titel max. 120. Optional je Folie: image (https-Link), timer (15–300 s), hideResults.

Ohne und mit API-Key

Ohne Key: anonymes Deck, max. 10 Folien, 10 Decks pro Stunde, nur mode "live". Es wird nach 30 Tagen ohne Aktivität gelöscht. Mit Konto lässt es sich über den host_url übernehmen.
Mit Key (Authorization: Bearer hz_…): Das Deck landet in deinem Konto, keine 10-Folien-Grenze, 100 Decks pro Stunde, auch Mitmach-Umfragen (mode "async"). Schlüssel erstellst du unter Mein Profil → Einstellungen. Er wird nur einmal angezeigt, gespeichert wird nur ein Hash.

MCP

Am einfachsten: die Adresse https://handzeichen.com/mcp in deinem KI-Chat als Konnektor einfügen (Claude, ChatGPT, Le Chat, Cursor, VS Code …). Anleitung: https://handzeichen.com/mcp.

Alternativ lokal: Für Claude Desktop, Cursor & Co. gibt es einen kleinen MCP-Server ohne Abhängigkeiten (eine Node-Datei) mit den Werkzeugen create_deck, get_deck, update_deck und get_results. Konfiguration: HANDZEICHEN_URL und optional HANDZEICHEN_API_KEY.

Datenschutz

Der Server steht in Deutschland. Was der Agent schickt, landet als Folientext in Handzeichen. Bitte keine personenbezogenen Daten in Fragen schreiben.