Jeden POST na typ aktywności. Wyślij swoją treść jako JSON, a w zamian dostaniesz aktywność na koncie Puzzel.org i adres URL, który przekażesz graczom albo wstawisz do iframe.
Bazowy URL
https://puzzel.org/api/public/v1
Uwierzytelnianie
Klucz + e-mail w treści żądania
Endpointy
38 typów aktywności
Limit
10 aktywności dziennie
Twoje pierwsze żądanie
Nic nie instalujesz i nie ma żadnej wstępnej wymiany tokenów: wyślij metodą POST treść JSON ze swoim kluczem, adresem e-mail i zawartością. W odpowiedzi wracają klucz nowej aktywności i adres URL, pod którym się w nią gra.
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": "pl",
"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"
}
]
}'
Każdy przykład na tej stronie to kompletne, gotowe do uruchomienia żądanie. Podstaw własny klucz i własną treść, a zadziała bez żadnych zmian.
Uwierzytelnianie
Nie ma żadnych nagłówków ani tokenu bearer. Oba dane uwierzytelniające jadą w treści JSON każdego żądania, a klucz jest akceptowany tylko dla konta, do którego należy ten adres e-mail.
Pole
Typ
Do czego służy
account_api_key
wymagane
string
string
Klucz API twojego konta. Trafia do treści żądania, a nie do nagłówka.
email
wymagane
string
string
Adres, którym logujesz się na swoje konto Puzzel.org. Klucz jest ważny tylko razem z nim.
Twój klucz znajdziesz w sekcji konta w panelu, pod przyciskiem Pokaż.
Traktuj klucz jak hasło. Tworzy i nadpisuje aktywności na twoim koncie, więc trzymaj go po stronie serwera, z dala od wszystkiego, co może odczytać przeglądarka.
Treść żądania
Każdy endpoint przyjmuje te same pięć pól. Różni się tylko pole z zawartością pod nimi: większość przyjmuje tablicę items, kilka jedno zdanie albo jeden obraz, a sudoku nie przyjmuje niczego.
Pole
Typ
Do czego służy
account_api_key
wymagane
string
string
Klucz API twojego konta. Trafia do treści żądania, a nie do nagłówka.
email
wymagane
string
string
Adres, którym logujesz się na swoje konto Puzzel.org. Klucz jest ważny tylko razem z nim.
title
opcjonalne
string
string
Nazwa, jaką aktywność dostanie w twoim panelu. Pomiń je, a endpoint użyje własnej nazwy zapasowej.
language
opcjonalne
string
string
Decyduje tylko o języku w zwracanym adresie URL — nie tłumaczy niczego, co wysyłasz. Wykreślanka dodatkowo z niego korzysta, by przełączyć litery wypełniające na arabskie, gdy ma wartość "ar".
Domyślnie: "en"
activity_key
opcjonalne
string
string
Pomiń je, aby utworzyć nową aktywność. Podaj klucz aktywności, którą już masz, a zostanie ona przebudowana.
settings to obiekt z opcjami danego endpointu. Które z nich endpoint odczytuje, wypisane jest przy nim niżej; wszystko inne, co tam umieścisz, jest ignorowane.
Co wraca w odpowiedzi
Udane wywołanie odpowiada kodem 200 z kluczem nowej aktywności i adresem URL, pod którym się w nią gra. Wszystko inne odpowiada polem success ustawionym na false i jednym tekstem błędu.
{
"success": false,
"error": "Invalid Email or API Key"
}
Zwracany url to widok osadzony. Zamień embed na play, aby otworzyć go na całej stronie, albo na build, aby otworzyć go w edytorze — klucz po p= pozostaje ten sam.
Tworzenie a aktualizacja
Wyślij activity_key, a stojąca za nim aktywność zostanie przebudowana na miejscu: jej zawartość jest zastępowana, nazwa i znacznik wersji odświeżane, a sam klucz pozostaje ten sam — więc udostępnione już linki i osadzenia działają dalej. Wyniki, umieszczenie w folderze i wszystkie ustawienia, których endpoint sam nie zapisuje, zostają bez zmian.
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 jest stosowane przy każdej aktualizacji, razem z wartością domyślną — pomiń je, a aktywność zostanie przemianowana na nazwę zapasową tego endpointu.
Bloki ustawień, które endpoint zapisuje sam, są pisane od zera, więc aktualizacja resetuje je do wartości, które wyślesz, albo do wartości domyślnych endpointu.
Aktualizować możesz tylko aktywności należące do twojego konta. Cudzy klucz kończy się odpowiedzią 403.
Aktualizacja kosztuje tyle samo co utworzenie: jedno wywołanie z dziennego limitu.
Limit żądań
10
10 aktywności na konto dziennie
Liczy się każde udane wywołanie, zarówno tworzenie, jak i aktualizacja. Po przekroczeniu limitu kolejne żądanie odpowiada kodem 429, dopóki licznik nie zostanie wyzerowany.
Licznik jest zerowany raz dziennie przez zaplanowane zadanie, a nie w ruchomym oknie 24 godzin.
Błędy
Błędy zawsze przychodzą jako JSON z tymi samymi dwoma polami, nigdy jako strona HTML. Tekst błędu jest napisany tak, by przeczytał go człowiek — nazywa pole albo limit, na którym coś się wysypało.
Status
Co oznacza
400
Bad Request
Czegoś w treści żądania brakuje, coś jest źle zbudowane albo poza zakresem. Komunikat wskazuje pole.
401
Unauthorized
Adres e-mail jest nieznany albo klucz nie należy do tego konta.
403
Forbidden
Wysłany activity_key należy do innego konta.
429
Too Many Requests
Dzisiejszy limit został wyczerpany. Zeruje się raz dziennie.
500
Server Error
Generator nie zdołał zbudować łamigłówki z tego, co wysłano — zwykle za mało słów albo słowa, których nie da się ze sobą dopasować.
Endpointy
Jedna ścieżka na typ aktywności, wszystkie POST, wszystkie pod tym samym bazowym URL. Przy każdej wypisana jest treść, której potrzebuje, ustawienia, które odczytuje, i żądanie, które możesz uruchomić.
Słowa i litery
K
O
T
T
T
O
R
T
Ś
Krzyżówka
Splata twoje odpowiedzi w siatkę i sam numeruje definicje.
POST/api/public/v1/crosswordOd 2 do 80 elementów w items
Treść
Tablica słów. Każdy wpis łączy odpowiedź z definicją, która na nią wskazuje.
W razie braku używa nazwy “Crossword API”
Warto wiedzieć
Odpowiedzi krótsze niż dwa znaki są odrzucane przed zbudowaniem siatki i co najmniej dwie muszą to przetrwać.
Odpowiedzi są zamieniane na wielkie litery, a generator ma dwadzieścia prób, żeby je dopasować. Jeśli nie zdoła umieścić ani jednego słowa, wywołanie odpowiada kodem 500.
Odczytywane ustawienia
Pole
Typ
Do czego służy
hidden_solution
opcjonalnew settings
string
string
Opcjonalne słowo bonusowe. Jego litery są zaznaczone w kratkach gotowej siatki, a gracze zbierają je po rozwiązaniu krzyżówki, więc każda jego litera musi pojawić się w odpowiedziach.
Przykładowe żądanie
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": "pl",
"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"
}
]
}'
POST/api/public/v1/wordseekerOd 2 do 40 elementów w items
Treść
Tablica słów. Tekst definicji staje się listą słów, z której korzystają gracze.
W razie braku używa nazwy “Wordseeker API”
Warto wiedzieć
Odpowiedzi krótsze niż dwa znaki są odrzucane, a każda odpowiedź trafia do siatki zamieniona na wielkie litery.
Siatka jest wypełniana literami łacińskimi, chyba że language ma wartość "ar" — wtedy litery wypełniające przełączają się na arabskie.
Odczytywane ustawienia
Pole
Typ
Do czego służy
hidden_solution
opcjonalnew settings
string
string
Pozostałe litery układają się w to rozwiązanie. Ustawienie go mówi też generatorowi, żeby najpierw dopasował rozwiązanie, zamiast upchnąć jak najwięcej słów.
directions
opcjonalnew settings
string[]
string[]
W których kierunkach może biec słowo. Pomiń je, a słowa pobiegną tylko na wschód, na południowy wschód i na południe.
Jedna z wartościwesteastnorthsouthnorthwestnortheastsouthwestsoutheast
Domyślnie: ["east", "southeast", "south"]
template
opcjonalnew settings
string
string
Wycina siatkę w kształt, zamiast zostawiać ją kwadratową.
Jedna z wartościsquarecirclecrossdiamondpyramidsmileystarcross_plus
Przykładowe żądanie
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": "pl",
"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"
}
}'
POST/api/public/v1/wordleOd 1 do 50 elementów w items
Treść
Tablica słów. Gracze dostają jedną rundę na każde słowo.
W razie braku używa nazwy “Wordle API”
Warto wiedzieć
Tworzone z włączonym sprawdzaniem, czy zgadywane słowa naprawdę istnieją. Wyłącz je w edytorze, jeśli twoje słowa to nazwy własne albo wyrazy wymyślone.
POST/api/public/v1/typing-practiceOd 1 do 50 elementów w items
Treść
api_c_typing_practice
W razie braku używa nazwy “Typing Practice API”
Przykładowe żądanie
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": "pl",
"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"
}
]
}'
Sukces
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
"message": "Typing Practice created successfully"
}
POST/api/public/v1/strandsOd 2 do 24 elementów w items
Treść
Tablica słów tematycznych. Razem ze spangramem ich litery muszą dokładnie wypełnić planszę.
W razie braku używa nazwy “Strands API”
Warto wiedzieć
Litery wszystkich słów i spangramu razem muszą dać dokładnie 30, 35, 36, 40, 42, 45, 48, 49, 50, 54, 56, 60, 63, 64, 70, 72 albo 80. Każda inna liczba kończy się odpowiedzią 400 i mówi, ile liter dodać lub usunąć.
Odczytywane ustawienia
Pole
Typ
Do czego służy
theme
opcjonalnew settings
string
string
Zagadka pokazywana nad siatką. Pominięta: gracze widzą tytuł.
spangram
opcjonalnew settings
string
string
Słowo lub fraza, która nazywa temat i przecina planszę od jednej krawędzi do drugiej.
POST/api/public/v1/name-them-allOd 1 do 250 elementów w items
Treść
api_c_name_them_all
W razie braku używa nazwy “Name Them All API”
Warto wiedzieć
Wpis to obiekt z polem answer i opcjonalnie aliases (inne pisownie, które się liczą), description (podpowiedź) oraz group. Przy sprawdzaniu nazwy wielkość liter, akcenty i interpunkcja są ignorowane.
Odczytywane ustawienia
Pole
Typ
Do czego służy
list_match_mode
opcjonalnew settings
string
string
Czy nazwa liczy się w chwili wpisania, czy dopiero po naciśnięciu Enter.
Jedna z wartościwhile_typingon_enter
Domyślnie: "while_typing"
list_slot_hint
opcjonalnew settings
string
string
Co zdradza puste pole: nic, długość nazwy, jej pierwszą literę albo podpowiedź, którą napiszesz.
Jedna z wartościnonelengthfirst_letterhint
Domyślnie: "none"
list_arrange
opcjonalnew settings
string
string
Jedna kolumna na grupę albo jedna lista.
Jedna z wartościgroupsone_list
Domyślnie: "groups"
list_allow_give_up
opcjonalnew settings
boolean
boolean
Pokazuje przycisk poddania się, który kończy rundę i odsłania to, czego zabrakło.
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/name-them-all/embed?p=-Nq8sample_activity_key",
"message": "Name them all list created successfully"
}
Tablica elementów, z których losowane są karty. Wyślij wyraźnie więcej elementów, niż ma kratek jedna karta, żeby karty się różniły.
W razie braku używa nazwy “Bingo API”
Warto wiedzieć
Element to obiekt z polem value i opcjonalnie type ("text", "image" albo "audio" z adresem URL w value), description (wskazówka, którą prowadzący odczytuje w trybie clues) oraz alt.
Odczytywane ustawienia
Pole
Typ
Do czego służy
mode
opcjonalnew settings
string
string
Co wypełnia kratki: twoje elementy, twoje elementy wywoływane po wskazówce albo zwykłe liczby (nie potrzebują items).
Jedna z wartościitemscluesnumbers
Domyślnie: "items"
rows
opcjonalnew settings
number
number
Wiersze na każdej karcie, od 2 do 5.
Domyślnie: 3
columns
opcjonalnew settings
number
number
Kolumny na każdej karcie, od 2 do 5.
Domyślnie: 3
highest_number
opcjonalnew settings
number
number
W trybie numbers karty są wypełniane liczbami od 1 do tej liczby, najwyżej 100. Funkcja planu: bez planu zostaje 50.
Domyślnie: 50
Przykładowe żądanie
POST bingo
curl -X POST https://puzzel.org/api/public/v1/bingo \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Bingo",
"language": "pl",
"items": [
{
"type": "text",
"value": "Paris",
"description": "The capital of France"
},
{
"type": "text",
"value": "Berlin",
"description": "The capital of Germany"
},
{
"type": "text",
"value": "Madrid",
"description": "The capital of Spain"
}
],
"settings": {
"mode": "clues",
"rows": 3,
"columns": 4,
"highest_number": 75
}
}'
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/i-have-who-has/embed?p=-Nq8sample_activity_key",
"message": "I have, who has created successfully"
}
POST/api/public/v1/keypadOd 1 do 30 elementów w items
Treść
Tablica kart. Karty wchodzące w skład kodu niosą swoje miejsce w nim.
W razie braku używa nazwy “Keypad API”
Warto wiedzieć
Karta to obiekt z polem value i opcjonalnie type ("text", "image" albo "audio" z adresem URL w value), alt oraz code_position: jej miejscem w kodzie, 1 to pierwsze. Karta może być w kodzie tylko raz i co najmniej jedna karta musi w nim być.
Odczytywane ustawienia
Pole
Typ
Do czego służy
instructions
opcjonalnew settings
string
string
Pytanie albo zagadka, na którą odpowiada kod, pokazywane razem z siatką kart.
force_solution_in_correct_order
opcjonalnew settings
boolean
boolean
Karty trzeba wybrać po kolei. Wyłączone: zamek otwiera dowolna kolejność właściwych kart.
Domyślnie: false
randomize_order
opcjonalnew settings
boolean
boolean
Każdy gracz dostaje karty w przetasowanym układzie.
POST/api/public/v1/quartetsOd 2 do 16 elementów w items
Treść
Tablica kwartetów. Każdy ma nazwę i dokładnie cztery karty.
W razie braku używa nazwy “Quartets API”
Warto wiedzieć
Karta to nazwa albo obiekt z polami name i description (fakt pokazany na karcie). Żadna nazwa karty nie może się w grze powtórzyć: gracze proszą o karty po nazwie.
Odczytywane ustawienia
Pole
Typ
Do czego służy
type
opcjonalnew settings
string
string
Zwykła gra albo gra edukacyjna, w której każda karta pokazuje fakt. Pominięte: learn, gdy jakakolwiek karta ma description.
Jedna z wartościnormallearn
Przykładowe żądanie
POST quartets
curl -X POST https://puzzel.org/api/public/v1/quartets \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Quartets",
"language": "pl",
"items": [
{
"name": "Birds",
"cards": [
{
"name": "Owl",
"description": "Hunts at night and turns its head three quarters of the way round."
},
{
"name": "Robin",
"description": "Sings through the winter."
},
{
"name": "Woodpecker",
"description": "Drums on trees up to twenty times a second."
},
{
"name": "Jay",
"description": "Buries thousands of acorns each autumn."
}
]
},
{
"name": "Mammals",
"cards": [
{
"name": "Hedgehog",
"description": "Carries about five thousand spines."
},
{
"name": "Fox",
"description": "Hears a mouse under the snow."
},
{
"name": "Badger",
"description": "Lives in a sett with its clan."
},
{
"name": "Otter",
"description": "Sleeps holding hands so it does not drift off."
}
]
}
],
"settings": {
"type": "learn"
}
}'
Sukces
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/quartets/embed?p=-Nq8sample_activity_key",
"message": "Quartets game created successfully"
}
POST/api/public/v1/quizOd 1 do 100 elementów w items
Treść
Tablica pytań. Pytania wielokrotnego wyboru niosą swoje odpowiedzi, pytania otwarte — odpowiedź, którą akceptujesz.
W razie braku używa nazwy “Quiz API”
Warto wiedzieć
question_type ma wartość "multiple_choice", gdzie poprawna opcja ma isCorrect true; "true_false", czyli to samo z dokładnie dwiema opcjami, pierwsza to prawda, druga to fałsz; albo "open_answer", który zamiast tego używa correct_answer. Jeśli go pominiesz, pytanie jest traktowane jak wielokrotny wybór.
Endpoint quizu przekazuje settings prosto jako bloki ustawień aktywności, więc nie jest to miejsce na luźne opcje — quiz dopracuj potem w edytorze.
Przykładowe żądanie
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": "pl",
"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."
}
]
}'
POST/api/public/v1/board-gameOd 1 do 100 elementów w items
Treść
api_c_board_game
W razie braku używa nazwy “Board Game API”
Warto wiedzieć
question_type ma wartość "multiple_choice", gdzie poprawna opcja ma isCorrect true; "true_false", czyli to samo z dokładnie dwiema opcjami, pierwsza to prawda, druga to fałsz; albo "open_answer", który zamiast tego używa correct_answer. Jeśli go pominiesz, pytanie jest traktowane jak wielokrotny wybór.
Odczytywane ustawienia
Pole
Typ
Do czego służy
number_of_tiles
opcjonalnew settings
number
number
Ile pól ma plansza. Od 10 do 75.
Domyślnie: 30
game_mode
opcjonalnew settings
string
string
Czy gracze ścigają się do mety, czy zbierają po drodze przedmioty.
Jedna z wartościrace_to_finishcollect_items
Domyślnie: "race_to_finish"
Przykładowe żądanie
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": "pl",
"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"
}
}'
Sukces
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
"message": "Board Game created successfully"
}
POST/api/public/v1/mazeCo najmniej 1 elementów w items
Treść
Tablica pytań wielokrotnego wyboru albo prawda/fałsz, dokładnie w takim kształcie, jaki przyjmuje endpoint quizu. Pytania otwarte są odrzucane: na drzwiach musi być napisana odpowiedź.
W razie braku używa nazwy “Maze API”
Odczytywane ustawienia
Pole
Typ
Do czego służy
maze_width
opcjonalnew settings
string
string
Jak ułożone są komnaty: jedna kolumna, kwadrat albo szerzej.
Jedna z wartościnarrownormalwide
Domyślnie: "normal"
maze_corridors
opcjonalnew settings
string
string
Ile labiryntu leży między dwoma pytaniami.
Jedna z wartościshortnormallong
Domyślnie: "normal"
maze_fog
opcjonalnew settings
string
string
Pokaż cały labirynt albo tylko to, obok czego gracz już był.
Jedna z wartościoffnear
Domyślnie: "off"
maze_wrong_door_pause
opcjonalnew settings
string
string
Jak długo drzwi pozostają zamknięte po błędnym wyborze.
Jedna z wartościnoneshortlong
Domyślnie: "short"
maze_walk_there
opcjonalnew settings
boolean
boolean
Dodaje przycisk, który przeprowadza pionek do następnej komnaty.
Domyślnie: false
maze_seed
opcjonalnew settings
string
string
Ziarno, z którego generowany jest labirynt. To samo ziarno i te same pytania dają ten sam labirynt; pominięte — losowany jest nowy.
Przykładowe żądanie
POST maze
curl -X POST https://puzzel.org/api/public/v1/maze \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Maze",
"language": "pl",
"items": [
{
"question_type": "multiple_choice",
"description": "What is it called when water vapour turns back into liquid droplets?",
"answers": [
{
"type": "text",
"description": "Evaporation",
"isCorrect": false
},
{
"type": "text",
"description": "Condensation",
"isCorrect": true
},
{
"type": "text",
"description": "Transpiration",
"isCorrect": false
}
],
"explanation": "Cooling vapour condenses into the droplets that make clouds."
},
{
"question_type": "true_false",
"description": "Most of the water on Earth is fresh water.",
"answers": [
{
"type": "text",
"description": "True",
"isCorrect": false
},
{
"type": "text",
"description": "False",
"isCorrect": true
}
]
}
],
"settings": {
"maze_width": "wide",
"maze_corridors": "short",
"maze_seed": "water123",
"maze_fog": "near"
}
}'
POST/api/public/v1/jeopardyCo najmniej 2 elementów w items
Treść
Tablica kategorii, od lewej do prawej. Każda ma nazwę i swoje wskazówki, od górnego wiersza w dół.
W razie braku używa nazwy “Jeopardy API”
Warto wiedzieć
Wskazówka to pytanie w takim kształcie, jaki przyjmuje endpoint quizu, open_answer, o ile nie podano inaczej, z correct_answer i opcjonalnie aliases. Może też nieść value (własną wartość) i daily_double. null zostawia kratkę pustą.
Odczytywane ustawienia
Pole
Typ
Do czego służy
jeopardy_buzzer_mode
opcjonalnew settings
string
string
Kto gra i jak: prowadzący steruje z konsoli, gracze zgłaszają się z telefonów albo każdy gracz przechodzi planszę sam.
Jedna z wartościhostphonessolo
Domyślnie: "host"
jeopardy_contestants
opcjonalnew settings
string
string
Czy konsola mówi o drużynach, czy o graczach.
Jedna z wartościteamsplayers
Domyślnie: "teams"
jeopardy_value_step
opcjonalnew settings
number
number
Ile warty jest wiersz: wskazówka jest warta tyle razy numer swojego wiersza. Od 50 do 500, co 50.
Domyślnie: 100
jeopardy_answer_time
opcjonalnew settings
number
number
Sekundy na odpowiedź po odsłonięciu wskazówki, maksymalnie 300. 0 oznacza brak stopera.
Domyślnie: 20
jeopardy_wrong_answer_costs
opcjonalnew settings
boolean
boolean
Błędna odpowiedź odejmuje od punktacji wartość wskazówki.
Domyślnie: false
jeopardy_reveal_on_timeout
opcjonalnew settings
boolean
boolean
Plansza sama pokazuje odpowiedź, gdy skończy się czas.
Domyślnie: false
jeopardy_require_question_form
opcjonalnew settings
boolean
boolean
Przypomina graczom, by odpowiadali w formie pytania.
Domyślnie: false
Przykładowe żądanie
POST jeopardy
curl -X POST https://puzzel.org/api/public/v1/jeopardy \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Jeopardy",
"language": "pl",
"items": [
{
"name": "Planets",
"questions": [
{
"question_type": "open_answer",
"description": "The planet closest to the Sun.",
"correct_answer": "Mercury"
},
{
"question_type": "open_answer",
"description": "It is known as the red planet.",
"correct_answer": "Mars",
"explanation": "Iron oxide in its soil gives it the colour."
},
{
"question_type": "multiple_choice",
"description": "This planet has the most confirmed moons.",
"answers": [
{
"description": "Jupiter",
"isCorrect": false
},
{
"description": "Saturn",
"isCorrect": true
},
{
"description": "Neptune",
"isCorrect": false
}
],
"daily_double": true
}
]
},
{
"name": "Moons",
"questions": [
{
"question_type": "open_answer",
"description": "The only world besides Earth that people have walked on.",
"correct_answer": "The Moon",
"aliases": [
"Luna"
]
},
null,
{
"question_type": "name_them_all",
"description": "Name the four Galilean satellites.",
"answers": [
{
"description": "Io"
},
{
"description": "Europa"
},
{
"description": "Ganymede",
"aliases": [
"Ganymedes"
]
},
{
"description": "Callisto"
}
],
"required_count": 3,
"value": 500
}
]
}
],
"settings": {
"jeopardy_buzzer_mode": "solo",
"jeopardy_value_step": 200,
"jeopardy_wrong_answer_costs": true
}
}'
POST/api/public/v1/interactive-videoOd 1 do 50 elementów w items
Treść
api_c_interactive_video
W razie braku używa nazwy “Interactive Video API”
Warto wiedzieć
Okienko to obiekt z time (sekundy albo "1:23"), kind ("question", chyba że napisano "note", "think" albo "chapter") i description. Pytanie to pytanie w takim kształcie, jaki przyjmuje endpoint quizu, i może nieść rewind_to: miejsce, od którego wideo odtwarza się od nowa po błędnej odpowiedzi.
Odczytywane ustawienia
Pole
Typ
Do czego służy
video_url
wymaganew settings
string
string
Wideo: strona YouTube, Vimeo albo Bunny Stream albo bezpośredni link do pliku mp4, webm lub mov.
video_duration
opcjonalnew settings
number
number
Długość wideo w sekundach. Gdy ją podasz, okienko po końcu wideo jest odrzucane.
Przykładowe żądanie
POST interactive-video
curl -X POST https://puzzel.org/api/public/v1/interactive-video \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Interactive Video",
"language": "pl",
"items": [
{
"time": 5,
"kind": "chapter",
"description": "Evaporation"
},
{
"time": 42.5,
"kind": "question",
"question_type": "multiple_choice",
"description": "What turns liquid water into vapour?",
"answers": [
{
"type": "text",
"description": "Heat from the sun",
"isCorrect": true
},
{
"type": "text",
"description": "Wind from the north",
"isCorrect": false
},
{
"type": "text",
"description": "Salt in the sea",
"isCorrect": false
}
],
"explanation": "The sun warms the surface and the water evaporates.",
"rewind_to": 20
}
],
"settings": {
"video_url": "https://www.youtube.com/watch?v=al-do-HGuIk",
"video_duration": 180,
"video_allow_skipping": true
}
}'
Sukces
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/interactive-video/embed?p=-Nq8sample_activity_key",
"message": "Interactive video created successfully"
}
Nie wysyłaj ani items, ani sentence — rozmiar i poziom trudności to całe wejście.
Edytor oferuje poziom trudności tylko dla 2x3, 3x3 i 3x4. API stosuje go do każdego rozmiaru, w tym 2x2 i 4x4.
Odczytywane ustawienia
Pole
Typ
Do czego służy
size
opcjonalnew settings
string
string
Rozmiar jednego bloku, zapisany jako wiersze na kolumny — 3x3 daje klasyczną siatkę 9x9. Endpoint sprawdza tylko, czy da się to odczytać jako dwie liczby, więc trzymaj się rozmiarów, które oferuje edytor.
POST/api/public/v1/fill-in-the-gapOd 1 do 50 elementów w items
Treść
api_c_fill_in_the_gap
W razie braku używa nazwy “Fill in the gap API”
Warto wiedzieć
Zapisz całe zdanie i otocz gwiazdkami każde słowo do pominięcia: "Water boils at *100* degrees." Kilka słów w jednej parze gwiazdek to jedna luka. Wpis może też nieść polecenie wyświetlane nad zdaniem.
Przykładowe żądanie
POST fill-in-the-gap
curl -X POST https://puzzel.org/api/public/v1/fill-in-the-gap \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Fill in the gap",
"language": "pl",
"items": [
{
"sentence": "The capital of France is *Paris*, and the river that runs through it is the *Seine*."
},
{
"sentence": "*Amsterdam* is the capital of the Netherlands, but the government sits in *The Hague*.",
"instruction": "Two cities, one of them two words."
},
{
"sentence": "The *Danube* flows through Vienna, Bratislava, *Budapest* and Belgrade."
}
]
}'
Sukces
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/fill-in-the-gap/embed?p=-Nq8sample_activity_key",
"message": "Fill in the gap created successfully"
}
POST/api/public/v1/deconstructOd 1 do 50 elementów w items
Treść
Tablica zdań. Każde słowo do oznaczenia zapisujesz jako [word](label).
W razie braku używa nazwy “Sentence analysis API”
Warto wiedzieć
Zapisz zdanie jako "The [dog](noun) [barks](verb)." Słowa bez znacznika są pokazywane, ale o nie nie pytamy. Etykiety noun, verb, adjective i subject są pokazywane każdemu graczowi w jego własnym języku.
Odczytywane ustawienia
Pole
Typ
Do czego służy
categories
opcjonalnew settings
string[]
string[]
Etykiety, spośród których gracze wybierają, po kolei. Pominięte: etykiety użyte w zdaniach. Wyślij je, aby dodać etykietę, której nie niesie żadne słowo, albo ustalić kolejność.
Przykładowe żądanie
POST deconstruct
curl -X POST https://puzzel.org/api/public/v1/deconstruct \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Sentence analysis",
"language": "pl",
"items": [
{
"sentence": "The [old](adjective) [farmer](noun) [feeds](verb) the [hungry](adjective) [chickens](noun) [early](adverb).",
"instruction": "Label the nouns, verbs, adjectives and adverbs."
},
{
"sentence": "A [brown](adjective) [horse](noun) [jumped](verb) [quickly](adverb) over the [fence](noun)."
},
{
"sentence": "[Two small lambs](subject) [sleep](verb) in the [barn](noun), and the [dog](noun) [watches](verb) [quietly](adverb)."
}
],
"settings": {
"categories": [
"noun",
"verb",
"adjective",
"adverb",
{
"name": "subject",
"color": "#224466"
},
"preposition"
]
}
}'
POST/api/public/v1/logic-puzzleCo najmniej 3 elementów w items
Treść
api_c_logic_puzzle
W razie braku używa nazwy “Logic Puzzle API”
Warto wiedzieć
Każda kategoria potrzebuje tej samej liczby elementów, od 3 do 6, wszystkich różnych. Jedną kategorię można oznaczyć jako ordered (ceny, godziny, wiek) z opcjonalnym unit, co pozwala generatorowi pisać wskazówki o tym, co jest większe, mniejsze i o ile.
Odczytywane ustawienia
Pole
Typ
Do czego służy
story
opcjonalnew settings
string
string
Historia w tle, pokazywana nad wskazówkami.
difficulty
opcjonalnew settings
string
string
Z jakich rodzajów wskazówek może korzystać generator.
Jedna z wartościeasymediumhard
Domyślnie: "easy"
hints
opcjonalnew settings
boolean
boolean
Dodaje przycisk, który pokazuje następny krok.
Domyślnie: true
auto_cross
opcjonalnew settings
boolean
boolean
Zaznaczenie dopasowania wykreśla resztę jego wiersza i kolumny.
Domyślnie: true
clue_mode
opcjonalnew settings
string
string
Kto pisze wskazówki widoczne dla graczy: generowane z tabeli, twoje własne zdania w free_clues albo żadne.
Jedna z wartościgeneratedfreenone
Domyślnie: "generated"
free_clues
opcjonalnew settings
string[]
string[]
Twoje własne zdania ze wskazówkami, pokazywane tak, jak je napiszesz, przy clue_mode "free". Nic ich nie sprawdza.
Przykładowe żądanie
POST logic-puzzle
curl -X POST https://puzzel.org/api/public/v1/logic-puzzle \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Logic Puzzle",
"language": "pl",
"items": [
{
"name": "Baker",
"items": [
"Amira",
"Jonas",
"Priya",
"Tobias"
]
},
{
"name": "Cake",
"items": [
"Lemon drizzle",
"Carrot cake",
"Brownies",
"Apple pie"
]
},
{
"name": "Price",
"items": [
"$2",
"$4",
"$6",
"$8"
],
"ordered": true,
"unit": "dollars"
}
],
"settings": {
"story": "Four friends each baked one thing for the school bake sale and each set a different price. Who baked what, and what did it cost?",
"difficulty": "medium"
}
}'
POST/api/public/v1/scavenger-huntOd 1 do 50 elementów w items
Treść
api_c_scavenger_hunt
W razie braku używa nazwy “Scavenger Hunt API”
Warto wiedzieć
Krok to obiekt z title, description, code i opcjonalnie accepted_codes (inne pisownie, które się liczą), url i link_text. Kod jest sprawdzany bez względu na wielkość liter i spacje. Mapę z pinezkami można dodać tylko w edytorze.
Przykładowe żądanie
POST scavenger-hunt
curl -X POST https://puzzel.org/api/public/v1/scavenger-hunt \
-H "Content-Type: application/json" \
-d '{
"account_api_key": "YOUR_API_KEY",
"email": "you@example.com",
"title": "Scavenger Hunt",
"language": "pl",
"items": [
{
"title": "Start at the front desk",
"description": "Which year is carved above the entrance?",
"code": "1897",
"accepted_codes": [
"eighteen ninety-seven"
]
},
{
"title": "The quiet corner",
"description": "Find the atlas shelf. What colour is the biggest atlas?",
"code": "crimson",
"accepted_codes": [
"dark red"
]
}
]
}'
POST/api/public/v1/spatial-reasoningOd 1 do 50 elementów w items
Treść
api_c_spatial_reasoning
W razie braku używa nazwy “Spatial Reasoning API”
Warto wiedzieć
Obiekty i cele to square, triangle, circle, hexagon, pentagon, star, diamond albo heart. Relacje to inside, outside, behind, in_front_of, right_of, left_of, above, below, same_color_as, different_color_from, larger_than i smaller_than. Reguła, której nie da się nigdy spełnić, kończy się odpowiedzią 400.
POST/api/public/v1/rebusOd 1 do 30 elementów w items
Treść
Tablica zdań. Każde wymienia słowa narysowane jako obrazki; każde inne słowo zostaje swoimi literami.
W razie braku używa nazwy “Rebus API”
Warto wiedzieć
Słowo jest rysowane z części, które razem je literują. Część ma litery, które reprezentuje (text), emoji i shows: słowo opisujące to, co pokazuje obrazek ("broom" dla obrazka oznaczającego "room"). Puzzel sam wylicza zmiany liter. Część może być zamiast tego symbolem, takim jak 4 dla "for".
Odczytywane ustawienia
Pole
Typ
Do czego służy
rebus_commas
opcjonalnew settings
boolean
boolean
Rysuje odciętą pierwszą albo ostatnią literę jako przecinek obok obrazka.
Jeden adres URL obrazu, w polu image. Ten endpoint nie przyjmuje items.
W razie braku używa nazwy “Jigsaw Game API”
Warto wiedzieć
API zawsze tworzy puzzle 4 na 4. Liczba elementów, nieregularne kształty i proste krawędzie to ustawienia edytora — wysyłanie tutaj rows albo columns nic nie daje.
Adres URL jest zapisywany dokładnie tak, jak go wyślesz, a plik nigdy nie jest kopiowany, więc musi pozostać publicznie dostępny tak długo, jak długo gra się w tę aktywność.
Odczytywane ustawienia
Pole
Typ
Do czego służy
image
wymagane
string
string
Bezwzględny adres URL obrazu do pocięcia. Wysyłany na najwyższym poziomie, nie w settings.
POST/api/public/v1/slidingpuzzleNie przyjmuje items
Treść
Jeden adres URL obrazu, w settings. Ten endpoint nie przyjmuje items.
W razie braku używa nazwy “Sliding Puzzle API”
Warto wiedzieć
W odróżnieniu od puzzli, ten endpoint czyta obraz z settings.image. Pole image na najwyższym poziomie jest ignorowane, a wywołanie odpowiada kodem 400.
Adres URL jest zapisywany dokładnie tak, jak go wyślesz, a plik nigdy nie jest kopiowany, więc musi pozostać publicznie dostępny tak długo, jak długo gra się w tę aktywność.
Odczytywane ustawienia
Pole
Typ
Do czego służy
image
wymaganew settings
string
string
Bezwzględny adres URL obrazu do wymieszania. W odróżnieniu od puzzli, ten trafia do settings.