Um POST por tipo de atividade. Envia o teu conteúdo em JSON e recebes uma atividade na tua conta Puzzel.org e um URL que podes dar aos jogadores ou colocar num iframe.
URL base
https://puzzel.org/api/public/v1
Autenticação
Chave + e-mail no corpo
Endpoints
38 tipos de atividade
Quota
10 atividades por dia
O teu primeiro pedido
Não há nada para instalar nem qualquer negociação prévia: envia um corpo em JSON com a tua chave, o teu e-mail e o teu conteúdo. A resposta traz a chave da nova atividade e o URL onde se joga.
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": "pt",
"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"
}
]
}'
Todos os exemplos desta página são pedidos completos e prontos a executar. Troca a chave e o conteúdo pelos teus e funcionam tal como estão.
Autenticação
Não há cabeçalhos nem bearer token. As duas credenciais viajam no corpo JSON de cada pedido e a chave só é aceite para a conta a que esse e-mail pertence.
Campo
Tipo
O que faz
account_api_key
obrigatório
string
string
A chave de API da tua conta. Vai no corpo, não num cabeçalho.
email
obrigatório
string
string
O endereço com que a tua conta Puzzel.org inicia sessão. A chave só é válida em conjunto com ele.
A tua chave está na secção da conta, no painel, atrás de Mostrar.
Trata a chave como uma palavra-passe. Cria e substitui atividades na tua conta, por isso guarda-a no servidor e fora de tudo o que um navegador possa ler.
O corpo do pedido
Todos os endpoints recebem os mesmos cinco campos. O que muda é o campo de conteúdo por baixo deles: a maioria recebe um array de itens, alguns recebem uma frase ou uma imagem, e o sudoku não recebe nada.
Campo
Tipo
O que faz
account_api_key
obrigatório
string
string
A chave de API da tua conta. Vai no corpo, não num cabeçalho.
email
obrigatório
string
string
O endereço com que a tua conta Puzzel.org inicia sessão. A chave só é válida em conjunto com ele.
title
opcional
string
string
O nome que a atividade recebe no teu painel. Se o deixares de fora, o endpoint usa o nome alternativo dele.
language
opcional
string
string
Só define o idioma no URL que recebes de volta — não traduz nada do que envias. A sopa de letras também o lê para mudar as letras de preenchimento para árabe quando é "ar".
Predefinição: "en"
activity_key
opcional
string
string
Deixa-o de fora para criar uma atividade nova. Se enviares a chave de uma que já te pertence, essa atividade é reconstruída.
settings é um objeto com opções específicas de cada endpoint. As que cada endpoint lê estão listadas com ele mais abaixo; tudo o resto que lá puseres é ignorado.
O que recebes de volta
Uma chamada bem-sucedida responde 200 com a chave da nova atividade e o URL onde se joga. Tudo o resto responde com success a false e uma única string error.
{
"success": false,
"error": "Invalid Email or API Key"
}
O url que recebes de volta é a vista de incorporação. Troca embed por play para a abrir em página inteira, ou por build para a abrir no editor — a chave depois de p= mantém-se igual.
Criar vs. atualizar
Envia activity_key e a atividade correspondente é reconstruída no lugar: o conteúdo é substituído, o nome e a marca de versão são atualizados e a chave em si mantém-se — por isso as ligações e as incorporações que já partilhaste continuam a funcionar. Os resultados, a pasta onde está e todas as definições que o endpoint não escreve ficam como estavam.
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 é aplicado em todas as atualizações, incluindo a predefinição — se o deixares de fora, a atividade passa a ter o nome alternativo desse endpoint.
Os blocos de definições que um endpoint escreve são reescritos de raiz, por isso uma atualização também os repõe nos valores que enviares, ou nas predefinições do endpoint.
Só podes atualizar atividades da tua própria conta. A chave de outra pessoa responde 403.
Uma atualização custa o mesmo que uma criação: uma chamada retirada à quota de hoje.
Limite de pedidos
10
10 atividades por conta por dia
Todas as chamadas bem-sucedidas contam, tanto criações como atualizações. Se passares do limite, o pedido seguinte responde 429 até o contador ser reposto.
O contador é limpo uma vez por dia por uma tarefa agendada, não numa janela móvel de 24 horas.
Erros
Os erros chegam sempre em JSON com os mesmos dois campos, nunca como uma página HTML. A string error está escrita para ser lida por uma pessoa — indica o campo ou o limite que falhou.
Estado
O que significa
400
Bad Request
Falta algo no corpo, está malformado ou fora do intervalo. A mensagem indica o campo.
401
Unauthorized
O e-mail é desconhecido, ou a chave não pertence a essa conta.
403
Forbidden
O activity_key que enviaste pertence a outra conta.
429
Too Many Requests
A quota de hoje está esgotada. É reposta uma vez por dia.
500
Server Error
O gerador não conseguiu criar um quebra-cabeças com o que enviaste — normalmente por serem poucas palavras, ou palavras que não encaixam umas nas outras.
Endpoints
Um caminho por tipo de atividade, todos POST, todos sob o mesmo URL base. Cada um indica o conteúdo de que precisa, as definições que lê e um pedido que podes executar.
Palavras e letras
C
O
R
A
F
I
L
A
S
Palavras cruzadas
Encaixa as tuas respostas numa grelha e numera as definições por ti.
Um array de palavras. Cada entrada junta a resposta à definição que lhe aponta.
Por omissão, fica com o nome “Crossword API”
Vale a pena saber
As respostas com menos de dois carateres são descartadas antes de a grelha ser criada, e pelo menos duas têm de sobreviver a isso.
As respostas passam a maiúsculas e o gerador tem vinte tentativas para as encaixar. Se não conseguir colocar uma única palavra, a chamada responde 500.
Definições que lê
Campo
Tipo
O que faz
hidden_solution
opcionalem settings
string
string
Uma palavra bónus opcional. As letras dela ficam marcadas em células da grelha concluída, para os jogadores as recolherem depois de resolverem as palavras cruzadas, por isso todas as letras dela têm de aparecer nas respostas.
Pedido de exemplo
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": "pt",
"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"
}
]
}'
Um array de palavras. O texto da definição passa a ser a lista de palavras com que os jogadores trabalham.
Por omissão, fica com o nome “Wordseeker API”
Vale a pena saber
As respostas com menos de dois carateres são descartadas, e todas as respostas passam a maiúsculas antes de entrarem na grelha.
A grelha é preenchida com letras latinas, a não ser que language seja "ar", o que muda o preenchimento para árabe.
Definições que lê
Campo
Tipo
O que faz
hidden_solution
opcionalem settings
string
string
As letras que sobram formam isto. Defini-lo também diz ao gerador para encaixar primeiro a solução, em vez de meter o máximo de palavras que conseguir.
directions
opcionalem settings
string[]
string[]
As direções em que uma palavra pode seguir. Se o deixares de fora, as palavras seguem apenas para leste, sudeste e sul.
Um dewesteastnorthsouthnorthwestnortheastsouthwestsoutheast
Predefinição: ["east", "southeast", "south"]
template
opcionalem settings
string
string
Recorta a grelha numa forma, em vez de a deixar quadrada.
Um desquarecirclecrossdiamondpyramidsmileystarcross_plus
Pedido de exemplo
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": "pt",
"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-scrambleDe 1 a 40 em items
Conteúdo
api_c_word_scramble
Por omissão, fica com o nome “Word Scramble API”
Vale a pena saber
As atividades criadas através da API têm sempre a definição de baralhar a ordem ativa, por isso a ordem que envias não é a ordem que os jogadores recebem.
Definições que lê
Campo
Tipo
O que faz
hidden_solution
opcionalem settings
string
string
Uma palavra bónus opcional que os jogadores escrevem depois de resolverem o resto.
Pedido de exemplo
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": "pt",
"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-practiceDe 1 a 50 em items
Conteúdo
api_c_typing_practice
Por omissão, fica com o nome “Typing Practice API”
Pedido de exemplo
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": "pt",
"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"
}
]
}'
Sucesso
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
"message": "Typing Practice created successfully"
}
Um array de palavras-tema. Juntamente com o spangram, as letras delas têm de preencher exatamente uma grelha.
Por omissão, fica com o nome “Strands API”
Vale a pena saber
As letras de todas as palavras e do spangram, em conjunto, têm de somar exatamente 30, 35, 36, 40, 42, 45, 48, 49, 50, 54, 56, 60, 63, 64, 70, 72 ou 80. Qualquer outro total responde 400 e indica quantas letras acrescentar ou retirar.
Definições que lê
Campo
Tipo
O que faz
theme
opcionalem settings
string
string
O enigma mostrado por cima da grelha. Se for deixado de fora, os jogadores veem o título.
spangram
opcionalem settings
string
string
A palavra ou expressão que dá nome ao tema e atravessa a grelha de uma ponta à outra.
POST/api/public/v1/name-them-allDe 1 a 250 em items
Conteúdo
api_c_name_them_all
Por omissão, fica com o nome “Name Them All API”
Vale a pena saber
Uma entrada é um objeto com answer e, opcionalmente, aliases (outras grafias que contam), uma description (a dica) e um group. As maiúsculas, os acentos e a pontuação são ignorados quando um nome é verificado.
Definições que lê
Campo
Tipo
O que faz
list_match_mode
opcionalem settings
string
string
Se um nome conta no momento em que é escrito, ou só com Enter.
Um dewhile_typingon_enter
Predefinição: "while_typing"
list_slot_hint
opcionalem settings
string
string
O que uma casa vazia revela: nada, o comprimento do nome, a primeira letra, ou a dica que escreveste.
Um denonelengthfirst_letterhint
Predefinição: "none"
list_arrange
opcionalem settings
string
string
Uma coluna por grupo, ou uma só lista.
Um degroupsone_list
Predefinição: "groups"
list_allow_give_up
opcionalem settings
boolean
boolean
Mostra um botão de desistir que termina a ronda e revela o que ficou por dizer.
{
"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"
}
Um array de pares. Cada par contém os dois cartões que pertencem um ao outro.
Por omissão, fica com o nome “Memory Game API”
Vale a pena saber
Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
POST/api/public/v1/matching-pairsDe 2 a 30 em items
Conteúdo
api_c_matching_pairs
Por omissão, fica com o nome “Matching Game API”
Vale a pena saber
Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
O endpoint guarda tantos cartões quantos enviares, por isso envia exatamente dois por entrada — primeiro a frente, depois o verso.
Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
POST/api/public/v1/categorizePelo menos 2 em items · No máximo 60 cartões, ao todo
Conteúdo
Um array de categorias, cada uma com um nome e os cartões que lhe pertencem.
Por omissão, fica com o nome “Categorize Game API”
Vale a pena saber
Uma categoria enviada sem nome é guardada como “Untitled Category”, por isso envia sempre um.
Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
POST/api/public/v1/reorderPelo menos 1 em items · No máximo 60 cartões, ao todo
Conteúdo
Um array de sequências. Cada uma contém os cartões pela ordem correta.
Por omissão, fica com o nome “Reorder Game API”
Vale a pena saber
A ordem que envias é guardada como a ordem correta — o número um primeiro.
Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
Um array de itens a partir dos quais os cartões são sorteados. Envia claramente mais itens do que as casas de um cartão, para que os cartões sejam diferentes.
Por omissão, fica com o nome “Bingo API”
Vale a pena saber
Um item é um objeto com um value e, opcionalmente, um type ("text", "image" ou "audio" com um URL em value), uma description (a pista que o anfitrião lê em voz alta no modo de pistas) e alt.
Definições que lê
Campo
Tipo
O que faz
mode
opcionalem settings
string
string
O que preenche as casas: os teus itens, os teus itens anunciados pela pista deles, ou simples números (que não precisam de itens).
Um deitemscluesnumbers
Predefinição: "items"
rows
opcionalem settings
number
number
Linhas de cada cartão, de 2 a 5.
Predefinição: 3
columns
opcionalem settings
number
number
Colunas de cada cartão, de 2 a 5.
Predefinição: 3
highest_number
opcionalem settings
number
number
No modo de números, os cartões são preenchidos de 1 até este número, 100 no máximo. É uma funcionalidade dos planos: sem plano, fica em 50.
Predefinição: 50
Pedido de exemplo
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": "pt",
"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"
}
Um array de cartões. Os cartões que fazem parte do código levam o lugar que ocupam nele.
Por omissão, fica com o nome “Keypad API”
Vale a pena saber
Um cartão é um objeto com um value e, opcionalmente, um type ("text", "image" ou "audio" com um URL em value), alt e code_position: o lugar dele no código, sendo 1 o primeiro. Um cartão só pode estar uma vez no código, e pelo menos um cartão tem de estar.
Definições que lê
Campo
Tipo
O que faz
instructions
opcionalem settings
string
string
A pergunta ou o enigma a que o código responde, mostrado com os cartões.
force_solution_in_correct_order
opcionalem settings
boolean
boolean
Os cartões têm de ser premidos por ordem. Desligado, qualquer ordem dos cartões certos abre o cadeado.
Predefinição: false
randomize_order
opcionalem settings
boolean
boolean
Cada jogador recebe os cartões numa disposição baralhada.
Um array de quartetos. Cada um tem um nome e exatamente quatro cartões.
Por omissão, fica com o nome “Quartets API”
Vale a pena saber
Um cartão é um nome, ou um objeto com um name e uma description (o facto mostrado nele). Nenhum nome de cartão pode aparecer duas vezes no jogo: os jogadores pedem os cartões pelo nome.
Definições que lê
Campo
Tipo
O que faz
type
opcionalem settings
string
string
Um jogo simples, ou um jogo de aprendizagem em que cada cartão mostra um facto. Se for deixado de fora, é learn quando algum cartão tem uma description.
Um denormallearn
Pedido de exemplo
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": "pt",
"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"
}
}'
Sucesso
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/quartets/embed?p=-Nq8sample_activity_key",
"message": "Quartets game created successfully"
}
Um array de perguntas. As perguntas de escolha múltipla levam as respetivas respostas; as de resposta aberta levam a resposta que aceitas.
Por omissão, fica com o nome “Quiz API”
Vale a pena saber
question_type é "multiple_choice", em que a opção certa leva isCorrect a true; "true_false", o mesmo mas com exatamente duas opções, true primeiro e false depois; ou "open_answer", que usa antes correct_answer. Se for deixado de fora, é tratado como escolha múltipla.
O endpoint do quiz passa settings diretamente como blocos de definições da atividade, por isso não é sítio para opções soltas — ajusta o quiz no editor depois.
Pedido de exemplo
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": "pt",
"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", em que a opção certa leva isCorrect a true; "true_false", o mesmo mas com exatamente duas opções, true primeiro e false depois; ou "open_answer", que usa antes correct_answer. Se for deixado de fora, é tratado como escolha múltipla.
Definições que lê
Campo
Tipo
O que faz
number_of_tiles
opcionalem settings
number
number
Quantas casas tem o tabuleiro. Entre 10 e 75.
Predefinição: 30
game_mode
opcionalem settings
string
string
Se os jogadores correm até à meta ou recolhem itens pelo caminho.
Um derace_to_finishcollect_items
Predefinição: "race_to_finish"
Pedido de exemplo
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": "pt",
"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"
}
}'
Sucesso
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
"message": "Board Game created successfully"
}
Um array de perguntas de escolha múltipla ou de verdadeiro ou falso, exatamente com a forma que o endpoint do quiz recebe. As perguntas abertas são recusadas: uma porta precisa de uma resposta escrita nela.
Por omissão, fica com o nome “Maze API”
Definições que lê
Campo
Tipo
O que faz
maze_width
opcionalem settings
string
string
Como as salas ficam dispostas: numa coluna, num quadrado, ou mais largas.
Um denarrownormalwide
Predefinição: "normal"
maze_corridors
opcionalem settings
string
string
Quanto labirinto há entre duas perguntas.
Um deshortnormallong
Predefinição: "normal"
maze_fog
opcionalem settings
string
string
Mostra o labirinto todo, ou só o que o jogador já viu de perto.
Um deoffnear
Predefinição: "off"
maze_wrong_door_pause
opcionalem settings
string
string
Quanto tempo as portas ficam fechadas depois de uma errada.
Um denoneshortlong
Predefinição: "short"
maze_walk_there
opcionalem settings
boolean
boolean
Oferece um botão que leva o peão até à sala seguinte.
Predefinição: false
maze_seed
opcionalem settings
string
string
A semente a partir da qual o labirinto é gerado. A mesma semente e as mesmas perguntas dão o mesmo labirinto; se for deixada de fora, é sorteado um novo.
Pedido de exemplo
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": "pt",
"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"
}
}'
Um array de categorias, da esquerda para a direita. Cada uma tem um nome e as respetivas definições, da linha de cima para baixo.
Por omissão, fica com o nome “Jeopardy API”
Vale a pena saber
Uma definição é uma pergunta tal como o endpoint do quiz a recebe, open_answer a não ser que diga outra coisa, com correct_answer e, opcionalmente, aliases. Pode também levar value (o valor dela) e daily_double. null deixa uma célula vazia.
Definições que lê
Campo
Tipo
O que faz
jeopardy_buzzer_mode
opcionalem settings
string
string
Quem joga e como: o anfitrião gere tudo a partir da consola, os jogadores tocam a campainha pelo telemóvel, ou cada jogador joga o quadro sozinho.
Um dehostphonessolo
Predefinição: "host"
jeopardy_contestants
opcionalem settings
string
string
Se a consola fala de equipas ou de jogadores.
Um deteamsplayers
Predefinição: "teams"
jeopardy_value_step
opcionalem settings
number
number
Quanto vale uma linha: uma definição vale este valor vezes o número da linha. De 50 a 500, em passos de 50.
Predefinição: 100
jeopardy_answer_time
opcionalem settings
number
number
Segundos para responder depois de uma definição abrir, até 300. 0 é sem relógio.
Predefinição: 20
jeopardy_wrong_answer_costs
opcionalem settings
boolean
boolean
Uma resposta errada tira o valor da definição à pontuação.
Predefinição: false
jeopardy_reveal_on_timeout
opcionalem settings
boolean
boolean
O quadro mostra ele próprio a resposta quando o tempo acaba.
Predefinição: false
jeopardy_require_question_form
opcionalem settings
boolean
boolean
Lembra os jogadores de responderem sob a forma de pergunta.
Predefinição: false
Pedido de exemplo
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": "pt",
"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-videoDe 1 a 50 em items
Conteúdo
api_c_interactive_video
Por omissão, fica com o nome “Interactive Video API”
Vale a pena saber
Um popup é um objeto com time (segundos, ou "1:23"), kind ("question", a não ser que diga "note", "think" ou "chapter") e description. Uma pergunta é uma pergunta tal como o endpoint do quiz a recebe e pode levar rewind_to: o ponto a partir do qual o vídeo recomeça depois de uma resposta errada.
Definições que lê
Campo
Tipo
O que faz
video_url
obrigatórioem settings
string
string
O vídeo: uma página do YouTube, do Vimeo ou do Bunny Stream, ou uma ligação direta para um ficheiro mp4, webm ou mov.
video_duration
opcionalem settings
number
number
A duração do vídeo em segundos. Quando indicada, um popup depois do fim é recusado.
Pedido de exemplo
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": "pt",
"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
}
}'
Sucesso
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/interactive-video/embed?p=-Nq8sample_activity_key",
"message": "Interactive video created successfully"
}
Uma frase, no campo sentence. Este endpoint não recebe items.
Por omissão, fica com o nome “Calculation Game API”
Vale a pena saber
Se as restrições forem demasiado apertadas para codificar a frase, a chamada responde 400 a pedir que as alargues, em vez de guardar um quebra-cabeças incompleto.
Definições que lê
Campo
Tipo
O que faz
sentence
obrigatório
string
string
A frase que os jogadores descobrem ao resolver as contas.
difficulty_level
opcionalem settings
number
number
O resultado mais alto que uma conta pode ter.
Um de20501001000
Predefinição: "100"
operators
opcionalem settings
string[]
string[]
Que operações podem aparecer. x é multiplicar, : é dividir.
Um de+-x:
Predefinição: ["+", "-", "x", ":"]
max_operations
opcionalem settings
number
number
Quantas operações uma conta pode encadear.
Um de123
Predefinição: 1
number_difficulty
opcionalem settings
number
number
Limita os números individuais dentro de uma conta. De 5 a 1000.
Nada. O quebra-cabeças inteiro sai das duas definições dele.
Por omissão, fica com o nome “Sudoku API”
Vale a pena saber
Não envies items nem sentence — size e difficulty são toda a entrada.
O editor só oferece a dificuldade para 2x3, 3x3 e 3x4. A API aplica-a a todos os tamanhos, incluindo 2x2 e 4x4.
Definições que lê
Campo
Tipo
O que faz
size
opcionalem settings
string
string
O tamanho de um bloco, escrito como linhas por colunas — 3x3 dá a grelha clássica de 9x9. O endpoint só verifica se é interpretável como dois números, por isso fica-te pelos tamanhos que o editor oferece.
POST/api/public/v1/fill-in-the-gapDe 1 a 50 em items
Conteúdo
api_c_fill_in_the_gap
Por omissão, fica com o nome “Fill in the gap API”
Vale a pena saber
Escreve a frase completa e põe asteriscos à volta de cada palavra a omitir: "Water boils at *100* degrees." Várias palavras dentro de um mesmo par formam uma só lacuna. Uma entrada pode também levar uma instrução mostrada por cima da frase.
Pedido de exemplo
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": "pt",
"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."
}
]
}'
Sucesso
{
"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"
}
Um array de frases. Cada palavra a etiquetar escreve-se como [word](label).
Por omissão, fica com o nome “Sentence analysis API”
Vale a pena saber
Escreve uma frase como "The [dog](noun) [barks](verb)." As palavras sem etiqueta são mostradas, mas não são perguntadas. As etiquetas noun, verb, adjective e subject são mostradas a cada jogador no idioma dele.
Definições que lê
Campo
Tipo
O que faz
categories
opcionalem settings
string[]
string[]
As etiquetas entre as quais os jogadores escolhem, por ordem. Se for deixado de fora, são as etiquetas usadas nas frases. Envia-o para acrescentar uma etiqueta que nenhuma palavra leva, ou para acertar a ordem.
Pedido de exemplo
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": "pt",
"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-puzzlePelo menos 3 em items
Conteúdo
api_c_logic_puzzle
Por omissão, fica com o nome “Logic Puzzle API”
Vale a pena saber
Todas as categorias precisam do mesmo número de itens, de 3 a 6, todos diferentes. Uma categoria pode ser marcada como ordered (preços, horas, idades), com uma unit opcional, o que permite ao gerador escrever pistas sobre mais, menos e quanto.
Definições que lê
Campo
Tipo
O que faz
story
opcionalem settings
string
string
A história de fundo mostrada por cima das pistas.
difficulty
opcionalem settings
string
string
Que tipos de pista o gerador pode usar.
Um deeasymediumhard
Predefinição: "easy"
hints
opcionalem settings
boolean
boolean
Oferece um botão que mostra o passo seguinte.
Predefinição: true
auto_cross
opcionalem settings
boolean
boolean
Marcar uma correspondência risca o resto da linha e da coluna dela.
Predefinição: true
clue_mode
opcionalem settings
string
string
Quem escreve as pistas que os jogadores veem: geradas a partir da tabela, as tuas próprias frases em free_clues, ou nenhuma.
Um degeneratedfreenone
Predefinição: "generated"
free_clues
opcionalem settings
string[]
string[]
As tuas próprias frases de pista, mostradas tal como as escreveres, com clue_mode "free". Nada as verifica.
Pedido de exemplo
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": "pt",
"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-huntDe 1 a 50 em items
Conteúdo
api_c_scavenger_hunt
Por omissão, fica com o nome “Scavenger Hunt API”
Vale a pena saber
Uma etapa é um objeto com title, description, code e, opcionalmente, accepted_codes (outras grafias que contam), url e link_text. Um código é verificado sem distinguir maiúsculas de minúsculas nem espaços. O mapa com marcadores só pode ser acrescentado no editor.
Pedido de exemplo
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": "pt",
"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-reasoningDe 1 a 50 em items
Conteúdo
api_c_spatial_reasoning
Por omissão, fica com o nome “Spatial Reasoning API”
Vale a pena saber
Os objetos e os alvos são square, triangle, circle, hexagon, pentagon, star, diamond ou heart. As relações são inside, outside, behind, in_front_of, right_of, left_of, above, below, same_color_as, different_color_from, larger_than e smaller_than. Uma regra que nunca pode ser cumprida responde 400.
Um array de frases. Cada uma lista as palavras desenhadas como imagens; todas as outras palavras ficam em letras.
Por omissão, fica com o nome “Rebus API”
Vale a pena saber
Uma palavra é desenhada a partir de partes que, juntas, a escrevem. Uma parte tem as letras que representa (text), um emoji, e shows: a palavra para o que a imagem mostra ("broom" para uma imagem que representa "room"). O Puzzel calcula as mudanças de letras. Uma parte pode ser antes um símbolo, como 4 para "for".
Definições que lê
Campo
Tipo
O que faz
rebus_commas
opcionalem settings
boolean
boolean
Desenha uma primeira ou última letra retirada como uma vírgula ao lado da imagem.
Um URL de imagem, no campo image. Este endpoint não recebe items.
Por omissão, fica com o nome “Jigsaw Game API”
Vale a pena saber
A API cria sempre um puzzle de 4 por 4. O número de peças, as peças irregulares e os bordos direitos são definições do editor — enviar rows ou columns aqui não faz nada.
O URL é guardado tal como o enviaste e o ficheiro nunca é copiado, por isso tem de continuar publicamente acessível enquanto a atividade for jogada.
Definições que lê
Campo
Tipo
O que faz
image
obrigatório
string
string
URL absoluto da imagem a cortar. Enviado no nível superior, não dentro de settings.