Vai al contenuto
API per sviluppatori

Crea attività dal tuo sistema

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
20 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"
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

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.

CampoTipoCosa fa
account_api_key
obbligatorio
string
stringLa chiave API del tuo account. Va nel corpo, non in un header.
email
obbligatorio
string
stringL'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.

Accedi

Le chiavi API vengono assegnate quando inizia un abbonamento, quindi un account gratuito non ne ha ancora una.

Guarda i piani

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.

CampoTipoCosa fa
account_api_key
obbligatorio
string
stringLa chiave API del tuo account. Va nel corpo, non in un header.
email
obbligatorio
string
stringL'indirizzo con cui accedi al tuo account Puzzel.org. La chiave è valida solo insieme a esso.
title
facoltativo
string
stringIl nome dell'attività nella dashboard. Se ometti questo campo, viene usato il nome predefinito dell'endpoint.
language
facoltativo
string
stringImposta la lingua dell'URL restituito, senza tradurre i contenuti inviati. Per il crucipuzzle, il valore "ar" seleziona anche le lettere arabe con cui riempire le caselle libere.
Predefinito: "en"
activity_key
facoltativo
string
stringOmetterlo 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.

Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
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.

StatoCosa 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

Cruciverba

Incastra le tue risposte in una griglia e numera le definizioni al posto tuo.

#
POST /api/public/v1/crossword Almeno 2 in items
Contenuti

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.
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"
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Apri l'editor Torna su

Crucipuzzle

Nasconde le tue parole in una griglia di lettere, nelle direzioni e nella forma che scegli.

#
POST /api/public/v1/wordseeker Almeno 2 in items
Contenuti

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
CampoTipoCosa fa
hidden_solution
facoltativo in settings
string
stringLe 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
facoltativo in 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 tra westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Predefinito: ["east", "southeast", "south"]
template
facoltativo in settings
string
stringRitaglia la griglia in una forma invece di lasciarla quadrata.
Uno tra squarecirclecrossdiamondpyramidsmileystarcross_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"
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Apri l'editor Torna su

Acrostico

Impila le tue risposte in modo che una colonna componga una parola nascosta.

#
POST /api/public/v1/acrostic Almeno 1 in items
Contenuti

Un array di parole. Tutte insieme devono fornire ogni lettera della parola nascosta.

Ripiega sul nome “Acrostic API”

Da sapere
  • Se le risposte non forniscono le lettere che servono alla soluzione, la chiamata risponde 500 invece di salvare una griglia a metà.
  • Il generatore riordina le tue risposte perché la colonna funzioni, quindi l'ordine che invii non è l'ordine che vedono i giocatori.
Impostazioni che legge
CampoTipoCosa fa
hidden_solution
obbligatorio in settings
string
stringLa parola composta dalla colonna evidenziata. Senza, questo endpoint non funziona.
Richiesta di esempio
POST acrostic 
curl -X POST https://puzzel.org/api/public/v1/acrostic \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Acrostic",
  "language": "it",
  "items": [
    {
      "answer": "PEACH",
      "description": "Fuzzy skin, sweet flesh",
      "type": "text"
    },
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "PLUM"
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Apri l'editor Torna su

Parole mescolate

api_e_word_scramble

#
POST /api/public/v1/word-scramble Almeno 1 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
CampoTipoCosa fa
hidden_solution
facoltativo in settings
string
stringUna 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"
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Apri l'editor Torna su

Impiccato

Trasforma le tue parole o frasi in partite in cui si indovinano le lettere.

#
POST /api/public/v1/hangman Almeno 1 in items
Contenuti

Un array di parole o frasi brevi. L'indizio è il suggerimento che vedono i giocatori.

Ripiega sul nome “Hangman API”

Richiesta di esempio
POST hangman 
curl -X POST https://puzzel.org/api/public/v1/hangman \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Hangman",
  "language": "it",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Apri l'editor Torna su

Wordle

Trasforma ogni parola che invii in una partita in cui indovinare la parola.

#
POST /api/public/v1/wordle Almeno 1 in items
Contenuti

Un array di parole. I giocatori fanno un round per ogni parola.

Ripiega sul nome “Wordle API”

Da sapere
  • Il controllo delle parole nel dizionario è attivo nelle attività create dall'API. Disattivalo nell'editor se usi nomi propri o parole inventate.
Richiesta di esempio
POST wordle 
curl -X POST https://puzzel.org/api/public/v1/wordle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordle",
  "language": "it",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Apri l'editor Torna su

Esercizio di digitazione

api_e_typing_practice

#
POST /api/public/v1/typing-practice Almeno 1 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"
}
Apri l'editor Torna su

Ruota della fortuna

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Almeno 1 in items
Contenuti

api_c_wheel_of_fortune

Ripiega sul nome “Wheel of Fortune API”

Da sapere
  • Creata con “mostra il risultato solo nella ruota”, così il risultato si legge sulla ruota invece di essere annunciato accanto.
Richiesta di esempio
POST wheel-of-fortune 
curl -X POST https://puzzel.org/api/public/v1/wheel-of-fortune \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wheel of Fortune",
  "language": "it",
  "items": [
    {
      "answer": "Read a page aloud",
      "description": "Segment 1",
      "type": "text"
    },
    {
      "answer": "Name three fruits",
      "description": "Segment 2",
      "type": "text"
    },
    {
      "answer": "Spell it backwards",
      "description": "Segment 3",
      "type": "text"
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wheel-of-fortune/embed?p=-Nq8sample_activity_key",
  "message": "Wheel of Fortune created successfully"
}
Apri l'editor Torna su
Carte e coppie

Memory

Carte coperte da girare e abbinare a coppie.

#
POST /api/public/v1/memory Almeno 2 in items
Contenuti

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.
Richiesta di esempio
POST memory 
curl -X POST https://puzzel.org/api/public/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Memory Game",
  "language": "it",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Apri l'editor Torna su

Gioco dei collegamenti

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Almeno 2 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.
Richiesta di esempio
POST matching-pairs 
curl -X POST https://puzzel.org/api/public/v1/matching-pairs \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Matching Game",
  "language": "it",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Apri l'editor Torna su

Carte di ripasso

api_e_flash_cards

#
POST /api/public/v1/flash-cards Almeno 1 in items
Contenuti

api_c_flash_cards

Ripiega sul nome “Flash Cards API”

Da sapere
  • 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.
Richiesta di esempio
POST flash-cards 
curl -X POST https://puzzel.org/api/public/v1/flash-cards \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Flash Cards",
  "language": "it",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Apri l'editor Torna su

Gioco delle categorie

Carte da smistare nella categoria a cui appartengono.

#
POST /api/public/v1/categorize Almeno 2 in items
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.
Richiesta di esempio
POST categorize 
curl -X POST https://puzzel.org/api/public/v1/categorize \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Categorize Game",
  "language": "it",
  "items": [
    {
      "name": "Red fruits",
      "cards": [
        {
          "type": "text",
          "value": "Strawberry"
        },
        {
          "type": "text",
          "value": "Cherry"
        }
      ]
    },
    {
      "name": "Yellow fruits",
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "Lemon"
        }
      ]
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Apri l'editor Torna su

Riordino

Una sequenza che i giocatori devono rimettere in ordine.

#
POST /api/public/v1/reorder Almeno 1 in items
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.
Richiesta di esempio
POST reorder 
curl -X POST https://puzzel.org/api/public/v1/reorder \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Reorder Game",
  "language": "it",
  "items": [
    {
      "name": "From seed to fruit",
      "cards": [
        {
          "type": "text",
          "value": "Plant the seed"
        },
        {
          "type": "text",
          "value": "Water it"
        },
        {
          "type": "text",
          "value": "Watch it grow"
        },
        {
          "type": "text",
          "value": "Pick the fruit"
        }
      ]
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Apri l'editor Torna su
Domande e risposte

Quiz

Domande a scelta multipla e aperte, con il punteggio calcolato mentre si gioca.

#
POST /api/public/v1/quiz Almeno 1 in items
Contenuti

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, 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."
    }
  ]
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Apri l'editor Torna su

Gioco da tavolo

api_e_board_game

#
POST /api/public/v1/board-game Almeno 1 in items
Contenuti

api_c_board_game

Ripiega sul nome “Board Game API”

Da sapere
  • question_type è "multiple_choice", dove l'opzione giusta ha isCorrect true, oppure "open_answer", che usa invece correct_answer. Se lo ometti, viene trattata come scelta multipla.
Impostazioni che legge
CampoTipoCosa fa
number_of_tiles
facoltativo in settings
number
numberQuante caselle ha il tabellone. Tra 10 e 75.
Predefinito: 30
game_mode
facoltativo in settings
string
stringSe i giocatori corrono al traguardo o raccolgono oggetti lungo il percorso.
Uno tra race_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"
}
Apri l'editor Torna su
Frasi e numeri

Crittogramma

Trasforma una frase in un codice da decifrare, un carattere alla volta.

#
POST /api/public/v1/cryptogram Non accetta items
Contenuti

Una sola frase, nel campo sentence. Questo endpoint non accetta items.

Ripiega sul nome “Cryptogram API”

Da sapere
  • Tutto quello che invii in items viene ignorato — il rompicapo si costruisce solo dalla frase.
Impostazioni che legge
CampoTipoCosa fa
sentence
obbligatorio
string
stringLa frase da cifrare. I giocatori la decodificano carattere per carattere.
helpers
facoltativo in settings
string
stringLe lettere da rivelare all'inizio per aiutare i giocatori: nessuna, le più frequenti, le vocali oppure una selezione personalizzata.
Uno tra nonemost_commonvowelscustom
Predefinito: "none"
character_list
facoltativo in settings
string
stringL'alfabeto su cui si basa il cifrario. Se lo lasci vuoto, la cifratura ne sceglie uno da sé.
extra_letters
facoltativo in settings
string
stringI caratteri svelati quando helpers è "custom". Ignorato con le altre modalità di aiuto.
hide_unused_characters
facoltativo in settings
boolean
booleanTiene fuori dalla chiave di cifratura i caratteri che la frase non usa mai.
Predefinito: false
Richiesta di esempio
POST cryptogram 
curl -X POST https://puzzel.org/api/public/v1/cryptogram \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Cryptogram",
  "language": "it",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Apri l'editor Torna su

Esercizio di calcolo

Nasconde una frase dietro dei calcoli — risolvi il calcolo, scopri la lettera.

#
POST /api/public/v1/calculation Non accetta items
Contenuti

Una sola frase, nel campo sentence. Questo endpoint non accetta items.

Ripiega sul nome “Calculation Game API”

Da sapere
  • Se i vincoli sono troppo stretti per codificare la frase, la chiamata risponde 400 e ti chiede di allentarli, invece di salvare un rompicapo a metà.
Impostazioni che legge
CampoTipoCosa fa
sentence
obbligatorio
string
stringLa frase che i giocatori scoprono risolvendo i calcoli.
difficulty_level
facoltativo in settings
number
numberIl risultato più alto che un calcolo può avere.
Uno tra 20501001000
Predefinito: "100"
operators
facoltativo in settings
string[]
string[]Quali operazioni possono comparire. x è la moltiplicazione, : la divisione.
Uno tra +-x:
Predefinito: ["+", "-", "x", ":"]
max_operations
facoltativo in settings
number
numberQuante operazioni può concatenare un singolo calcolo.
Uno tra 123
Predefinito: 1
number_difficulty
facoltativo in settings
number
numberLimita i singoli numeri all'interno di un calcolo. Da 5 a 1000.
Predefinito: 100
Richiesta di esempio
POST calculation 
curl -X POST https://puzzel.org/api/public/v1/calculation \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Calculation Game",
  "language": "it",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Apri l'editor Torna su

Sudoku

Genera una griglia risolta, poi ne toglie di nuovo dei numeri.

#
POST /api/public/v1/sudoku Non accetta items
Contenuti

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
CampoTipoCosa fa
size
facoltativo in settings
string
stringLa 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 tra 2x22x33x33x44x4
Predefinito: "3x3"
difficulty_level
facoltativo in settings
string
stringQuanti numeri restano sulla griglia come punto di partenza.
Uno tra easynormalhard
Predefinito: "normal"
Richiesta di esempio
POST sudoku 
curl -X POST https://puzzel.org/api/public/v1/sudoku \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sudoku",
  "language": "it",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Apri l'editor Torna su
Immagini

Puzzle

Taglia un'immagine in pezzi da ricomporre trascinandoli.

#
POST /api/public/v1/jigsaw Non accetta items
Contenuti

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
CampoTipoCosa fa
image
obbligatorio
string
stringURL assoluto dell'immagine da tagliare. Va inviato al primo livello, non dentro settings.
Richiesta di esempio
POST jigsaw 
curl -X POST https://puzzel.org/api/public/v1/jigsaw \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Jigsaw Game",
  "language": "it",
  "image": "https://example.com/orchard.jpg"
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Apri l'editor Torna su

Rompicapo scorrevole

Mescola un'immagine in tessere che scorrono al loro posto.

#
POST /api/public/v1/slidingpuzzle Non accetta items
Contenuti

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
CampoTipoCosa fa
image
obbligatorio in settings
string
stringURL assoluto dell'immagine da mescolare. A differenza di quella del puzzle, questa sta dentro settings.
Richiesta di esempio
POST slidingpuzzle 
curl -X POST https://puzzel.org/api/public/v1/slidingpuzzle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sliding Puzzle",
  "language": "it",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Successo 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Apri l'editor Torna su

Qualcosa non funziona come dovrebbe?

Inviaci la richiesta che hai provato, senza la chiave API, e il messaggio di errore ricevuto. Ti risponderà direttamente chi ha sviluppato l'endpoint.

Scrivi all'assistenza