Zum Inhalt springen
Du siehst gerade das neue Puzzel.org Zurück zur aktuellen Seite
Entwickler-API

Erstelle Aktivitäten aus deinem eigenen System

Ein POST pro Aktivitätstyp. Schick deine Inhalte als JSON und du bekommst eine Aktivität in deinem Puzzel.org-Konto zurück, dazu eine URL, die du an Spieler weitergeben oder in ein iframe setzen kannst.

Basis-URL
https://puzzel.org/api/public/v1
Auth
Schlüssel + E-Mail im Body
Endpunkte
20 Aktivitätstypen
Kontingent
10 Aktivitäten pro Tag

Deine erste Anfrage

Nichts zu installieren, kein Handshake: Schick einen JSON-Body mit deinem Schlüssel, deiner E-Mail-Adresse und deinen Inhalten. Die Antwort enthält den Schlüssel der neuen Aktivität und die URL, unter der sie gespielt wird.

POST crossword 
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "de",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Jedes Beispiel auf dieser Seite ist eine vollständige, lauffähige Anfrage. Setz deinen eigenen Schlüssel und deine eigenen Inhalte ein und es funktioniert genau so.

Authentifizierung

Es gibt keine Header und kein Bearer-Token. Beide Zugangsdaten stehen im JSON-Body jeder Anfrage, und der Schlüssel wird nur für das Konto akzeptiert, zu dem die E-Mail-Adresse gehört.

FeldTypWas es macht
account_api_key
erforderlich
string
stringDer API-Schlüssel deines Kontos. Er gehört in den Body, nicht in einen Header.
email
erforderlich
string
stringDie Adresse, mit der sich dein Puzzel.org-Konto anmeldet. Der Schlüssel ist nur zusammen mit ihr gültig.

Deinen Schlüssel findest du im Kontobereich deines Dashboards, hinter Anzeigen.

Anmelden

API-Schlüssel werden mit dem Start eines Abos vergeben, ein kostenloses Konto hat also noch keinen.

Tarife ansehen

Behandle den Schlüssel wie ein Passwort. Er erstellt und überschreibt Aktivitäten in deinem Konto, halte ihn also serverseitig und aus allem heraus, was ein Browser lesen kann.

Der Request-Body

Jeder Endpunkt nimmt dieselben fünf Felder. Der Unterschied liegt im Inhaltsfeld darunter: Die meisten nehmen ein Array aus items, ein paar einen einzelnen Satz oder ein einzelnes Bild, und sudoku nimmt gar nichts.

FeldTypWas es macht
account_api_key
erforderlich
string
stringDer API-Schlüssel deines Kontos. Er gehört in den Body, nicht in einen Header.
email
erforderlich
string
stringDie Adresse, mit der sich dein Puzzel.org-Konto anmeldet. Der Schlüssel ist nur zusammen mit ihr gültig.
title
optional
string
stringDer Name, den die Aktivität in deinem Dashboard bekommt. Lässt du ihn weg, nimmt der Endpunkt seinen eigenen Ersatznamen.
language
optional
string
stringBestimmt nur die Sprache in der URL, die du zurückbekommst — es übersetzt nichts von dem, was du schickst. Das Wortsuchrätsel liest es außerdem, um seine Füllbuchstaben auf Arabisch umzustellen, wenn es "ar" ist.
Standard: "en"
activity_key
optional
string
stringLass es weg, um eine neue Aktivität zu erstellen. Gib den Schlüssel einer Aktivität an, die dir schon gehört, und diese wird stattdessen neu aufgebaut.

settings ist ein Objekt mit Optionen pro Endpunkt. Welche ein Endpunkt liest, steht unten bei ihm; alles andere, was du dort hineinschreibst, wird ignoriert.

Was zurückkommt

Ein erfolgreicher Aufruf antwortet mit 200, dem Schlüssel der neuen Aktivität und der URL, unter der sie gespielt wird. Alles andere antwortet mit success auf false und einem einzelnen error-String.

Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Fehler 
{
  "success": false,
  "error": "Invalid Email or API Key"
}

Die url, die du zurückbekommst, ist die Einbettungsansicht. Ersetz embed durch play, um sie als ganze Seite zu öffnen, oder durch build, um sie im Editor zu öffnen — der Schlüssel hinter p= bleibt gleich.

Erstellen vs. Aktualisieren

Schick activity_key mit und die Aktivität dahinter wird an Ort und Stelle neu aufgebaut: Ihr Inhalt wird ersetzt, ihr Name und ihr Versionsstempel werden aufgefrischt, und der Schlüssel selbst bleibt gleich — Links und Einbettungen, die du schon geteilt hast, funktionieren also weiter. Ergebnisse, die Ablage im Ordner und jede Einstellung, die der Endpunkt nicht selbst schreibt, bleiben, wie sie waren.

activity_key 
{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "activity_key": "-Nq8sample_activity_key",
  "title": "Fruit crossword, week 2",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}
  • title wird bei jeder Aktualisierung angewendet, sein Standard eingeschlossen — lässt du es weg, wird die Aktivität in den Ersatznamen dieses Endpunkts umbenannt.
  • Die Einstellungsblöcke, die ein Endpunkt selbst schreibt, werden von Grund auf neu geschrieben. Eine Aktualisierung setzt sie also ebenfalls auf die Werte, die du schickst, oder auf die Standardwerte des Endpunkts.
  • Du kannst nur Aktivitäten aktualisieren, die deinem eigenen Konto gehören. Der Schlüssel einer fremden Aktivität antwortet mit 403.
  • Eine Aktualisierung kostet genauso viel wie ein Erstellen: einen Aufruf vom heutigen Kontingent.

Rate-Limit

10
10 Aktivitäten pro Konto und Tag

Jeder erfolgreiche Aufruf zählt, erstellen wie aktualisieren. Gehst du darüber, antwortet die nächste Anfrage mit 429, bis der Zähler zurückgesetzt ist.

Der Zähler wird einmal am Tag von einem geplanten Job geleert, nicht in einem gleitenden 24-Stunden-Fenster.

Fehler

Fehler kommen immer als JSON mit denselben zwei Feldern, nie als HTML-Seite. Der error-String ist so geschrieben, dass ein Mensch ihn lesen kann — er nennt das Feld oder das Limit, an dem es gescheitert ist.

StatusWas es bedeutet
400
Bad Request
Im Body fehlt etwas, ist fehlerhaft oder außerhalb des zulässigen Bereichs. Die Meldung nennt das Feld.
401
Unauthorized
Die E-Mail-Adresse ist unbekannt oder der Schlüssel gehört nicht zu diesem Konto.
403
Forbidden
Der activity_key, den du geschickt hast, gehört zu einem anderen Konto.
429
Too Many Requests
Das heutige Kontingent ist aufgebraucht. Es wird einmal am Tag zurückgesetzt.
500
Server Error
Der Generator konnte aus dem, was du geschickt hast, kein Rätsel bauen — meist zu wenige Wörter oder Wörter, die sich nicht zusammenfügen lassen.

Endpunkte

Ein Pfad pro Aktivitätstyp, alle POST, alle unter derselben Basis-URL. Bei jedem stehen die Inhalte, die er braucht, die Einstellungen, die er liest, und eine Anfrage, die du ausführen kannst.

Wörter & Buchstaben

Kreuzworträtsel

Verzahnt deine Antworten zu einem Raster und nummeriert die Hinweise für dich.

#
POST /api/public/v1/crossword Mindestens 2 in items
Inhalt

Ein Array aus Wörtern. Jeder Eintrag verbindet die Antwort mit dem Hinweis, der auf sie zeigt.

Nutzt ersatzweise den Namen “Crossword API”

Gut zu wissen
  • Antworten mit weniger als zwei Zeichen fallen raus, bevor das Raster gebaut wird, und mindestens zwei müssen das überstehen.
  • Antworten werden in Großbuchstaben umgewandelt und der Generator hat zwanzig Versuche, sie unterzubringen. Kann er kein einziges Wort platzieren, antwortet der Aufruf mit 500.
Beispielanfrage
POST crossword 
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "de",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Editor öffnen Nach oben

Wortsuchrätsel

Versteckt deine Wörter in einem Buchstabenraster, in den Richtungen und der Form, die du wählst.

#
POST /api/public/v1/wordseeker Mindestens 2 in items
Inhalt

Ein Array aus Wörtern. Der Hinweistext wird zur Wortliste, mit der die Spieler arbeiten.

Nutzt ersatzweise den Namen “Wordseeker API”

Gut zu wissen
  • Antworten unter zwei Zeichen fallen raus, und jede Antwort wird in Großbuchstaben umgewandelt, bevor sie ins Raster kommt.
  • Das Raster wird mit lateinischen Buchstaben aufgefüllt, es sei denn, language ist "ar" — dann sind die Füllbuchstaben arabisch.
Einstellungen, die er liest
FeldTypWas es macht
hidden_solution
optional in den Einstellungen
string
stringDie übrigen Buchstaben ergeben diese Lösung. Setzt du sie, baut der Generator außerdem zuerst die Lösung ein, statt so viele Wörter wie möglich unterzubringen.
directions
optional in den Einstellungen
string[]
string[]In welche Richtungen ein Wort verlaufen darf. Lässt du es weg, verlaufen Wörter nur nach Osten, Südosten und Süden.
Eines von westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Standard: ["east", "southeast", "south"]
template
optional in den Einstellungen
string
stringSchneidet das Raster in eine Form, statt es quadratisch zu lassen.
Eines von squarecirclecrossdiamondpyramidsmileystarcross_plus
Beispielanfrage
POST wordseeker 
curl -X POST https://puzzel.org/api/public/v1/wordseeker \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordseeker",
  "language": "de",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT",
    "directions": [
      "east",
      "south",
      "southeast"
    ],
    "template": "square"
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Editor öffnen Nach oben

Akrostichon

Stapelt deine Antworten so, dass eine Spalte ein verstecktes Wort ergibt.

#
POST /api/public/v1/acrostic Mindestens 1 in items
Inhalt

Ein Array aus Wörtern. Zusammen müssen sie jeden Buchstaben des versteckten Wortes liefern.

Nutzt ersatzweise den Namen “Acrostic API”

Gut zu wissen
  • Können die Antworten die Buchstaben der Lösung nicht liefern, antwortet der Aufruf mit 500, statt ein halbfertiges Raster zu speichern.
  • Der Generator sortiert deine Antworten um, damit die Spalte aufgeht, die Reihenfolge, die du schickst, ist also nicht die, die Spieler sehen.
Einstellungen, die er liest
FeldTypWas es macht
hidden_solution
erforderlich in den Einstellungen
string
stringDas Wort, das die hervorgehobene Spalte ergibt. Ohne es läuft dieser Endpunkt nicht.
Beispielanfrage
POST acrostic 
curl -X POST https://puzzel.org/api/public/v1/acrostic \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Acrostic",
  "language": "de",
  "items": [
    {
      "answer": "PEACH",
      "description": "Fuzzy skin, sweet flesh",
      "type": "text"
    },
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "PLUM"
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Editor öffnen Nach oben

Buchstabensalat

api_e_word_scramble

#
POST /api/public/v1/word-scramble Mindestens 1 in items
Inhalt

api_c_word_scramble

Nutzt ersatzweise den Namen “Word Scramble API”

Gut zu wissen
  • Über die API erstellte Aktivitäten haben die Einstellung zum Mischen der Reihenfolge immer an, die Reihenfolge, die du schickst, ist also nicht die, die Spieler bekommen.
Einstellungen, die er liest
FeldTypWas es macht
hidden_solution
optional in den Einstellungen
string
stringEin optionales Bonuswort, das Spieler eingeben, sobald der Rest gelöst ist.
Beispielanfrage
POST word-scramble 
curl -X POST https://puzzel.org/api/public/v1/word-scramble \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Word Scramble",
  "language": "de",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT"
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Editor öffnen Nach oben

Galgenmännchen

Macht aus deinen Wörtern oder Sätzen Runden zum Buchstabenraten.

#
POST /api/public/v1/hangman Mindestens 1 in items
Inhalt

Ein Array aus Wörtern oder kurzen Sätzen. Der Hinweis ist der Tipp, den Spieler sehen.

Nutzt ersatzweise den Namen “Hangman API”

Beispielanfrage
POST hangman 
curl -X POST https://puzzel.org/api/public/v1/hangman \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Hangman",
  "language": "de",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Editor öffnen Nach oben

Wordle

Macht aus jedem Wort, das du schickst, ein Ratespiel.

#
POST /api/public/v1/wordle Mindestens 1 in items
Inhalt

Ein Array aus Wörtern. Spieler bekommen eine Runde pro Wort.

Nutzt ersatzweise den Namen “Wordle API”

Gut zu wissen
  • Wird mit der Einstellung erstellt, die prüft, ob die geratenen Wörter echt sind. Schalte sie im Editor aus, wenn deine Wörter Namen oder erfunden sind.
Beispielanfrage
POST wordle 
curl -X POST https://puzzel.org/api/public/v1/wordle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordle",
  "language": "de",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Editor öffnen Nach oben

Tipptraining

api_e_typing_practice

#
POST /api/public/v1/typing-practice Mindestens 1 in items
Inhalt

api_c_typing_practice

Nutzt ersatzweise den Namen “Typing Practice API”

Beispielanfrage
POST typing-practice 
curl -X POST https://puzzel.org/api/public/v1/typing-practice \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Typing Practice",
  "language": "de",
  "items": [
    {
      "answer": "The quick brown fox jumps over the lazy dog",
      "description": "Every letter of the alphabet",
      "type": "text"
    },
    {
      "answer": "Pack my box with five dozen liquor jugs",
      "description": "Another pangram",
      "type": "text"
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}
Editor öffnen Nach oben

Glücksrad

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Mindestens 1 in items
Inhalt

api_c_wheel_of_fortune

Nutzt ersatzweise den Namen “Wheel of Fortune API”

Gut zu wissen
  • Wird mit “Ergebnis nur im Rad anzeigen” erstellt, das Ergebnis wird also am Rad abgelesen und nicht daneben angesagt.
Beispielanfrage
POST wheel-of-fortune 
curl -X POST https://puzzel.org/api/public/v1/wheel-of-fortune \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wheel of Fortune",
  "language": "de",
  "items": [
    {
      "answer": "Read a page aloud",
      "description": "Segment 1",
      "type": "text"
    },
    {
      "answer": "Name three fruits",
      "description": "Segment 2",
      "type": "text"
    },
    {
      "answer": "Spell it backwards",
      "description": "Segment 3",
      "type": "text"
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wheel-of-fortune/embed?p=-Nq8sample_activity_key",
  "message": "Wheel of Fortune created successfully"
}
Editor öffnen Nach oben
Karten & Paare

Memory

Verdeckte Karten, die umgedreht und zu Paaren zusammengeführt werden.

#
POST /api/public/v1/memory Mindestens 2 in items
Inhalt

Ein Array aus Paaren. Jedes Paar enthält die zwei Karten, die zusammengehören.

Nutzt ersatzweise den Namen “Memory Game API”

Gut zu wissen
  • Eine Karte ist ein Objekt mit type und value. Nimm "text" für Wörter oder "image", "audio", "youtube" bzw. "link" mit einer URL in value, und ergänze alt für eine Beschreibung.
Beispielanfrage
POST memory 
curl -X POST https://puzzel.org/api/public/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Memory Game",
  "language": "de",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Editor öffnen Nach oben

Zuordnungsspiel

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Mindestens 2 in items
Inhalt

api_c_matching_pairs

Nutzt ersatzweise den Namen “Matching Game API”

Gut zu wissen
  • Eine Karte ist ein Objekt mit type und value. Nimm "text" für Wörter oder "image", "audio", "youtube" bzw. "link" mit einer URL in value, und ergänze alt für eine Beschreibung.
Beispielanfrage
POST matching-pairs 
curl -X POST https://puzzel.org/api/public/v1/matching-pairs \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Matching Game",
  "language": "de",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Editor öffnen Nach oben

Lernkarten

api_e_flash_cards

#
POST /api/public/v1/flash-cards Mindestens 1 in items
Inhalt

api_c_flash_cards

Nutzt ersatzweise den Namen “Flash Cards API”

Gut zu wissen
  • Der Endpunkt speichert so viele Karten, wie du schickst, schick also genau zwei pro Eintrag — Vorderseite, dann Rückseite.
  • Eine Karte ist ein Objekt mit type und value. Nimm "text" für Wörter oder "image", "audio", "youtube" bzw. "link" mit einer URL in value, und ergänze alt für eine Beschreibung.
Beispielanfrage
POST flash-cards 
curl -X POST https://puzzel.org/api/public/v1/flash-cards \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Flash Cards",
  "language": "de",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Editor öffnen Nach oben

Sortierrätsel

Karten, die in die passende Kategorie sortiert werden.

#
POST /api/public/v1/categorize Mindestens 2 in items
Inhalt

Ein Array aus Kategorien, jede mit einem Namen und den Karten, die dazugehören.

Nutzt ersatzweise den Namen “Categorize Game API”

Gut zu wissen
  • Eine Kategorie ohne Namen wird als “Untitled Category” gespeichert, schick also immer einen.
  • Eine Karte ist ein Objekt mit type und value. Nimm "text" für Wörter oder "image", "audio", "youtube" bzw. "link" mit einer URL in value, und ergänze alt für eine Beschreibung.
Beispielanfrage
POST categorize 
curl -X POST https://puzzel.org/api/public/v1/categorize \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Categorize Game",
  "language": "de",
  "items": [
    {
      "name": "Red fruits",
      "cards": [
        {
          "type": "text",
          "value": "Strawberry"
        },
        {
          "type": "text",
          "value": "Cherry"
        }
      ]
    },
    {
      "name": "Yellow fruits",
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "Lemon"
        }
      ]
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Editor öffnen Nach oben

Reihenfolgerätsel

Eine Reihenfolge, die Spieler wiederherstellen müssen.

#
POST /api/public/v1/reorder Mindestens 1 in items
Inhalt

Ein Array aus Reihenfolgen. Jede enthält ihre Karten in der richtigen Reihenfolge.

Nutzt ersatzweise den Namen “Reorder Game API”

Gut zu wissen
  • Die Reihenfolge, die du schickst, wird als die richtige gespeichert — Nummer eins zuerst.
  • Eine Karte ist ein Objekt mit type und value. Nimm "text" für Wörter oder "image", "audio", "youtube" bzw. "link" mit einer URL in value, und ergänze alt für eine Beschreibung.
Beispielanfrage
POST reorder 
curl -X POST https://puzzel.org/api/public/v1/reorder \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Reorder Game",
  "language": "de",
  "items": [
    {
      "name": "From seed to fruit",
      "cards": [
        {
          "type": "text",
          "value": "Plant the seed"
        },
        {
          "type": "text",
          "value": "Water it"
        },
        {
          "type": "text",
          "value": "Watch it grow"
        },
        {
          "type": "text",
          "value": "Pick the fruit"
        }
      ]
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Editor öffnen Nach oben
Fragen & Antworten

Quiz

Multiple-Choice-Fragen und offene Fragen, die beim Spielen direkt bewertet werden.

#
POST /api/public/v1/quiz Mindestens 1 in items
Inhalt

Ein Array aus Fragen. Multiple-Choice-Fragen bringen ihre Antworten mit, offene Fragen die Antwort, die du gelten lässt.

Nutzt ersatzweise den Namen “Quiz API”

Gut zu wissen
  • question_type ist entweder "multiple_choice", wobei die richtige Option isCorrect true trägt, oder "open_answer", das stattdessen correct_answer verwendet. Fehlt es, wird es als Multiple Choice behandelt.
  • Der quiz-Endpunkt reicht settings direkt als Einstellungsblöcke der Aktivität durch, es ist also kein Ort für lose Optionen — pass das Quiz danach im Editor an.
Beispielanfrage
POST quiz 
curl -X POST https://puzzel.org/api/public/v1/quiz \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Quiz",
  "language": "de",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ]
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Editor öffnen Nach oben

Brettspiel

api_e_board_game

#
POST /api/public/v1/board-game Mindestens 1 in items
Inhalt

api_c_board_game

Nutzt ersatzweise den Namen “Board Game API”

Gut zu wissen
  • question_type ist entweder "multiple_choice", wobei die richtige Option isCorrect true trägt, oder "open_answer", das stattdessen correct_answer verwendet. Fehlt es, wird es als Multiple Choice behandelt.
Einstellungen, die er liest
FeldTypWas es macht
number_of_tiles
optional in den Einstellungen
number
numberWie viele Felder das Brett hat. Zwischen 10 und 75.
Standard: 30
game_mode
optional in den Einstellungen
string
stringOb Spieler zum Ziel rennen oder unterwegs Gegenstände sammeln.
Eines von race_to_finishcollect_items
Standard: "race_to_finish"
Beispielanfrage
POST board-game 
curl -X POST https://puzzel.org/api/public/v1/board-game \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Board Game",
  "language": "de",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ],
  "settings": {
    "number_of_tiles": 30,
    "game_mode": "race_to_finish"
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}
Editor öffnen Nach oben
Sätze & Zahlen

Kryptogramm

Macht aus einem Satz einen Code zum Knacken, Zeichen für Zeichen.

#
POST /api/public/v1/cryptogram Nimmt keine items
Inhalt

Ein Satz, im Feld sentence. Dieser Endpunkt nimmt keine items.

Nutzt ersatzweise den Namen “Cryptogram API”

Gut zu wissen
  • Alles, was du in items schickst, wird ignoriert — das Rätsel entsteht allein aus sentence.
Einstellungen, die er liest
FeldTypWas es macht
sentence
erforderlich
string
stringDer Satz, der verschlüsselt wird. Spieler entschlüsseln ihn Zeichen für Zeichen.
helpers
optional in den Einstellungen
string
stringWelche Zeichen als Einstieg von vornherein verraten werden: keine, die häufigsten, die Vokale oder die, die du selbst angibst.
Eines von nonemost_commonvowelscustom
Standard: "none"
character_list
optional in den Einstellungen
string
stringDas Alphabet, aus dem die Verschlüsselung gebaut wird. Bleibt es leer, wählt die Verschlüsselung ihr eigenes.
extra_letters
optional in den Einstellungen
string
stringDie Zeichen, die verraten werden, wenn helpers auf "custom" steht. Bei den anderen Hilfe-Modi wird es ignoriert.
hide_unused_characters
optional in den Einstellungen
boolean
booleanLässt Zeichen, die im Satz nie vorkommen, aus der Legende weg.
Standard: false
Beispielanfrage
POST cryptogram 
curl -X POST https://puzzel.org/api/public/v1/cryptogram \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Cryptogram",
  "language": "de",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Editor öffnen Nach oben

Rechenrätsel

Versteckt einen Satz hinter Rechenaufgaben — löse die Aufgabe, deck den Buchstaben auf.

#
POST /api/public/v1/calculation Nimmt keine items
Inhalt

Ein Satz, im Feld sentence. Dieser Endpunkt nimmt keine items.

Nutzt ersatzweise den Namen “Calculation Game API”

Gut zu wissen
  • Sind die Vorgaben zu eng, um den Satz zu verschlüsseln, antwortet der Aufruf mit 400 und bittet dich, sie zu lockern, statt ein halbes Rätsel zu speichern.
Einstellungen, die er liest
FeldTypWas es macht
sentence
erforderlich
string
stringDer Satz, den Spieler aufdecken, indem sie die Rechenaufgaben lösen.
difficulty_level
optional in den Einstellungen
number
numberDas höchste Ergebnis, das eine Rechenaufgabe haben darf.
Eines von 20501001000
Standard: "100"
operators
optional in den Einstellungen
string[]
string[]Welche Rechenarten vorkommen dürfen. x ist mal, : ist geteilt.
Eines von +-x:
Standard: ["+", "-", "x", ":"]
max_operations
optional in den Einstellungen
number
numberWie viele Rechenschritte eine Aufgabe aneinanderreihen darf.
Eines von 123
Standard: 1
number_difficulty
optional in den Einstellungen
number
numberBegrenzt die einzelnen Zahlen in einer Aufgabe. Von 5 bis 1000.
Standard: 100
Beispielanfrage
POST calculation 
curl -X POST https://puzzel.org/api/public/v1/calculation \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Calculation Game",
  "language": "de",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Editor öffnen Nach oben

Sudoku

Erzeugt ein gelöstes Raster und nimmt dann wieder Zahlen heraus.

#
POST /api/public/v1/sudoku Nimmt keine items
Inhalt

Nichts. Das ganze Rätsel entsteht aus seinen zwei Einstellungen.

Nutzt ersatzweise den Namen “Sudoku API”

Gut zu wissen
  • Schick keine items und kein sentence — size und difficulty sind die gesamte Eingabe.
  • Der Editor bietet die Schwierigkeit nur für 2x3, 3x3 und 3x4 an. Die API wendet sie auf jede Größe an, 2x2 und 4x4 eingeschlossen.
Einstellungen, die er liest
FeldTypWas es macht
size
optional in den Einstellungen
string
stringDie Größe eines Blocks, geschrieben als Zeilen mal Spalten — 3x3 ergibt das klassische 9x9-Raster. Der Endpunkt prüft nur, ob sich das als zwei Zahlen lesen lässt, bleib also bei den Größen, die der Editor anbietet.
Eines von 2x22x33x33x44x4
Standard: "3x3"
difficulty_level
optional in den Einstellungen
string
stringWie viele Zahlen zu Beginn im Raster stehen bleiben.
Eines von easynormalhard
Standard: "normal"
Beispielanfrage
POST sudoku 
curl -X POST https://puzzel.org/api/public/v1/sudoku \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sudoku",
  "language": "de",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Editor öffnen Nach oben
Bilder

Puzzle

Zerschneidet ein Bild in Teile, die wieder zusammengezogen werden.

#
POST /api/public/v1/jigsaw Nimmt keine items
Inhalt

Eine Bild-URL, im Feld image. Dieser Endpunkt nimmt keine items.

Nutzt ersatzweise den Namen “Jigsaw Game API”

Gut zu wissen
  • Die API erstellt immer ein Puzzle mit 4 mal 4 Teilen. Teilezahl, unregelmäßige Teile und glatte Ränder sind Einstellungen im Editor — rows oder columns hierher zu schicken bewirkt nichts.
  • Die URL wird so gespeichert, wie du sie geschickt hast, und die Datei wird nie kopiert. Sie muss also öffentlich erreichbar bleiben, solange die Aktivität gespielt wird.
Einstellungen, die er liest
FeldTypWas es macht
image
erforderlich
string
stringAbsolute URL des Bildes, das zerschnitten wird. Wird auf oberster Ebene geschickt, nicht in settings.
Beispielanfrage
POST jigsaw 
curl -X POST https://puzzel.org/api/public/v1/jigsaw \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Jigsaw Game",
  "language": "de",
  "image": "https://example.com/orchard.jpg"
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Editor öffnen Nach oben

Schiebepuzzle

Zerlegt ein Bild in Kacheln, die an ihren Platz geschoben werden.

#
POST /api/public/v1/slidingpuzzle Nimmt keine items
Inhalt

Eine Bild-URL, in settings. Dieser Endpunkt nimmt keine items.

Nutzt ersatzweise den Namen “Sliding Puzzle API”

Gut zu wissen
  • Anders als beim Puzzle liest dieser Endpunkt sein Bild aus settings.image. Ein image-Feld auf oberster Ebene wird ignoriert und der Aufruf antwortet mit 400.
  • Die URL wird so gespeichert, wie du sie geschickt hast, und die Datei wird nie kopiert. Sie muss also öffentlich erreichbar bleiben, solange die Aktivität gespielt wird.
Einstellungen, die er liest
FeldTypWas es macht
image
erforderlich in den Einstellungen
string
stringAbsolute URL des Bildes, das zerlegt wird. Anders als beim Puzzle steht es hier in settings.
Beispielanfrage
POST slidingpuzzle 
curl -X POST https://puzzel.org/api/public/v1/slidingpuzzle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sliding Puzzle",
  "language": "de",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Erfolg 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Editor öffnen Nach oben

Etwas macht nicht, was es soll?

Schick die Anfrage, die du versucht hast, und den Fehler, den du zurückbekommen hast, und du bekommst eine echte Antwort, von der Person, die den Endpunkt geschrieben hat.

Support per E-Mail