Invia i tuoi contenuti in formato JSON con una richiesta POST all'endpoint del tipo di attività scelto. L'API crea l'attività nel tuo account Puzzel.org e restituisce un URL da condividere o incorporare in un iframe.
URL di base
https://puzzel.org/api/public/v1
Autenticazione
Chiave + e-mail nel corpo
Endpoint
38 tipi di attività
Quota
10 attività al giorno
La tua prima richiesta
Invia una richiesta con un corpo JSON contenente la chiave API, l'indirizzo e-mail del tuo account e i contenuti. La risposta contiene la chiave della nuova attività e l'URL per aprirla.
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": "it",
"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"
}
]
}'
Ogni esempio di questa pagina è una richiesta completa e pronta da eseguire. Metti la tua chiave e i tuoi contenuti e funziona così com'è.
Autenticazione
Non serve un header di autenticazione né un bearer token: invia la chiave API e l'indirizzo e-mail nel corpo JSON di ogni richiesta. La chiave è valida solo per l'account associato a quell'indirizzo.
Campo
Tipo
Cosa fa
account_api_key
obbligatorio
string
string
La chiave API del tuo account. Va nel corpo, non in un header.
email
obbligatorio
string
string
L'indirizzo con cui accedi al tuo account Puzzel.org. La chiave è valida solo insieme a esso.
Trovi la chiave API nella sezione account della dashboard: fai clic su Mostra per visualizzarla.
Tratta la chiave API come una password: permette di creare e sovrascrivere attività nel tuo account. Conservala sul server e non inserirla nel codice accessibile dal browser.
Il corpo della richiesta
Tutti gli endpoint accettano gli stessi cinque campi comuni. I contenuti richiesti variano: la maggior parte usa un array items, alcuni una frase o un'immagine. Il sudoku non richiede un campo per i contenuti.
Campo
Tipo
Cosa fa
account_api_key
obbligatorio
string
string
La chiave API del tuo account. Va nel corpo, non in un header.
email
obbligatorio
string
string
L'indirizzo con cui accedi al tuo account Puzzel.org. La chiave è valida solo insieme a esso.
title
facoltativo
string
string
Il nome dell'attività nella dashboard. Se ometti questo campo, viene usato il nome predefinito dell'endpoint.
language
facoltativo
string
string
Imposta la lingua dell'URL restituito, senza tradurre i contenuti inviati. Per le parole intrecciate, il valore "ar" seleziona anche le lettere arabe con cui riempire le caselle libere.
Predefinito: "en"
activity_key
facoltativo
string
string
Ometterlo crea una nuova attività. Passa la chiave di una che possiedi già e quell'attività viene invece ricostruita.
settings contiene le opzioni specifiche dell'endpoint. Per ogni endpoint sono elencate qui sotto le impostazioni supportate; le altre vengono ignorate.
Cosa ricevi in risposta
Una chiamata riuscita risponde 200 con la chiave della nuova attività e l'URL su cui si gioca. Tutto il resto risponde con success impostato a false e una sola stringa di errore.
{
"success": false,
"error": "Invalid Email or API Key"
}
L'url che ricevi è la vista di incorporamento. Sostituisci embed con play per aprirla a pagina intera, o con build per aprirla nell'editor — la chiave dopo p= resta la stessa.
Creare o aggiornare
Invia activity_key e l'attività corrispondente viene ricostruita sul posto: i contenuti vengono sostituiti, il nome e la marca temporale della versione vengono aggiornati e la chiave resta la stessa — così i link e i codici di incorporamento che hai già condiviso continuano a funzionare. Risultati, posizione nelle cartelle e ogni impostazione che l'endpoint non scrive restano come erano.
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 viene applicato anche agli aggiornamenti. Se lo ometti, il nome dell'attività viene sostituito con quello predefinito dell'endpoint.
I blocchi di impostazioni che un endpoint scrive da sé vengono riscritti da zero, quindi anche un aggiornamento li riporta ai valori che invii, o ai valori predefiniti dell'endpoint.
Puoi aggiornare solo le attività di cui è proprietario il tuo account. La chiave di qualcun altro risponde 403.
Un aggiornamento costa quanto una creazione: una chiamata sulla quota di oggi.
Limite di frequenza
10
10 attività per account al giorno
Ogni richiesta riuscita viene conteggiata nel limite giornaliero, sia per creare sia per aggiornare un'attività. Una volta raggiunto il limite, le richieste successive restituiscono il codice 429 fino all'azzeramento del contatore.
Il contatore viene azzerato una volta al giorno da un processo pianificato, non su una finestra mobile di 24 ore.
Errori
Gli errori arrivano sempre come JSON con gli stessi due campi, mai come pagina HTML. La stringa di errore è scritta per essere letta da una persona: indica il campo o il limite che non ha funzionato.
Stato
Cosa significa
400
Bad Request
Qualcosa nel corpo manca, è malformato o fuori intervallo. Il messaggio indica il campo.
401
Unauthorized
L'e-mail è sconosciuta, oppure la chiave non appartiene a quell'account.
403
Forbidden
L'activity_key che hai inviato appartiene a un altro account.
429
Too Many Requests
La quota di oggi è esaurita. Si azzera una volta al giorno.
500
Server Error
Il generatore non è riuscito a costruire un rompicapo con quello che hai inviato — di solito troppe poche parole, o parole che non si incastrano tra loro.
Endpoint
Un percorso per ogni tipo di attività, tutti in POST, tutti sotto lo stesso URL di base. Ognuno elenca i contenuti che gli servono, le impostazioni che legge e una richiesta che puoi eseguire.
Parole e lettere
M
I
O
A
A
R
C
O
E
Cruciverba
Incastra le tue risposte in una griglia e numera le definizioni al posto tuo.
Un array di parole. Ogni voce abbina la risposta alla definizione che la indica.
Ripiega sul nome “Crossword API”
Da sapere
Le risposte con meno di due caratteri vengono escluse prima di generare la griglia. Devono restare almeno due risposte valide.
Le risposte vengono convertite in maiuscolo e il generatore ha venti tentativi per incastrarle. Se non riesce a piazzare nemmeno una parola, la chiamata risponde 500.
Impostazioni che legge
Campo
Tipo
Cosa fa
hidden_solution
facoltativoin settings
string
string
Una parola bonus facoltativa. Le sue lettere vengono segnate in alcune caselle della griglia completata, perché i giocatori le raccolgano una volta risolto il cruciverba, quindi ogni sua lettera deve comparire nelle risposte.
Richiesta di esempio
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": "it",
"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"
}
]
}'
Un array di parole. Il testo della definizione diventa la lista di parole da cui lavorano i giocatori.
Ripiega sul nome “Wordseeker API”
Da sapere
Le risposte sotto i due caratteri vengono scartate, e ogni risposta viene convertita in maiuscolo prima di finire nella griglia.
La griglia viene riempita con lettere latine, a meno che language non sia "ar", che passa il riempimento all'arabo.
Impostazioni che legge
Campo
Tipo
Cosa fa
hidden_solution
facoltativoin settings
string
string
Le lettere rimaste dopo aver trovato tutte le parole formano questa soluzione nascosta. Se la imposti, il generatore dà priorità alla soluzione rispetto al numero di parole da inserire nella griglia.
directions
facoltativoin settings
string[]
string[]
Le direzioni in cui possono essere inserite le parole. Se ometti questa impostazione, vengono usate solo est, sud-est e sud.
Uno trawesteastnorthsouthnorthwestnortheastsouthwestsoutheast
Predefinito: ["east", "southeast", "south"]
template
facoltativoin settings
string
string
Ritaglia la griglia in una forma invece di lasciarla quadrata.
Uno trasquarecirclecrossdiamondpyramidsmileystarcross_plus
Richiesta di esempio
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": "it",
"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-scrambleDa 1 a 40 in items
Contenuti
api_c_word_scramble
Ripiega sul nome “Word Scramble API”
Da sapere
Le attività create tramite API hanno sempre attiva l'impostazione che mescola l'ordine, quindi l'ordine che invii non è quello che ricevono i giocatori.
Impostazioni che legge
Campo
Tipo
Cosa fa
hidden_solution
facoltativoin settings
string
string
Una parola bonus facoltativa che i giocatori inseriscono quando hanno risolto il resto.
Richiesta di esempio
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": "it",
"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-practiceDa 1 a 50 in items
Contenuti
api_c_typing_practice
Ripiega sul nome “Typing Practice API”
Richiesta di esempio
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": "it",
"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"
}
]
}'
Successo
{
"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 di parole. Ogni voce abbina la risposta a una definizione abbastanza breve da stare in una sola casella.
Ripiega sul nome “Arrowword API”
Impostazioni che legge
Campo
Tipo
Cosa fa
hidden_solution
facoltativoin settings
string
string
Una parola bonus facoltativa. Le sue lettere vengono segnate in alcune caselle della griglia completata, quindi ogni sua lettera deve comparire nelle risposte.
Un array di parole a tema. Insieme allo spangram, le loro lettere devono riempire esattamente il tabellone.
Ripiega sul nome “Strands API”
Da sapere
Le lettere di tutte le parole e dello spangram insieme devono essere esattamente 30, 35, 36, 40, 42, 45, 48, 49, 50, 54, 56, 60, 63, 64, 70, 72 o 80. Con qualsiasi altro numero la chiamata risponde 400 e indica quante lettere aggiungere o togliere.
Impostazioni che legge
Campo
Tipo
Cosa fa
theme
facoltativoin settings
string
string
L'indovinello mostrato sopra la griglia. Se lo ometti, i giocatori vedono il titolo.
spangram
facoltativoin settings
string
string
La parola o la frase che dà il nome al tema e attraversa il tabellone da un bordo all'altro.
POST/api/public/v1/name-them-allDa 1 a 250 in items
Contenuti
api_c_name_them_all
Ripiega sul nome “Name Them All API”
Da sapere
Una voce è un oggetto con una answer e, facoltativamente, aliases (altre grafie valide), una description (il suggerimento) e un group. Maiuscole, accenti e punteggiatura vengono ignorati quando si controlla un nome.
Impostazioni che legge
Campo
Tipo
Cosa fa
list_match_mode
facoltativoin settings
string
string
Se un nome conta nel momento in cui viene scritto, oppure solo premendo Invio.
Uno trawhile_typingon_enter
Predefinito: "while_typing"
list_slot_hint
facoltativoin settings
string
string
Cosa svela una casella vuota: niente, la lunghezza del nome, la sua prima lettera o il suggerimento che hai scritto.
Uno tranonelengthfirst_letterhint
Predefinito: "none"
list_arrange
facoltativoin settings
string
string
Una colonna per gruppo, oppure un unico elenco.
Uno tragroupsone_list
Predefinito: "groups"
list_allow_give_up
facoltativoin settings
boolean
boolean
Mostra un pulsante per arrendersi che termina il tentativo e rivela ciò che è mancato.
{
"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 di coppie. Ogni coppia contiene le due carte che vanno insieme.
Ripiega sul nome “Memory Game API”
Da sapere
Una carta è un oggetto con un type e un value. Usa "text" per le parole, oppure "image", "audio", "youtube" o "link" con un URL in value, e aggiungi alt per una descrizione.
POST/api/public/v1/matching-pairsDa 2 a 30 in items
Contenuti
api_c_matching_pairs
Ripiega sul nome “Matching Game API”
Da sapere
Una carta è un oggetto con un type e un value. Usa "text" per le parole, oppure "image", "audio", "youtube" o "link" con un URL in value, e aggiungi alt per una descrizione.
L'endpoint salva tutte le carte che invii, quindi inviane esattamente due per voce — prima il fronte, poi il retro.
Una carta è un oggetto con un type e un value. Usa "text" per le parole, oppure "image", "audio", "youtube" o "link" con un URL in value, e aggiungi alt per una descrizione.
POST/api/public/v1/categorizeAlmeno 2 in items · Al massimo 60 carte in tutto
Contenuti
Un array di categorie, ognuna con un nome e le carte che le appartengono.
Ripiega sul nome “Categorize Game API”
Da sapere
Una categoria inviata senza nome viene salvata come “Untitled Category”, quindi inviane sempre uno.
Una carta è un oggetto con un type e un value. Usa "text" per le parole, oppure "image", "audio", "youtube" o "link" con un URL in value, e aggiungi alt per una descrizione.
POST/api/public/v1/reorderAlmeno 1 in items · Al massimo 60 carte in tutto
Contenuti
Un array di sequenze. Ognuna contiene le sue carte nell'ordine corretto.
Ripiega sul nome “Reorder Game API”
Da sapere
L'ordine che invii viene salvato come ordine corretto — il numero uno per primo.
Una carta è un oggetto con un type e un value. Usa "text" per le parole, oppure "image", "audio", "youtube" o "link" con un URL in value, e aggiungi alt per una descrizione.
Un array di items da cui vengono composte le carte. Inviane chiaramente più di quante ne abbia una carta, così le carte risultano diverse.
Ripiega sul nome “Bingo API”
Da sapere
Un item è un oggetto con un value e, facoltativamente, un type ("text", "image" o "audio" con un URL in value), una description (l'indizio che il conduttore legge ad alta voce nella modalità a indizi) e alt.
Impostazioni che legge
Campo
Tipo
Cosa fa
mode
facoltativoin settings
string
string
Cosa riempie le caselle: i tuoi items, i tuoi items estratti tramite il loro indizio, oppure semplici numeri (che non richiedono items).
Uno traitemscluesnumbers
Predefinito: "items"
rows
facoltativoin settings
number
number
Le righe di ogni carta, da 2 a 5.
Predefinito: 3
columns
facoltativoin settings
number
number
Le colonne di ogni carta, da 2 a 5.
Predefinito: 3
highest_number
facoltativoin settings
number
number
Nella modalità a numeri, le carte si riempiono da 1 fino a questo numero, al massimo 100. È una funzione dei piani a pagamento: senza un piano resta 50.
Predefinito: 50
Richiesta di esempio
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": "it",
"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 di tasti. I tasti che fanno parte del codice indicano la propria posizione al suo interno.
Ripiega sul nome “Keypad API”
Da sapere
Un tasto è un oggetto con un value e, facoltativamente, un type ("text", "image" o "audio" con un URL in value), alt e code_position: la sua posizione nel codice, 1 per il primo. Un tasto può comparire nel codice una sola volta, e almeno un tasto deve farne parte.
Impostazioni che legge
Campo
Tipo
Cosa fa
instructions
facoltativoin settings
string
string
La domanda o l'indovinello a cui risponde il codice, mostrato insieme al tastierino.
force_solution_in_correct_order
facoltativoin settings
boolean
boolean
I tasti vanno premuti in ordine. Disattivato, qualsiasi ordine dei tasti giusti apre il lucchetto.
Predefinito: false
randomize_order
facoltativoin settings
boolean
boolean
Ogni giocatore riceve i tasti disposti in ordine mescolato.
Un array di quartetti. Ognuno ha un nome ed esattamente quattro carte.
Ripiega sul nome “Quartets API”
Da sapere
Una carta è un nome, oppure un oggetto con un name e una description (l'informazione mostrata sulla carta). Nessun nome di carta può comparire due volte nel gioco: i giocatori chiedono le carte per nome.
Impostazioni che legge
Campo
Tipo
Cosa fa
type
facoltativoin settings
string
string
Un gioco semplice, oppure un gioco didattico in cui ogni carta mostra un'informazione. Se lo ometti, è learn quando una qualsiasi carta ha una description.
Uno tranormallearn
Richiesta di esempio
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": "it",
"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"
}
}'
Successo
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/quartets/embed?p=-Nq8sample_activity_key",
"message": "Quartets game created successfully"
}
Un array di domande. Ogni domanda a scelta multipla include le opzioni di risposta; ogni domanda aperta include la risposta accettata.
Ripiega sul nome “Quiz API”
Da sapere
question_type è "multiple_choice", dove l'opzione giusta ha isCorrect true; "true_false", lo stesso ma con esattamente due opzioni, la prima vera e la seconda falsa; oppure "open_answer", che usa invece correct_answer. Se lo ometti, viene trattata come scelta multipla.
L'endpoint quiz passa settings direttamente come blocchi di impostazioni dell'attività, quindi non è il posto per opzioni sparse — regola il quiz nell'editor dopo.
Richiesta di esempio
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": "it",
"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."
}
]
}'
question_type è "multiple_choice", dove l'opzione giusta ha isCorrect true; "true_false", lo stesso ma con esattamente due opzioni, la prima vera e la seconda falsa; oppure "open_answer", che usa invece correct_answer. Se lo ometti, viene trattata come scelta multipla.
Impostazioni che legge
Campo
Tipo
Cosa fa
number_of_tiles
facoltativoin settings
number
number
Quante caselle ha il tabellone. Tra 10 e 75.
Predefinito: 30
game_mode
facoltativoin settings
string
string
Se i giocatori corrono al traguardo o raccolgono oggetti lungo il percorso.
Uno trarace_to_finishcollect_items
Predefinito: "race_to_finish"
Richiesta di esempio
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": "it",
"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"
}
}'
Successo
{
"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 di domande a scelta multipla o vero o falso, esattamente nella forma che accetta l'endpoint quiz. Le domande aperte vengono rifiutate: una porta ha bisogno di una risposta scritta sopra.
Ripiega sul nome “Maze API”
Impostazioni che legge
Campo
Tipo
Cosa fa
maze_width
facoltativoin settings
string
string
Come sono disposte le sale: in una colonna, in un quadrato o in una forma più larga.
Uno tranarrownormalwide
Predefinito: "normal"
maze_corridors
facoltativoin settings
string
string
Quanto labirinto c'è tra una domanda e l'altra.
Uno trashortnormallong
Predefinito: "normal"
maze_fog
facoltativoin settings
string
string
Mostra tutto il labirinto, oppure solo ciò che il giocatore ha già incontrato.
Uno traoffnear
Predefinito: "off"
maze_wrong_door_pause
facoltativoin settings
string
string
Per quanto tempo le porte restano chiuse dopo averne scelta una sbagliata.
Uno tranoneshortlong
Predefinito: "short"
maze_walk_there
facoltativoin settings
boolean
boolean
Offre un pulsante che porta la pedina nella sala successiva.
Predefinito: false
maze_seed
facoltativoin settings
string
string
Il seme da cui viene generato il labirinto. Lo stesso seme con le stesse domande dà lo stesso labirinto; se lo ometti, ne viene estratto uno nuovo.
Richiesta di esempio
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": "it",
"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 di categorie, da sinistra a destra. Ognuna ha un nome e i suoi indizi, dalla riga in alto in giù.
Ripiega sul nome “Jeopardy API”
Da sapere
Un indizio è una domanda nella forma che accetta l'endpoint quiz, open_answer se non indicato altrimenti, con correct_answer e, facoltativamente, aliases. Può avere anche value (il suo valore) e daily_double. null lascia vuota una casella.
Impostazioni che legge
Campo
Tipo
Cosa fa
jeopardy_buzzer_mode
facoltativoin settings
string
string
Chi gioca e come: il conduttore gestisce il tabellone dalla console, i giocatori premono il buzzer dal telefono, oppure ogni giocatore gioca il tabellone da solo.
Uno trahostphonessolo
Predefinito: "host"
jeopardy_contestants
facoltativoin settings
string
string
Se la console parla di squadre o di giocatori.
Uno trateamsplayers
Predefinito: "teams"
jeopardy_value_step
facoltativoin settings
number
number
Quanto vale una riga: un indizio vale questa cifra moltiplicata per il numero della sua riga. Da 50 a 500, a passi di 50.
Predefinito: 100
jeopardy_answer_time
facoltativoin settings
number
number
I secondi per rispondere una volta aperto un indizio, fino a 300. Con 0 non c'è il timer.
Predefinito: 20
jeopardy_wrong_answer_costs
facoltativoin settings
boolean
boolean
Una risposta sbagliata toglie dal punteggio il valore dell'indizio.
Predefinito: false
jeopardy_reveal_on_timeout
facoltativoin settings
boolean
boolean
Il tabellone mostra la risposta da solo quando il tempo scade.
Predefinito: false
jeopardy_require_question_form
facoltativoin settings
boolean
boolean
Ricorda ai giocatori di rispondere sotto forma di domanda.
Predefinito: false
Richiesta di esempio
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": "it",
"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-videoDa 1 a 50 in items
Contenuti
api_c_interactive_video
Ripiega sul nome “Interactive Video API”
Da sapere
Un popup è un oggetto con time (secondi, oppure "1:23"), kind ("question", a meno che indichi "note", "think" o "chapter") e description. Una domanda è una domanda nella forma che accetta l'endpoint quiz e può avere rewind_to: il punto da cui riparte il video dopo una risposta sbagliata.
Impostazioni che legge
Campo
Tipo
Cosa fa
video_url
obbligatorioin settings
string
string
Il video: una pagina di YouTube, Vimeo o Bunny Stream, oppure un link diretto a un file mp4, webm o mov.
video_duration
facoltativoin settings
number
number
La durata del video in secondi. Se la indichi, un popup oltre la fine viene rifiutato.
Richiesta di esempio
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": "it",
"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
}
}'
Successo
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/interactive-video/embed?p=-Nq8sample_activity_key",
"message": "Interactive video created successfully"
}
Niente. L'intero rompicapo nasce dalle sue due impostazioni.
Ripiega sul nome “Sudoku API”
Da sapere
Non inviare né items né sentence — dimensione e difficoltà sono tutto l'input.
L'editor offre la difficoltà solo per 2x3, 3x3 e 3x4. L'API la applica a ogni dimensione, 2x2 e 4x4 comprese.
Impostazioni che legge
Campo
Tipo
Cosa fa
size
facoltativoin settings
string
string
La dimensione di un blocco, scritta come righe per colonne — 3x3 dà la classica griglia 9x9. L'endpoint verifica solo che sia leggibile come due numeri, quindi resta sulle dimensioni che offre l'editor.
Uno tra2x22x33x33x44x4
Predefinito: "3x3"
difficulty_level
facoltativoin settings
string
string
Quanti numeri restano sulla griglia come punto di partenza.
POST/api/public/v1/fill-in-the-gapDa 1 a 50 in items
Contenuti
api_c_fill_in_the_gap
Ripiega sul nome “Fill in the gap API”
Da sapere
Scrivi la frase per intero e metti degli asterischi attorno a ogni parola da togliere: "Water boils at *100* degrees." Più parole dentro la stessa coppia formano un unico spazio vuoto. Una voce può anche avere un'istruzione mostrata sopra la frase.
Richiesta di esempio
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": "it",
"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."
}
]
}'
Successo
{
"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"
}
Un array di frasi. Ogni parola da etichettare si scrive come [word](label).
Ripiega sul nome “Sentence analysis API”
Da sapere
Scrivi una frase come "The [dog](noun) [barks](verb)." Le parole senza tag vengono mostrate ma non richieste. Le etichette noun, verb, adjective e subject vengono mostrate a ogni giocatore nella sua lingua.
Impostazioni che legge
Campo
Tipo
Cosa fa
categories
facoltativoin settings
string[]
string[]
Le etichette tra cui scelgono i giocatori, in ordine. Se ometti questa impostazione, sono le etichette usate nelle frasi. Inviala per aggiungere un'etichetta che nessuna parola ha, o per sistemare l'ordine.
Richiesta di esempio
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": "it",
"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"
]
}
}'
Ogni categoria deve avere lo stesso numero di elementi, da 3 a 6, tutti diversi. Una categoria può essere contrassegnata come ordered (prezzi, orari, età) con un unit facoltativo, che permette al generatore di scrivere indizi su più, meno e quanto.
Impostazioni che legge
Campo
Tipo
Cosa fa
story
facoltativoin settings
string
string
La storia di sfondo mostrata sopra gli indizi.
difficulty
facoltativoin settings
string
string
Quali tipi di indizio può usare il generatore.
Uno traeasymediumhard
Predefinito: "easy"
hints
facoltativoin settings
boolean
boolean
Offre un pulsante che mostra il passaggio successivo.
Predefinito: true
auto_cross
facoltativoin settings
boolean
boolean
Segnare un abbinamento barra il resto della sua riga e della sua colonna.
Predefinito: true
clue_mode
facoltativoin settings
string
string
Chi scrive gli indizi che vedono i giocatori: generati dalla tabella, le tue frasi in free_clues, oppure nessuno.
Uno trageneratedfreenone
Predefinito: "generated"
free_clues
facoltativoin settings
string[]
string[]
Le tue frasi come indizi, mostrate così come sono scritte, con clue_mode "free". Nessun controllo le verifica.
Richiesta di esempio
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": "it",
"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-huntDa 1 a 50 in items
Contenuti
api_c_scavenger_hunt
Ripiega sul nome “Scavenger Hunt API”
Da sapere
Un passaggio è un oggetto con title, description, code e, facoltativamente, accepted_codes (altre grafie valide), url e link_text. Un codice viene controllato senza distinguere maiuscole e spazi. La mappa con i segnaposto si può aggiungere solo nell'editor.
Richiesta di esempio
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": "it",
"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-reasoningDa 1 a 50 in items
Contenuti
api_c_spatial_reasoning
Ripiega sul nome “Spatial Reasoning API”
Da sapere
Gli oggetti e le destinazioni sono square, triangle, circle, hexagon, pentagon, star, diamond o heart. Le relazioni sono inside, outside, behind, in_front_of, right_of, left_of, above, below, same_color_as, different_color_from, larger_than e smaller_than. Una regola che non può mai essere soddisfatta risponde 400.
Impostazioni che legge
Campo
Tipo
Cosa fa
clue_mode
facoltativoin settings
string
string
Regole mostrate come immagini o come frasi.
Uno travisualtext
Predefinito: "visual"
unique_object_picks
facoltativoin settings
boolean
boolean
Ogni forma può essere posizionata una sola volta.
Predefinito: false
hide_color_picker
facoltativoin settings
boolean
boolean
I giocatori non possono cambiare il colore delle forme.
Un array di frasi. Ognuna elenca le parole disegnate come immagini; ogni altra parola resta con le sue lettere.
Ripiega sul nome “Rebus API”
Da sapere
Una parola viene disegnata con parti che, insieme, la compongono. Una parte ha le lettere che rappresenta (text), un emoji e shows: la parola che indica ciò che mostra l'immagine ("broom" per un'immagine che rappresenta "room"). Puzzel calcola i cambi di lettera. Una parte può anche essere un simbolo, come 4 per "for".
Impostazioni che legge
Campo
Tipo
Cosa fa
rebus_commas
facoltativoin settings
boolean
boolean
Disegna una lettera iniziale o finale tolta come una virgola accanto all'immagine.
Un solo URL di immagine, nel campo image. Questo endpoint non accetta items.
Ripiega sul nome “Jigsaw Game API”
Da sapere
L'API crea sempre un puzzle 4 per 4. Il numero di pezzi, i pezzi irregolari e i bordi dritti sono impostazioni dell'editor — inviare qui rows o columns non fa niente.
L'URL viene salvato così come lo hai inviato e il file non viene mai copiato, quindi deve restare pubblicamente raggiungibile per tutto il tempo in cui l'attività viene giocata.
Impostazioni che legge
Campo
Tipo
Cosa fa
image
obbligatorio
string
string
URL assoluto dell'immagine da tagliare. Va inviato al primo livello, non dentro settings.
Un solo URL di immagine, dentro settings. Questo endpoint non accetta items.
Ripiega sul nome “Sliding Puzzle API”
Da sapere
A differenza del puzzle, questo endpoint legge la sua immagine da settings.image. Un campo image di primo livello viene ignorato e la chiamata risponde 400.
L'URL viene salvato così come lo hai inviato e il file non viene mai copiato, quindi deve restare pubblicamente raggiungibile per tutto il tempo in cui l'attività viene giocata.
Impostazioni che legge
Campo
Tipo
Cosa fa
image
obbligatorioin settings
string
string
URL assoluto dell'immagine da mescolare. A differenza di quella del puzzle, questa sta dentro settings.