API for AI agents

Let ChatGPT, Claude & co. turn your slides, a PDF or an article into a Handzeichen deck. The agent gets back a presenter link, the join code and a QR code.

Create a deck

curl -X POST https://handzeichen.com/api/v1/decks \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Photosynthesis – quick check",
  "settings": {
    "mode": "live",
    "showResults": true
  },
  "slides": [
    {
      "type": "choice",
      "question": "Where does the light reaction take place?",
      "options": [
        "Thylakoid",
        "Stroma",
        "Nucleus"
      ],
      "correct": 0
    },
    {
      "type": "scale",
      "question": "How confident do you feel about the topic?",
      "labels": {
        "lo": "unsure",
        "hi": "very sure"
      }
    },
    {
      "type": "cluster",
      "question": "Where do you stand?",
      "labels": {
        "lo": "theory",
        "hi": "practice",
        "top": "motivated",
        "bottom": "tired"
      }
    },
    {
      "type": "wordcloud",
      "question": "One word about plants?"
    }
  ]
}'

Response (201): code, host_url, participant_url, mitmach_url (only for mode "async"), qr_svg, host_token. Open host_url in the browser and present.

Read and edit a deck

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 returns all slides with an id. PATCH sends the complete new slide list in the desired order: slides with an id are updated (same type and options: answers are kept), just {"id"} keeps the slide unchanged, slides without id are new, omitted ones are deleted. Code and links stay the same.

Fetch results

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

Only aggregated results per slide (counts, averages, word cloud, ideas). No participant IDs, no names.

Slide types

`choice`	Multiple choice, 2–10 options; with correct (0-based index) it becomes a quiz
`quiz`	Alias for choice, correct is required
`scale`	Scale 1–5, labels.lo/hi
`emoji`	Mood 😡–😍
`slider`	Slider, default 0–100 %; custom range with range {min, max, step, unit}, e.g. {"min": 0, "max": 12, "step": 0.5, "unit": "hours"}; labels.lo/hi
`cluster (map, 2d)`	2D map for positioning, labels.lo/hi/top/bottom
`scales`	several statements (options 1–10), each 1–5
`ranking`	Ranking, options 2–10
`wordcloud`	Word cloud
`ideas`	open ideas with upvotes
`text (freetext, open)`	Open text answers: everyone writes a free answer, no upvotes, newest first
`info`	Info slide without voting
`media (video)`	Show a video and collect reactions: video (YouTube or Vimeo link), react "comment" (open text, default), "scale" (1–5, labels.lo/hi) or "none". Image galleries only in the editor (own uploads).

Question max. 200 characters, option max. 100, label max. 30, title max. 120. Optional per slide: image (https link), timer (15–300 s), hideResults.

Without and with an API key

Without a key: anonymous deck, max. 10 slides, 10 decks per hour, mode "live" only. It is deleted after 30 days without activity. With an account you can adopt it via the host_url.
With a key (Authorization: Bearer hz_…): the deck goes into your account, no 10-slide limit, 100 decks per hour, open polls (mode "async") too. Create keys under My profile → Settings. A key is shown only once; only a hash is stored.

MCP

Easiest: add https://handzeichen.com/mcp as a connector in your AI chat (Claude, ChatGPT, Le Chat, Cursor, VS Code …). Guide: https://handzeichen.com/mcp.

Alternatively local: for Claude Desktop, Cursor & co. there is a small dependency-free MCP server (one Node file) with the tools create_deck, get_deck, update_deck and get_results. Configuration: HANDZEICHEN_URL and optionally HANDZEICHEN_API_KEY.

Privacy

The server is located in Germany. What the agent sends is stored as slide text in Handzeichen. Please do not put personal data in questions.