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: 38 Aktivitätstypen
Kontingent: 10 Aktivitäten pro Tag

Deine erste Anfrage

Du musst nichts installieren. Sende eine POST-Anfrage mit deinem API-Schlüssel, deiner E-Mail-Adresse und deinen Inhalten als JSON-Body. Die Antwort enthält den Schlüssel der neuen Aktivität und ihre Spiel-URL.

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

Du brauchst keinen Authentifizierungs-Header und kein Bearer-Token. API-Schlüssel und E-Mail-Adresse stehen im JSON-Body jeder Anfrage. Der Schlüssel muss zu dem Konto mit dieser E-Mail-Adresse gehören.

Feld	Typ	Was es macht
`account_api_key` erforderlich string	string	Der API-Schlüssel deines Kontos. Er gehört in den Body, nicht in einen Header.
`email` erforderlich string	string	Die 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

Alle Endpunkte verwenden dieselben fünf gemeinsamen Felder. Die zusätzlichen Inhaltsfelder unterscheiden sich je nach Aktivität: meist ein Array mit Einträgen, manchmal ein einzelner Satz oder ein Bild. Für Sudoku brauchst du keine Inhalte mitzusenden.

Feld	Typ	Was es macht
`account_api_key` erforderlich string	string	Der API-Schlüssel deines Kontos. Er gehört in den Body, nicht in einen Header.
`email` erforderlich string	string	Die Adresse, mit der sich dein Puzzel.org-Konto anmeldet. Der Schlüssel ist nur zusammen mit ihr gültig.
`title` optional string	string	Der Name, den die Aktivität in deinem Dashboard bekommt. Lässt du ihn weg, nimmt der Endpunkt seinen eigenen Ersatznamen.
`language` optional string	string	Bestimmt 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	string	Lass 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

Wenn du activity_key mitsendest, wird die bestehende Aktivität aktualisiert: Ihr Inhalt wird ersetzt, Name und Versionsstempel werden aktualisiert. Der Schlüssel bleibt gleich, sodass bereits geteilte Links und Einbettungen weiter funktionieren. Ergebnisse, die Zuordnung zu einem Ordner und Einstellungen, die der Endpunkt nicht überschreibt, bleiben erhalten.

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 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.

Status	Was 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 2 bis 80 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.

Einstellungen, die er liest

Feld	Typ	Was es macht
`hidden_solution` optional in den Einstellungen string	string	Ein optionales Bonuswort. Seine Buchstaben werden in Feldern des fertigen Rasters markiert, damit die Spieler sie einsammeln, sobald das Kreuzworträtsel gelöst ist. Jeder Buchstabe davon muss also in den Antworten vorkommen.

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"
}

Feld	Typ	Was es macht
`hidden_solution` optional in den Einstellungen string	string	Die ü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	string	Schneidet das Raster in eine Form, statt es quadratisch zu lassen. Eines von `squarecirclecrossdiamondpyramidsmileystarcross_plus`

Feld	Typ	Was es macht
`theme` optional in den Einstellungen string	string	Das Rätsel, das über dem Raster steht. Lässt du es weg, sehen die Spieler den Titel.
`spangram` optional in den Einstellungen string	string	Das Wort oder die Wortgruppe, die das Thema benennt und das Spielfeld von einem Rand zum anderen durchquert.

Feld	Typ	Was es macht
`list_match_mode` optional in den Einstellungen string	string	Ob ein Name zählt, sobald er getippt ist, oder erst mit Enter. Eines von `while_typingon_enter` Standard: "while_typing"
`list_slot_hint` optional in den Einstellungen string	string	Was ein leerer Platz verrät: nichts, die Länge des Namens, seinen ersten Buchstaben oder den Tipp, den du geschrieben hast. Eines von `nonelengthfirst_letterhint` Standard: "none"
`list_arrange` optional in den Einstellungen string	string	Eine Spalte pro Gruppe oder eine einzige Liste. Eines von `groupsone_list` Standard: "groups"
`list_allow_give_up` optional in den Einstellungen boolean	boolean	Zeigt eine Schaltfläche zum Aufgeben, die den Durchgang beendet und zeigt, was gefehlt hat. Standard: false

Feld	Typ	Was es macht
`mode` optional in den Einstellungen string	string	Was die Felder füllt: deine Einträge, deine Einträge, aufgerufen über ihren Hinweis, oder reine Zahlen (die keine items brauchen). Eines von `itemscluesnumbers` Standard: "items"
`rows` optional in den Einstellungen number	number	Zeilen pro Karte, 2 bis 5. Standard: 3
`columns` optional in den Einstellungen number	number	Spalten pro Karte, 2 bis 5. Standard: 3
`highest_number` optional in den Einstellungen number	number	Im Modus "numbers" werden die Karten mit Zahlen von 1 bis zu dieser Zahl gefüllt, höchstens 100. Gibt es nur mit einem Tarif: ohne bleibt es bei 50. Standard: 50

Feld	Typ	Was es macht
`instructions` optional in den Einstellungen string	string	Die Frage oder das Rätsel, auf das der Code die Antwort ist, angezeigt zusammen mit den Karten.
`force_solution_in_correct_order` optional in den Einstellungen boolean	boolean	Die Karten müssen der Reihe nach gedrückt werden. Ausgeschaltet öffnet jede Reihenfolge der richtigen Karten das Schloss. Standard: false
`randomize_order` optional in den Einstellungen boolean	boolean	Jeder Spieler bekommt die Karten in einer gemischten Anordnung. Standard: true

Feld	Typ	Was es macht
`number_of_tiles` optional in den Einstellungen number	number	Wie viele Felder das Brett hat. Zwischen 10 und 75. Standard: 30
`game_mode` optional in den Einstellungen string	string	Ob Spieler zum Ziel rennen oder unterwegs Gegenstände sammeln. Eines von `race_to_finishcollect_items` Standard: "race_to_finish"

Feld	Typ	Was es macht
`maze_width` optional in den Einstellungen string	string	Wie die Kammern angeordnet sind: eine Spalte, ein Quadrat oder breiter. Eines von `narrownormalwide` Standard: "normal"
`maze_corridors` optional in den Einstellungen string	string	Wie viel Labyrinth zwischen zwei Fragen liegt. Eines von `shortnormallong` Standard: "normal"
`maze_fog` optional in den Einstellungen string	string	Das ganze Labyrinth zeigen oder nur die Stellen, an denen der Spieler schon vorbeigekommen ist. Eines von `offnear` Standard: "off"
`maze_wrong_door_pause` optional in den Einstellungen string	string	Wie lange die Türen nach einer falschen verschlossen bleiben. Eines von `noneshortlong` Standard: "short"
`maze_walk_there` optional in den Einstellungen boolean	boolean	Bietet eine Schaltfläche, die die Spielfigur zur nächsten Kammer laufen lässt. Standard: false
`maze_seed` optional in den Einstellungen string	string	Der Startwert, aus dem das Labyrinth erzeugt wird. Derselbe Startwert und dieselben Fragen ergeben dasselbe Labyrinth; lässt du ihn weg, wird ein neuer gezogen.

Feld	Typ	Was es macht
`jeopardy_buzzer_mode` optional in den Einstellungen string	string	Wer wie spielt: Du steuerst es von der Konsole aus, die Spieler melden sich per Handy, oder jeder Spieler spielt das Board allein. Eines von `hostphonessolo` Standard: "host"
`jeopardy_contestants` optional in den Einstellungen string	string	Ob die Konsole von Teams oder von Spielern spricht. Eines von `teamsplayers` Standard: "teams"
`jeopardy_value_step` optional in den Einstellungen number	number	Was eine Zeile wert ist: Ein Hinweis ist so viel wert wie dieser Wert mal seine Zeilennummer. Von 50 bis 500, in Schritten von 50. Standard: 100
`jeopardy_answer_time` optional in den Einstellungen number	number	Sekunden zum Antworten, sobald ein Hinweis geöffnet ist, höchstens 300. 0 bedeutet keine Uhr. Standard: 20
`jeopardy_wrong_answer_costs` optional in den Einstellungen boolean	boolean	Eine falsche Antwort zieht den Wert des Hinweises von der Punktzahl ab. Standard: false
`jeopardy_reveal_on_timeout` optional in den Einstellungen boolean	boolean	Das Board zeigt die Antwort selbst, wenn die Zeit abläuft. Standard: false
`jeopardy_require_question_form` optional in den Einstellungen boolean	boolean	Erinnert die Spieler daran, in der Form einer Frage zu antworten. Standard: false

Feld	Typ	Was es macht
`video_url` erforderlich in den Einstellungen string	string	Das Video: eine YouTube-, Vimeo- oder Bunny-Stream-Seite oder ein direkter Link zu einer mp4-, webm- oder mov-Datei.
`video_duration` optional in den Einstellungen number	number	Die Länge des Videos in Sekunden. Ist sie angegeben, wird ein Pop-up hinter dem Ende abgelehnt.

Feld	Typ	Was es macht
`sentence` erforderlich string	string	Der Satz, der verschlüsselt wird. Spieler entschlüsseln ihn Zeichen für Zeichen.
`helpers` optional in den Einstellungen string	string	Welche 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	string	Das 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	string	Die 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	boolean	Lässt Zeichen, die im Satz nie vorkommen, aus der Legende weg. Standard: false

Feld	Typ	Was es macht
`sentence` erforderlich string	string	Der Satz, den Spieler aufdecken, indem sie die Rechenaufgaben lösen.
`difficulty_level` optional in den Einstellungen number	number	Das 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	number	Wie viele Rechenschritte eine Aufgabe aneinanderreihen darf. Eines von `123` Standard: 1
`number_difficulty` optional in den Einstellungen number	number	Begrenzt die einzelnen Zahlen in einer Aufgabe. Von 5 bis 1000. Standard: 100

Feld	Typ	Was es macht
`size` optional in den Einstellungen string	string	Die 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	string	Wie viele Zahlen zu Beginn im Raster stehen bleiben. Eines von `easynormalhard` Standard: "normal"

Feld	Typ	Was es macht
`sentence` erforderlich string	string	Der Satz, der versteckt werden soll: ein Zitat, ein Sprichwort, ein Kernsatz. Höchstens 120 Buchstaben und Ziffern.
`columns` optional in den Einstellungen number	number	Wie breit das Spielfeld ist, von 8 bis 18. Schmaler stapelt mehr Buchstaben in jede Spalte und ist schwerer. Standard: 14
`helpers` optional in den Einstellungen string	string	Welche Buchstaben als Einstieg im Raster stehen bleiben: keine, die häufigsten, die Vokale oder die, die du selbst angibst. Eines von `nonemost_commonvowelscustom` Standard: "none"
`extra_letters` optional in den Einstellungen string	string	Die Buchstaben, die verraten werden, wenn helpers auf "custom" steht.

Feld	Typ	Was es macht
`tables` optional in den Einstellungen number[]	number[]	Die Reihen, die geübt werden. Lässt du es weg, sind es 1 bis 10; mit einer 11 oder 12 wird das Raster 12 mal 12. Eines von `123456789101112`
`order` optional in den Einstellungen string	string	Ob die Zeilen und Spalten der Reihe nach oder gemischt laufen. Eines von `ascendingshuffled` Standard: "ascending"
`picture` optional in den Einstellungen string	string	Das Bild, das richtige Antworten ausmalen. Eines von `sailboatheartrockettreecatfishflowerhouse` Standard: "sailboat"
`players_choose_tables` optional in den Einstellungen boolean	boolean	Lässt jeden Spieler wählen, welche der Reihen er üben möchte. Standard: false
`fill_same_sums` optional in den Einstellungen boolean	boolean	Eine richtige Antwort füllt jedes Feld mit derselben Aufgabe. Standard: true

Feld	Typ	Was es macht
`story` optional in den Einstellungen string	string	Die Hintergrundgeschichte, die über den Hinweisen steht.
`difficulty` optional in den Einstellungen string	string	Welche Arten von Hinweisen der Generator verwenden darf. Eines von `easymediumhard` Standard: "easy"
`hints` optional in den Einstellungen boolean	boolean	Bietet eine Schaltfläche, die den nächsten Schritt zeigt. Standard: true
`auto_cross` optional in den Einstellungen boolean	boolean	Wer eine Zuordnung markiert, streicht den Rest ihrer Zeile und Spalte durch. Standard: true
`clue_mode` optional in den Einstellungen string	string	Wer die Hinweise schreibt, die die Spieler sehen: aus der Tabelle erzeugt, deine eigenen Sätze in free_clues oder keine. Eines von `generatedfreenone` Standard: "generated"
`free_clues` optional in den Einstellungen string[]	string[]	Deine eigenen Hinweissätze, angezeigt wie geschrieben, bei clue_mode "free". Nichts prüft sie.

Feld	Typ	Was es macht
`clue_mode` optional in den Einstellungen string	string	Regeln als Bilder oder als Sätze anzeigen. Eines von `visualtext` Standard: "visual"
`unique_object_picks` optional in den Einstellungen boolean	boolean	Jede Form darf nur einmal platziert werden. Standard: false
`hide_color_picker` optional in den Einstellungen boolean	boolean	Die Spieler können Formen nicht umfärben. Standard: false

Erstelle Aktivitäten aus deinem eigenen System

Deine erste Anfrage

Authentifizierung

Der Request-Body

Was zurückkommt

Erstellen vs. Aktualisieren

Rate-Limit

Fehler

Endpunkte

Etwas macht nicht, was es soll?