Un POST pentru fiecare tip de activitate. Trimiți conținutul ca JSON și primești înapoi o activitate în contul tău Puzzel.org, plus un URL pe care îl poți da jucătorilor sau îl poți pune într-un iframe.
URL de bază
https://puzzel.org/api/public/v1
Autentificare
Cheie + e-mail în corpul cererii
Endpointuri
38 tipuri de activități
Cotă
10 activități pe zi
Prima ta cerere
Nu ai nimic de instalat și nu e nevoie de niciun handshake: trimiți un corp JSON cu cheia ta, e-mailul tău și conținutul tău. Răspunsul conține cheia noii activități și URL-ul la care se joacă.
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": "ro",
"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"
}
]
}'
Fiecare exemplu de pe această pagină este o cerere completă, care poate fi rulată. Înlocuiește cheia și conținutul cu ale tale și funcționează ca atare.
Autentificare
Nu există anteturi și niciun token bearer. Ambele credențiale călătoresc în corpul JSON al fiecărei cereri, iar cheia este acceptată doar pentru contul căruia îi aparține acel e-mail.
Câmp
Tip
Ce face
account_api_key
obligatoriu
string
string
Cheia API a contului tău. Se pune în corpul cererii, nu într-un antet.
email
obligatoriu
string
string
Adresa cu care te conectezi la contul tău Puzzel.org. Cheia este valabilă doar împreună cu ea.
Cheia ta se află în secțiunea de cont a tabloului tău de bord, după butonul Arată.
Tratează cheia ca pe o parolă. Ea creează și suprascrie activități în contul tău, așa că păstreaz-o pe server și departe de orice poate citi un browser.
Corpul cererii
Fiecare endpoint primește aceleași cinci câmpuri. Ce diferă este câmpul de conținut de sub ele: majoritatea primesc un array de elemente, câteva primesc o singură propoziție sau o singură imagine, iar sudoku nu primește nimic.
Câmp
Tip
Ce face
account_api_key
obligatoriu
string
string
Cheia API a contului tău. Se pune în corpul cererii, nu într-un antet.
email
obligatoriu
string
string
Adresa cu care te conectezi la contul tău Puzzel.org. Cheia este valabilă doar împreună cu ea.
title
opțional
string
string
Numele pe care îl primește activitatea în tabloul tău de bord. Dacă îl omiți, endpointul folosește propriul nume implicit.
language
opțional
string
string
Decide doar limba din URL-ul pe care îl primești înapoi — nu traduce nimic din ce trimiți. Cuvintele ascunse îl citesc și pentru a comuta literele de umplutură la arabă, atunci când valoarea este "ar".
Implicit: "en"
activity_key
opțional
string
string
Omite-l ca să creezi o activitate nouă. Trimite cheia uneia pe care deja o deții și acea activitate este reconstruită în loc.
settings este un obiect cu opțiuni specifice fiecărui endpoint. Care dintre ele sunt citite de un endpoint este listat mai jos, la el; orice altceva pui acolo este ignorat.
Ce primești înapoi
Un apel reușit răspunde cu 200, cu cheia noii activități și URL-ul la care se joacă. Orice altceva răspunde cu success setat pe false și un singur șir de eroare.
{
"success": false,
"error": "Invalid Email or API Key"
}
URL-ul primit înapoi este vizualizarea de încorporare. Înlocuiește embed cu play ca să-l deschizi pe pagină întreagă, sau cu build ca să-l deschizi în editor — cheia de după p= rămâne aceeași.
Creare vs. actualizare
Trimite activity_key și activitatea din spatele ei este reconstruită pe loc: conținutul îi este înlocuit, numele și marcajul de versiune sunt reîmprospătate, iar cheia în sine rămâne aceeași — așa că linkurile și încorporările pe care le-ai partajat deja continuă să funcționeze. Rezultatele, plasarea în folder și orice setare pe care endpointul nu o scrie el însuși rămân neschimbate.
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 este aplicat la fiecare actualizare, inclusiv valoarea lui implicită — dacă îl omiți, activitatea este redenumită cu numele implicit al acelui endpoint.
Blocurile de setări pe care un endpoint le scrie el însuși sunt rescrise de la zero, așa că o actualizare le resetează și pe acestea la valorile pe care le trimiți, sau la valorile implicite ale endpointului.
Poți actualiza doar activități deținute chiar de contul tău. Cheia altcuiva primește răspuns 403.
O actualizare costă la fel ca o creare: un apel scăzut din cota de azi.
Limită de trafic
10
10 activități per cont pe zi
Fiecare apel reușit se contorizează, la fel creările ca și actualizările. Dacă depășești limita, următoarea cerere primește răspuns 429 până când contorul este resetat.
Contorul este șters o dată pe zi de un job programat, nu pe o fereastră glisantă de 24 de ore.
Erori
Erorile sosesc întotdeauna ca JSON, cu aceleași două câmpuri, niciodată ca pagină HTML. Șirul de eroare este scris pentru a fi citit de o persoană — numește câmpul sau limita care a eșuat.
Stare
Ce înseamnă
400
Bad Request
Ceva din corpul cererii lipsește, este malformat sau este în afara intervalului permis. Mesajul numește câmpul.
401
Unauthorized
E-mailul este necunoscut, sau cheia nu aparține acelui cont.
403
Forbidden
activity_key pe care l-ai trimis aparține unui alt cont.
429
Too Many Requests
Cota de azi este epuizată. Se resetează o dată pe zi.
500
Server Error
Generatorul nu a putut construi un joc din ce ai trimis — de obicei prea puține cuvinte, sau cuvinte care nu pot fi îmbinate.
Endpointuri
O cale pentru fiecare tip de activitate, toate POST, toate sub același URL de bază. Fiecare listează conținutul de care are nevoie, setările pe care le citește și o cerere pe care o poți rula.
Cuvinte și litere
V
A
S
A
O
R
A
R
A
Cuvintele încrucișate
Îmbină răspunsurile tale într-o grilă și numerotează definițiile pentru tine.
POST/api/public/v1/crosswordÎntre 2 și 80 în items
Conținut
Un array de cuvinte. Fiecare intrare asociază răspunsul cu definiția care indică spre el.
Revine implicit la numele “Crossword API”
Bine de știut
Răspunsurile mai scurte de două caractere sunt eliminate înainte de construirea grilei, iar cel puțin două trebuie să supraviețuiască acestui pas.
Răspunsurile sunt convertite cu majuscule, iar generatorul are douăzeci de încercări să le potrivească. Dacă nu poate plasa niciun cuvânt, apelul răspunde cu 500.
Setări pe care le citește
Câmp
Tip
Ce face
hidden_solution
opționalîn settings
string
string
Un cuvânt bonus opțional. Literele lui sunt marcate în căsuțele grilei terminate, ca jucătorii să le adune după ce rezolvă cuvintele încrucișate, așa că fiecare literă a lui trebuie să apară în răspunsuri.
Exemplu de cerere
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": "ro",
"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/wordseekerÎntre 2 și 40 în items
Conținut
Un array de cuvinte. Textul definiției devine lista de cuvinte de la care pornesc jucătorii.
Revine implicit la numele “Wordseeker API”
Bine de știut
Răspunsurile sub două caractere sunt eliminate, iar fiecare răspuns este convertit cu majuscule înainte de a intra în grilă.
Grila este completată cu litere latine, cu excepția cazului în care language este "ar", ceea ce comută umplutura la arabă.
Setări pe care le citește
Câmp
Tip
Ce face
hidden_solution
opționalîn settings
string
string
Literele rămase formează acest cuvânt. Setarea lui îi spune și generatorului să potrivească mai întâi soluția, în loc să încadreze cât mai multe cuvinte posibil.
directions
opționalîn settings
string[]
string[]
În ce direcții poate merge un cuvânt. Dacă îl omiți, cuvintele merg doar spre est, sud-est și sud.
Una dintrewesteastnorthsouthnorthwestnortheastsouthwestsoutheast
Implicit: ["east", "southeast", "south"]
template
opționalîn settings
string
string
Decupează grila într-o formă, în loc să o lase pătrată.
Una dintresquarecirclecrossdiamondpyramidsmileystarcross_plus
Exemplu de cerere
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": "ro",
"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/word-scrambleÎntre 1 și 40 în items
Conținut
api_c_word_scramble
Revine implicit la numele “Word Scramble API”
Bine de știut
Activitățile create prin API au mereu activată setarea de amestecare a ordinii, așa că ordinea pe care o trimiți nu este ordinea pe care o primesc jucătorii.
Setări pe care le citește
Câmp
Tip
Ce face
hidden_solution
opționalîn settings
string
string
Un cuvânt bonus opțional pe care jucătorii îl introduc după ce rezolvă restul.
Exemplu de cerere
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": "ro",
"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"
}
}'
POST/api/public/v1/typing-practiceÎntre 1 și 50 în items
Conținut
api_c_typing_practice
Revine implicit la numele “Typing Practice API”
Exemplu de cerere
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": "ro",
"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"
}
]
}'
Succes
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
"message": "Typing Practice created successfully"
}
Un array de cuvinte tematice. Împreună cu spangramul, literele lor trebuie să umple grila exact.
Revine implicit la numele “Strands API”
Bine de știut
Literele tuturor cuvintelor și ale spangramului luate împreună trebuie să însumeze exact 30, 35, 36, 40, 42, 45, 48, 49, 50, 54, 56, 60, 63, 64, 70, 72 sau 80. Orice alt număr răspunde cu 400 și spune câte litere trebuie adăugate sau eliminate.
Setări pe care le citește
Câmp
Tip
Ce face
theme
opționalîn settings
string
string
Ghicitoarea afișată deasupra grilei. Dacă o omiți, jucătorii văd titlul.
spangram
opționalîn settings
string
string
Cuvântul sau expresia care numește tema și traversează grila de la o margine la cealaltă.
POST/api/public/v1/name-them-allÎntre 1 și 250 în items
Conținut
api_c_name_them_all
Revine implicit la numele “Name Them All API”
Bine de știut
O intrare este un obiect cu un answer și, opțional, aliases (alte variante de scriere care contează), o description (sugestia) și un group. Majusculele, diacriticele și punctuația sunt ignorate când se verifică un nume.
Setări pe care le citește
Câmp
Tip
Ce face
list_match_mode
opționalîn settings
string
string
Dacă un nume contează în clipa în care este tastat sau doar la Enter.
Una dintrewhile_typingon_enter
Implicit: "while_typing"
list_slot_hint
opționalîn settings
string
string
Ce dă de gol un spațiu gol: nimic, lungimea numelui, prima lui literă sau sugestia pe care ai scris-o.
Una dintrenonelengthfirst_letterhint
Implicit: "none"
list_arrange
opționalîn settings
string
string
O coloană pentru fiecare grup sau o singură listă.
Una dintregroupsone_list
Implicit: "groups"
list_allow_give_up
opționalîn settings
boolean
boolean
Afișează un buton de renunțare care încheie runda și dezvăluie ce a rămas neenumerat.
{
"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"
}
Un array de perechi. Fiecare pereche conține cele două cartonașe care merg împreună.
Revine implicit la numele “Memory Game API”
Bine de știut
Un cartonaș este un obiect cu un type și o value. Folosește "text" pentru cuvinte, sau "image", "audio", "youtube" ori "link" cu un URL în value, și adaugă alt pentru o descriere.
POST/api/public/v1/matching-pairsÎntre 2 și 30 în items
Conținut
api_c_matching_pairs
Revine implicit la numele “Matching Game API”
Bine de știut
Un cartonaș este un obiect cu un type și o value. Folosește "text" pentru cuvinte, sau "image", "audio", "youtube" ori "link" cu un URL în value, și adaugă alt pentru o descriere.
POST/api/public/v1/flash-cardsÎntre 1 și 150 în items
Conținut
api_c_flash_cards
Revine implicit la numele “Flash Cards API”
Bine de știut
Endpointul stochează exact atâtea cartonașe câte trimiți, așa că trimite exact două per intrare — fața, apoi spatele.
Un cartonaș este un obiect cu un type și o value. Folosește "text" pentru cuvinte, sau "image", "audio", "youtube" ori "link" cu un URL în value, și adaugă alt pentru o descriere.
POST/api/public/v1/categorizeCel puțin 2 în items · cel mult 60 cartonașe în total
Conținut
Un array de categorii, fiecare cu un nume și cartonașele care fac parte din ea.
Revine implicit la numele “Categorize Game API”
Bine de știut
O categorie trimisă fără nume este salvată ca “Categorie fără titlu”, așa că trimite mereu unul.
Un cartonaș este un obiect cu un type și o value. Folosește "text" pentru cuvinte, sau "image", "audio", "youtube" ori "link" cu un URL în value, și adaugă alt pentru o descriere.
POST/api/public/v1/reorderCel puțin 1 în items · cel mult 60 cartonașe în total
Conținut
Un array de secvențe. Fiecare conține cartonașele sale în ordinea corectă.
Revine implicit la numele “Reorder Game API”
Bine de știut
Ordinea pe care o trimiți este stocată ca ordine corectă — numărul unu primul.
Un cartonaș este un obiect cu un type și o value. Folosește "text" pentru cuvinte, sau "image", "audio", "youtube" ori "link" cu un URL în value, și adaugă alt pentru o descriere.
Un array de items din care se alcătuiesc cartonașele. Trimite clar mai multe decât are căsuțe un cartonaș, ca să difere cartonașele între ele.
Revine implicit la numele “Bingo API”
Bine de știut
Un item este un obiect cu o value și, opțional, un type ("text", "image" sau "audio" cu un URL în value), o description (indiciul pe care gazda îl citește în modul clues) și alt.
Setări pe care le citește
Câmp
Tip
Ce face
mode
opționalîn settings
string
string
Ce umple căsuțele: items-urile tale, items-urile tale extrase după indiciul lor sau simple numere (care nu au nevoie de items).
Una dintreitemscluesnumbers
Implicit: "items"
rows
opționalîn settings
number
number
Rânduri pe fiecare cartonaș, de la 2 la 5.
Implicit: 3
columns
opționalîn settings
number
number
Coloane pe fiecare cartonaș, de la 2 la 5.
Implicit: 3
highest_number
opționalîn settings
number
number
În modul numere, cartonașele se umplu de la 1 până la acest număr, cel mult 100. O funcție care ține de un plan: fără plan rămâne 50.
Implicit: 50
Exemplu de cerere
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": "ro",
"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"
}
Un array de cartonașe. Cartonașele din cod își poartă locul în el.
Revine implicit la numele “Keypad API”
Bine de știut
Un cartonaș este un obiect cu o value și, opțional, un type ("text", "image" sau "audio" cu un URL în value), alt și code_position: locul lui în cod, 1 fiind primul. Un cartonaș poate apărea în cod o singură dată, iar cel puțin unul trebuie să fie în cod.
Setări pe care le citește
Câmp
Tip
Ce face
instructions
opționalîn settings
string
string
Întrebarea sau ghicitoarea la care răspunde codul, afișată împreună cu cartonașele.
force_solution_in_correct_order
opționalîn settings
boolean
boolean
Cartonașele trebuie apăsate în ordine. Dezactivat, orice ordine a cartonașelor corecte deschide lacătul.
Implicit: false
randomize_order
opționalîn settings
boolean
boolean
Fiecare jucător primește cartonașele într-o ordine amestecată.
Un array de seturi. Fiecare are un nume și exact patru cartonașe.
Revine implicit la numele “Quartets API”
Bine de știut
Un cartonaș este un nume sau un obiect cu un name și o description (faptul afișat pe el). Niciun nume de cartonaș nu poate apărea de două ori în joc: jucătorii cer cartonașele pe nume.
Setări pe care le citește
Câmp
Tip
Ce face
type
opționalîn settings
string
string
Un joc simplu sau un joc de învățare în care fiecare cartonaș arată un fapt. Dacă îl omiți, este learn când vreun cartonaș are o description.
Una dintrenormallearn
Exemplu de cerere
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": "ro",
"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"
}
}'
Succes
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/quartets/embed?p=-Nq8sample_activity_key",
"message": "Quartets game created successfully"
}
Un array de întrebări. Întrebările cu variante multiple conțin răspunsurile lor; întrebările deschise conțin răspunsul pe care îl accepți.
Revine implicit la numele “Quiz API”
Bine de știut
question_type este "multiple_choice", caz în care opțiunea corectă are isCorrect true; "true_false", la fel, dar cu exact două opțiuni, prima adevărat și a doua fals; sau "open_answer", care folosește în schimb correct_answer. Dacă îl omiți, este tratat ca variante multiple.
Endpointul quiz transmite settings direct, ca blocuri de setări ale activității, așa că nu e locul pentru opțiuni disparate — ajustează quizul ulterior în editor.
Exemplu de cerere
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": "ro",
"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-gameÎntre 1 și 100 în items
Conținut
api_c_board_game
Revine implicit la numele “Board Game API”
Bine de știut
question_type este "multiple_choice", caz în care opțiunea corectă are isCorrect true; "true_false", la fel, dar cu exact două opțiuni, prima adevărat și a doua fals; sau "open_answer", care folosește în schimb correct_answer. Dacă îl omiți, este tratat ca variante multiple.
Setări pe care le citește
Câmp
Tip
Ce face
number_of_tiles
opționalîn settings
number
number
Câte căsuțe are jocul de societate. Între 10 și 75.
Implicit: 30
game_mode
opționalîn settings
string
string
Dacă jucătorii se întrec spre final sau colectează obiecte pe parcurs.
Una dintrerace_to_finishcollect_items
Implicit: "race_to_finish"
Exemplu de cerere
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": "ro",
"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"
}
}'
Succes
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
"message": "Board Game created successfully"
}
Un array de întrebări cu variante multiple sau adevărat-fals, exact în forma pe care o primește endpointul quiz. Întrebările deschise sunt refuzate: o ușă are nevoie de un răspuns scris pe ea.
Revine implicit la numele “Maze API”
Setări pe care le citește
Câmp
Tip
Ce face
maze_width
opționalîn settings
string
string
Cum sunt dispuse camerele: într-o singură coloană, ca un pătrat sau mai late.
Una dintrenarrownormalwide
Implicit: "normal"
maze_corridors
opționalîn settings
string
string
Cât de mult labirint se află între două întrebări.
Una dintreshortnormallong
Implicit: "normal"
maze_fog
opționalîn settings
string
string
Arată tot labirintul sau doar ce a văzut jucătorul pe lângă drumul lui.
Una dintreoffnear
Implicit: "off"
maze_wrong_door_pause
opționalîn settings
string
string
Cât timp rămân ușile închise după una greșită.
Una dintrenoneshortlong
Implicit: "short"
maze_walk_there
opționalîn settings
boolean
boolean
Pune un buton care duce jetonul în camera următoare.
Implicit: false
maze_seed
opționalîn settings
string
string
Seed-ul din care este generat labirintul. Același seed și aceleași întrebări dau același labirint; dacă îl omiți, se generează unul nou.
Exemplu de cerere
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": "ro",
"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"
}
}'
Un array de categorii, de la stânga la dreapta. Fiecare are un nume și indiciile ei, de la rândul de sus în jos.
Revine implicit la numele “Jeopardy API”
Bine de știut
Un indiciu este o întrebare în forma pe care o primește endpointul quiz, open_answer dacă nu se spune altfel, cu correct_answer și, opțional, aliases. Poate conține și value (valoarea lui proprie) și daily_double. null lasă o căsuță goală.
Setări pe care le citește
Câmp
Tip
Ce face
jeopardy_buzzer_mode
opționalîn settings
string
string
Cine joacă cum: gazda o conduce din consolă, jucătorii apasă soneria de pe telefoane sau fiecare jucător parcurge grila singur.
Una dintrehostphonessolo
Implicit: "host"
jeopardy_contestants
opționalîn settings
string
string
Dacă în consolă se vorbește despre echipe sau despre jucători.
Una dintreteamsplayers
Implicit: "teams"
jeopardy_value_step
opționalîn settings
number
number
Cât valorează un rând: un indiciu valorează această sumă înmulțită cu numărul rândului lui. De la 50 la 500, din 50 în 50.
Implicit: 100
jeopardy_answer_time
opționalîn settings
number
number
Secunde pentru răspuns după ce un indiciu este deschis, cel mult 300. 0 înseamnă fără cronometru.
Implicit: 20
jeopardy_wrong_answer_costs
opționalîn settings
boolean
boolean
Un răspuns greșit scade valoarea indiciului din scor.
Implicit: false
jeopardy_reveal_on_timeout
opționalîn settings
boolean
boolean
Grila arată singură răspunsul când expiră timpul.
Implicit: false
jeopardy_require_question_form
opționalîn settings
boolean
boolean
Le reamintește jucătorilor să răspundă sub formă de întrebare.
Implicit: false
Exemplu de cerere
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": "ro",
"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-videoÎntre 1 și 50 în items
Conținut
api_c_interactive_video
Revine implicit la numele “Interactive Video API”
Bine de știut
O fereastră pop-up este un obiect cu time (secunde sau "1:23"), kind ("question", dacă nu se spune "note", "think" sau "chapter") și description. O întrebare este o întrebare în forma pe care o primește endpointul quiz și poate conține rewind_to: momentul de la care se reia după un răspuns greșit.
Setări pe care le citește
Câmp
Tip
Ce face
video_url
obligatoriuîn settings
string
string
Videoclipul: o pagină YouTube, Vimeo sau Bunny Stream sau un link direct către un fișier mp4, webm sau mov.
video_duration
opționalîn settings
number
number
Lungimea videoclipului în secunde. Dacă este dată, o fereastră pop-up de după final este refuzată.
Exemplu de cerere
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": "ro",
"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
}
}'
Succes
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/interactive-video/embed?p=-Nq8sample_activity_key",
"message": "Interactive video created successfully"
}
Nimic. Tot jocul rezultă din cele două setări ale sale.
Revine implicit la numele “Sudoku API”
Bine de știut
Nu trimite items și nici sentence — size și difficulty sunt toată intrarea.
Editorul oferă dificultatea doar pentru 2x3, 3x3 și 3x4. API-ul o aplică pentru fiecare dimensiune, inclusiv 2x2 și 4x4.
Setări pe care le citește
Câmp
Tip
Ce face
size
opționalîn settings
string
string
Dimensiunea unui bloc, scrisă ca rânduri pe coloane — 3x3 dă grila clasică 9x9. Endpointul verifică doar că se poate interpreta ca două numere, așa că rămâi la dimensiunile oferite de editor.
POST/api/public/v1/fill-in-the-gapÎntre 1 și 50 în items
Conținut
api_c_fill_in_the_gap
Revine implicit la numele “Fill in the gap API”
Bine de știut
Scrie propoziția întreagă și pune asteriscuri în jurul fiecărui cuvânt de omis: "Water boils at *100* degrees." Mai multe cuvinte într-o singură pereche formează o singură lacună. O intrare poate conține și o instrucțiune afișată deasupra propoziției.
Exemplu de cerere
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": "ro",
"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."
}
]
}'
Succes
{
"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/deconstructÎntre 1 și 50 în items
Conținut
Un array de propoziții. Fiecare cuvânt de etichetat este scris ca [word](label).
Revine implicit la numele “Sentence analysis API”
Bine de știut
Scrie o propoziție astfel: "The [dog](noun) [barks](verb)." Cuvintele fără etichetă sunt afișate, dar nu sunt cerute. Etichetele noun, verb, adjective și subject sunt afișate fiecărui jucător în propria lui limbă.
Setări pe care le citește
Câmp
Tip
Ce face
categories
opționalîn settings
string[]
string[]
Etichetele dintre care aleg jucătorii, în ordine. Dacă îl omiți, sunt etichetele folosite în propoziții. Trimite-l ca să adaugi o etichetă pe care nu o poartă niciun cuvânt sau ca să stabilești ordinea.
Exemplu de cerere
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": "ro",
"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-puzzleCel puțin 3 în items
Conținut
api_c_logic_puzzle
Revine implicit la numele “Logic Puzzle API”
Bine de știut
Fiecare categorie are nevoie de același număr de elemente, de la 3 la 6, toate diferite. O categorie poate fi marcată ordered (prețuri, ore, vârste), cu un unit opțional, ceea ce îi permite generatorului să scrie indicii despre mai mult, mai puțin și cu cât mai mult.
Setări pe care le citește
Câmp
Tip
Ce face
story
opționalîn settings
string
string
Povestea de fundal afișată deasupra indiciilor.
difficulty
opționalîn settings
string
string
Ce fel de indicii poate folosi generatorul.
Una dintreeasymediumhard
Implicit: "easy"
hints
opționalîn settings
boolean
boolean
Pune un buton care arată pasul următor.
Implicit: true
auto_cross
opționalîn settings
boolean
boolean
Marcarea unei potriviri taie restul rândului și al coloanei ei.
Implicit: true
clue_mode
opționalîn settings
string
string
Cine scrie indiciile pe care le văd jucătorii: generate din tabel, propriile tale propoziții din free_clues sau niciunul.
Una dintregeneratedfreenone
Implicit: "generated"
free_clues
opționalîn settings
string[]
string[]
Propriile tale propoziții-indiciu, afișate exact cum le-ai scris, cu clue_mode "free". Nimic nu le verifică.
Exemplu de cerere
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": "ro",
"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-huntÎntre 1 și 50 în items
Conținut
api_c_scavenger_hunt
Revine implicit la numele “Scavenger Hunt API”
Bine de știut
Un pas este un obiect cu title, description, code și, opțional, accepted_codes (alte variante de scriere care contează), url și link_text. Un cod este verificat fără a ține cont de majuscule și de spații. Harta cu pini poate fi adăugată doar în editor.
Exemplu de cerere
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": "ro",
"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-reasoningÎntre 1 și 50 în items
Conținut
api_c_spatial_reasoning
Revine implicit la numele “Spatial Reasoning API”
Bine de știut
Obiectele și țintele sunt square, triangle, circle, hexagon, pentagon, star, diamond sau heart. Relațiile sunt inside, outside, behind, in_front_of, right_of, left_of, above, below, same_color_as, different_color_from, larger_than și smaller_than. O regulă care nu poate fi îndeplinită niciodată răspunde cu 400.
Un array de propoziții. Fiecare enumeră cuvintele desenate ca imagini; orice alt cuvânt rămâne cu literele lui.
Revine implicit la numele “Rebus API”
Bine de știut
Un cuvânt este desenat din părți care împreună îl compun. O parte are literele pe care le reprezintă (text), un emoji și shows: cuvântul pentru ce arată imaginea ("broom" pentru o imagine care stă pentru "room"). Puzzel calculează singur schimbările de litere. O parte poate fi în schimb un simbol, cum ar fi 4 pentru "for".
Setări pe care le citește
Câmp
Tip
Ce face
rebus_commas
opționalîn settings
boolean
boolean
Desenează o primă sau o ultimă literă eliminată ca o virgulă lângă imagine.
Un URL de imagine, în câmpul image. Acest endpoint nu primește items.
Revine implicit la numele “Jigsaw Game API”
Bine de știut
API-ul creează întotdeauna un puzzle de 4 pe 4. Numărul de piese, piesele neregulate și marginile drepte sunt setări din editor — trimiterea de rows sau columns aici nu are niciun efect.
URL-ul este stocat exact așa cum l-ai trimis, iar fișierul nu este copiat niciodată, așa că trebuie să rămână accesibil public atât timp cât activitatea este jucată.
Setări pe care le citește
Câmp
Tip
Ce face
image
obligatoriu
string
string
URL absolut al imaginii de tăiat în bucăți. Se trimite la nivelul de sus, nu în interiorul settings.
Un URL de imagine, în interiorul settings. Acest endpoint nu primește items.
Revine implicit la numele “Sliding Puzzle API”
Bine de știut
Spre deosebire de puzzle, acest endpoint își citește imaginea din settings.image. Un câmp image la nivelul de sus este ignorat, iar apelul răspunde cu 400.
URL-ul este stocat exact așa cum l-ai trimis, iar fișierul nu este copiat niciodată, așa că trebuie să rămână accesibil public atât timp cât activitatea este jucată.
Setări pe care le citește
Câmp
Tip
Ce face
image
obligatoriuîn settings
string
string
URL absolut al imaginii de amestecat. Spre deosebire de cel de la puzzle, acesta se află în interiorul settings.