Um POST para cada tipo de atividade. Envie seu conteúdo em JSON e receba de volta uma atividade na sua conta do Puzzel.org e uma URL que você pode entregar aos jogadores ou colocar em um iframe.
URL base
https://puzzel.org/api/public/v1
Autenticação
Chave + e-mail no corpo
Endpoints
38 tipos de atividade
Cota
10 atividades por dia
Sua primeira requisição
Nada para instalar e nenhum handshake: envie um corpo JSON com sua chave, seu e-mail e seu conteúdo. A resposta traz a chave da nova atividade e a URL onde ela é jogada.
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": "br",
"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"
}
]
}'
Todo exemplo nesta página é uma requisição completa e executável. Basta trocar pela sua própria chave e conteúdo, e funciona sem alterações.
Autenticação
Não há headers nem bearer token. As duas credenciais viajam no corpo JSON de cada requisição, e a chave só é aceita para a conta à qual aquele e-mail pertence.
Campo
Tipo
O que faz
account_api_key
obrigatório
string
string
A chave de API da sua conta. Ela vai no corpo, não em um header.
email
obrigatório
string
string
O endereço com o qual sua conta do Puzzel.org entra. A chave só é válida junto com ele.
Sua chave fica na seção de conta do seu painel, atrás de Mostrar.
Trate a chave como uma senha. Ela cria e sobrescreve atividades na sua conta, então mantenha-a no servidor e fora de qualquer coisa que um navegador possa ler.
O corpo da requisição
Todo endpoint recebe os mesmos cinco campos. O que muda é o campo de conteúdo abaixo deles: a maioria recebe um array de items, alguns recebem uma sentence ou uma image, e o sudoku não recebe nada.
Campo
Tipo
O que faz
account_api_key
obrigatório
string
string
A chave de API da sua conta. Ela vai no corpo, não em um header.
email
obrigatório
string
string
O endereço com o qual sua conta do Puzzel.org entra. A chave só é válida junto com ele.
title
opcional
string
string
O nome que a atividade recebe no seu painel. Deixe de fora e o endpoint usa seu próprio nome padrão.
language
opcional
string
string
Decide apenas o locale na URL que você recebe de volta — não traduz nada do que você envia. O caça-palavras também usa esse campo para trocar as letras de preenchimento para árabe quando o valor é "ar".
Padrão: "en"
activity_key
opcional
string
string
Deixe de fora para criar uma nova atividade. Informe a chave de uma que você já possui e essa atividade é reconstruída em vez disso.
settings é um objeto com opções específicas de cada endpoint. Quais delas um endpoint lê está listado logo abaixo; qualquer outra coisa que você colocar ali é ignorada.
O que volta
Uma chamada bem-sucedida responde 200 com a chave da nova atividade e a URL onde ela é jogada. Qualquer outra coisa responde com success definido como false e uma única string de erro.
{
"success": false,
"error": "Invalid Email or API Key"
}
A url que você recebe é a visualização de incorporação. Troque embed por play para abri-la em página inteira, ou por build para abri-la no editor — a chave depois de p= permanece a mesma.
Criar x atualizar
Envie activity_key e a atividade por trás dela é reconstruída no lugar: o conteúdo é substituído, o nome e o carimbo de versão são atualizados, e a própria chave permanece a mesma — então links e incorporações que você já compartilhou continuam funcionando. Resultados, posição na pasta e toda configuração que o endpoint não escreve por conta própria permanecem 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 toda atualização, inclusive seu padrão — deixe de fora e a atividade é renomeada para o nome padrão daquele endpoint.
Os blocos de configuração que um endpoint escreve por conta própria são reescritos do zero, então uma atualização também os redefine para os valores que você envia, ou para os padrões do endpoint.
Você só pode atualizar atividades que a sua própria conta possui. A chave de outra pessoa responde 403.
Uma atualização custa o mesmo que uma criação: uma chamada a menos na cota de hoje.
Limite de taxa
10
10 atividades por conta por dia
Toda chamada bem-sucedida conta, tanto criações quanto atualizações. Ultrapasse o limite e a próxima requisição responde 429 até o contador ser zerado.
O contador é zerado uma vez por dia por uma tarefa agendada, não em uma janela contínua de 24 horas.
Erros
Erros sempre chegam como JSON com os mesmos dois campos, nunca como uma página HTML. A string de erro é escrita para ser lida por uma pessoa — ela nomeia o campo ou o limite que falhou.
Status
O que significa
400
Bad Request
Algo no corpo está faltando, malformado ou fora do intervalo. A mensagem nomeia o campo.
401
Unauthorized
O e-mail é desconhecido, ou a chave não pertence àquela conta.
403
Forbidden
A activity_key que você enviou pertence a uma conta diferente.
429
Too Many Requests
A cota de hoje foi esgotada. Ela é zerada uma vez por dia.
500
Server Error
O gerador não conseguiu montar um passatempo a partir do que você enviou — geralmente poucas palavras, ou palavras que não se encaixam.
Endpoints
Um caminho para cada tipo de atividade, todos POST, todos sob a mesma URL base. Cada um lista o conteúdo que precisa, as configurações que lê e uma requisição que você pode executar.
Palavras e letras
M
E
L
E
A
S
A
S
A
Palavras cruzadas
Encaixa suas respostas em uma grade e numera as definições para você.
Um array de palavras. Cada item combina a resposta com a definição que aponta para ela.
Usa como padrão o nome “Crossword API”
Vale saber
Respostas com menos de dois caracteres são descartadas antes da grade ser montada, e pelo menos duas precisam sobrar depois disso.
As respostas são colocadas em maiúsculas e o gerador tem vinte tentativas para encaixá-las. Se não conseguir posicionar uma única palavra, a chamada responde 500.
Configurações que lê
Campo
Tipo
O que faz
hidden_solution
opcionalem settings
string
string
Uma palavra bônus opcional. Suas letras são marcadas em casas da grade pronta, para os jogadores coletarem quando as palavras cruzadas forem resolvidas, então todas as letras dela precisam aparecer nas respostas.
Exemplo de requisição
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": "br",
"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 se torna a lista de palavras que os jogadores usam.
Usa como padrão o nome “Wordseeker API”
Vale saber
Respostas com menos de dois caracteres são descartadas, e toda resposta é colocada em maiúsculas antes de entrar na grade.
A grade é preenchida com letras latinas, a menos que language seja "ar", o que troca o preenchimento para árabe.
Configurações que lê
Campo
Tipo
O que faz
hidden_solution
opcionalem settings
string
string
As letras restantes formam isso. Defini-lo também diz ao gerador para encaixar a solução primeiro, em vez de tentar caber o máximo de palavras possível.
directions
opcionalem settings
string[]
string[]
Em quais direções uma palavra pode correr. Deixe de fora e as palavras correm apenas para leste, sudeste e sul.
Um dewesteastnorthsouthnorthwestnortheastsouthwestsoutheast
Padrão: ["east", "southeast", "south"]
template
opcionalem settings
string
string
Recorta a grade em um formato, em vez de deixá-la quadrada.
Um desquarecirclecrossdiamondpyramidsmileystarcross_plus
Exemplo de requisição
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": "br",
"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
Usa como padrão o nome “Word Scramble API”
Vale saber
Atividades criadas pela API sempre têm a configuração de embaralhar a ordem ativada, então a ordem que você envia não é a ordem que os jogadores recebem.
Configurações que lê
Campo
Tipo
O que faz
hidden_solution
opcionalem settings
string
string
Uma palavra bônus opcional que os jogadores digitam depois de resolver o restante.
Exemplo de requisição
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": "br",
"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
Usa como padrão o nome “Typing Practice API”
Exemplo de requisição
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": "br",
"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. Junto com o spangram, as letras delas precisam preencher a grade exatamente.
Usa como padrão o nome “Strands API”
Vale saber
As letras de todas as palavras e do spangram juntas precisam somar exatamente 30, 35, 36, 40, 42, 45, 48, 49, 50, 54, 56, 60, 63, 64, 70, 72 ou 80. Qualquer outra quantidade responde 400 e diz quantas letras acrescentar ou remover.
Configurações que lê
Campo
Tipo
O que faz
theme
opcionalem settings
string
string
O enigma exibido acima da grade. Se for omitido, os jogadores veem o título.
spangram
opcionalem settings
string
string
A palavra ou frase que nomeia o tema e atravessa a grade de uma borda a outra.
POST/api/public/v1/name-them-allDe 1 a 250 em items
Conteúdo
api_c_name_them_all
Usa como padrão o nome “Name Them All API”
Vale saber
Um item é um objeto com answer e, opcionalmente, aliases (outras grafias que valem), description (a dica) e group. Maiúsculas, acentos e pontuação são ignorados quando um nome é verificado.
Configurações que lê
Campo
Tipo
O que faz
list_match_mode
opcionalem settings
string
string
Se um nome vale assim que é digitado, ou só com Enter.
Um dewhile_typingon_enter
Padrão: "while_typing"
list_slot_hint
opcionalem settings
string
string
O que um espaço vazio entrega: nada, o tamanho do nome, a primeira letra, ou a dica que você escreveu.
Um denonelengthfirst_letterhint
Padrão: "none"
list_arrange
opcionalem settings
string
string
Uma coluna para cada grupo, ou uma única lista.
Um degroupsone_list
Padrão: "groups"
list_allow_give_up
opcionalem settings
boolean
boolean
Mostra um botão de desistir que encerra a rodada e revela o que ficou faltando.
{
"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 combinam entre si.
Usa como padrão o nome “Memory Game API”
Vale saber
Um cartão é um objeto com um type e um value. Use "text" para palavras, ou "image", "audio", "youtube" ou "link" com uma URL em value, e adicione alt para uma descrição.
POST/api/public/v1/matching-pairsDe 2 a 30 em items
Conteúdo
api_c_matching_pairs
Usa como padrão o nome “Matching Game API”
Vale saber
Um cartão é um objeto com um type e um value. Use "text" para palavras, ou "image", "audio", "youtube" ou "link" com uma URL em value, e adicione alt para uma descrição.
O endpoint armazena quantos cartões você enviar, então envie exatamente dois por item — frente, depois verso.
Um cartão é um objeto com um type e um value. Use "text" para palavras, ou "image", "audio", "youtube" ou "link" com uma URL em value, e adicione 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 pertencem a ela.
Usa como padrão o nome “Categorize Game API”
Vale saber
Uma categoria enviada sem nome é salva como “Untitled Category”, então sempre envie um.
Um cartão é um objeto com um type e um value. Use "text" para palavras, ou "image", "audio", "youtube" ou "link" com uma URL em value, e adicione 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 seus cartões na ordem correta.
Usa como padrão o nome “Reorder Game API”
Vale saber
A ordem que você envia é armazenada como a ordem correta — o número um primeiro.
Um cartão é um objeto com um type e um value. Use "text" para palavras, ou "image", "audio", "youtube" ou "link" com uma URL em value, e adicione alt para uma descrição.
Um array de items a partir dos quais as cartelas são montadas. Envie bem mais do que cabe em uma cartela, para que as cartelas sejam diferentes.
Usa como padrão o nome “Bingo API”
Vale saber
Um item é um objeto com value e, opcionalmente, type ("text", "image" ou "audio" com uma URL em value), description (a pista que o apresentador lê no modo "clues") e alt.
Configurações que lê
Campo
Tipo
O que faz
mode
opcionalem settings
string
string
O que preenche as casas: seus items, seus items sorteados pela pista, ou simples números (que não precisam de items).
Um deitemscluesnumbers
Padrão: "items"
rows
opcionalem settings
number
number
Linhas em cada cartela, de 2 a 5.
Padrão: 3
columns
opcionalem settings
number
number
Colunas em cada cartela, de 2 a 5.
Padrão: 3
highest_number
opcionalem settings
number
number
No modo de números, as cartelas são preenchidas de 1 até este número, no máximo 100. Um recurso de plano: sem plano, continua em 50.
Padrão: 50
Exemplo de requisição
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": "br",
"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 cartas. As cartas que fazem parte do código trazem sua posição nele.
Usa como padrão o nome “Keypad API”
Vale saber
Uma carta é um objeto com value e, opcionalmente, type ("text", "image" ou "audio" com uma URL em value), alt e code_position: sua posição no código, com 1 sendo a primeira. Uma carta só pode aparecer uma vez no código, e pelo menos uma carta precisa fazer parte dele.
Configurações que lê
Campo
Tipo
O que faz
instructions
opcionalem settings
string
string
A pergunta ou o enigma a que o código responde, exibido junto com a grade.
force_solution_in_correct_order
opcionalem settings
boolean
boolean
As cartas precisam ser tocadas em ordem. Desativado, qualquer ordem das cartas certas abre o cadeado.
Padrão: false
randomize_order
opcionalem settings
boolean
boolean
Cada jogador recebe as cartas em uma disposição embaralhada.
Um array de quartetos. Cada um tem um nome e exatamente quatro cartas.
Usa como padrão o nome “Quartets API”
Vale saber
Uma carta é um nome, ou um objeto com name e description (o fato exibido nela). Nenhum nome de carta pode aparecer duas vezes no jogo: os jogadores pedem as cartas pelo nome.
Configurações que lê
Campo
Tipo
O que faz
type
opcionalem settings
string
string
Um jogo simples, ou um jogo de aprendizado em que cada carta mostra um fato. Se for omitido, é learn quando alguma carta tem description.
Um denormallearn
Exemplo de requisição
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": "br",
"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. Perguntas de múltipla escolha trazem suas respostas; perguntas abertas trazem a resposta que você aceita.
Usa como padrão o nome “Quiz API”
Vale saber
question_type é "multiple_choice", em que a opção certa traz isCorrect true; "true_false", o mesmo com exatamente duas opções, verdadeiro primeiro e falso depois; ou "open_answer", que usa correct_answer no lugar. Se for omitido, é tratado como múltipla escolha.
O endpoint do quiz repassa settings diretamente como blocos de configuração da atividade, então não é um lugar para opções soltas — ajuste o quiz no editor depois.
Exemplo de requisição
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": "br",
"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 traz isCorrect true; "true_false", o mesmo com exatamente duas opções, verdadeiro primeiro e falso depois; ou "open_answer", que usa correct_answer no lugar. Se for omitido, é tratado como múltipla escolha.
Configurações que lê
Campo
Tipo
O que faz
number_of_tiles
opcionalem settings
number
number
Quantas casas o tabuleiro tem. Entre 10 e 75.
Padrão: 30
game_mode
opcionalem settings
string
string
Se os jogadores correm até a chegada ou coletam itens pelo caminho.
Um derace_to_finishcollect_items
Padrão: "race_to_finish"
Exemplo de requisição
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": "br",
"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 múltipla escolha ou de verdadeiro ou falso, exatamente no formato que o endpoint do quiz recebe. Perguntas abertas são recusadas: uma porta precisa de uma resposta escrita nela.
Usa como padrão o nome “Maze API”
Configurações que lê
Campo
Tipo
O que faz
maze_width
opcionalem settings
string
string
Como as salas ficam dispostas: em uma coluna, em um quadrado, ou mais largas.
Um denarrownormalwide
Padrão: "normal"
maze_corridors
opcionalem settings
string
string
Quanto labirinto fica entre duas perguntas.
Um deshortnormallong
Padrão: "normal"
maze_fog
opcionalem settings
string
string
Mostra o labirinto inteiro, ou só o que fica perto de onde o jogador já esteve.
Um deoffnear
Padrão: "off"
maze_wrong_door_pause
opcionalem settings
string
string
Por quanto tempo as portas ficam fechadas depois de uma errada.
Um denoneshortlong
Padrão: "short"
maze_walk_there
opcionalem settings
boolean
boolean
Oferece um botão que leva a peça até a próxima sala.
Padrã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 omitida, um novo é sorteado.
Exemplo de requisição
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": "br",
"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 suas pistas, da linha de cima para baixo.
Usa como padrão o nome “Jeopardy API”
Vale saber
Uma pista é uma pergunta no formato que o endpoint do quiz recebe, open_answer a menos que diga outra coisa, com correct_answer e, opcionalmente, aliases. Ela também pode trazer value (seu próprio valor) e daily_double. null deixa uma casa vazia.
Configurações que lê
Campo
Tipo
O que faz
jeopardy_buzzer_mode
opcionalem settings
string
string
Quem joga como: o apresentador comanda pelo console, os jogadores tocam a campainha pelo celular, ou cada jogador joga o tabuleiro sozinho.
Um dehostphonessolo
Padrão: "host"
jeopardy_contestants
opcionalem settings
string
string
Se o console fala de equipes ou de jogadores.
Um deteamsplayers
Padrão: "teams"
jeopardy_value_step
opcionalem settings
number
number
Quanto vale uma linha: uma pista vale este valor vezes o número da sua linha. De 50 a 500, de 50 em 50.
Padrão: 100
jeopardy_answer_time
opcionalem settings
number
number
Segundos para responder depois que uma pista é aberta, até 300. 0 é sem cronômetro.
Padrão: 20
jeopardy_wrong_answer_costs
opcionalem settings
boolean
boolean
Uma resposta errada tira o valor da pista da pontuação.
Padrão: false
jeopardy_reveal_on_timeout
opcionalem settings
boolean
boolean
O tabuleiro mostra a resposta sozinho quando o tempo acaba.
Padrão: false
jeopardy_require_question_form
opcionalem settings
boolean
boolean
Lembra os jogadores de responder na forma de uma pergunta.
Padrão: false
Exemplo de requisição
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": "br",
"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
Usa como padrão o nome “Interactive Video API”
Vale saber
Um pop-up é um objeto com time (segundos, ou "1:23"), kind ("question" a menos que diga "note", "think" ou "chapter") e description. Uma pergunta é uma pergunta no formato que o endpoint do quiz recebe, e pode trazer rewind_to: o ponto de onde uma resposta errada recomeça.
Configurações que lê
Campo
Tipo
O que faz
video_url
obrigatórioem settings
string
string
O vídeo: uma página do YouTube, Vimeo ou Bunny Stream, ou um link direto para um arquivo mp4, webm ou mov.
video_duration
opcionalem settings
number
number
A duração do vídeo em segundos. Quando informada, um pop-up depois do fim é recusado.
Exemplo de requisição
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": "br",
"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.
Usa como padrão o nome “Calculation Game API”
Vale saber
Se as restrições forem apertadas demais para codificar a frase, a chamada responde 400 pedindo para afrouxá-las, em vez de salvar um passatempo parcial.
Configurações que lê
Campo
Tipo
O que faz
sentence
obrigatório
string
string
A frase que os jogadores revelam ao resolver as contas.
difficulty_level
opcionalem settings
number
number
O maior resultado que uma conta pode ter.
Um de20501001000
Padrão: "100"
operators
opcionalem settings
string[]
string[]
Quais operações podem aparecer. x é multiplicação, : é divisão.
Um de+-x:
Padrão: ["+", "-", "x", ":"]
max_operations
opcionalem settings
number
number
Quantas operações uma conta pode encadear.
Um de123
Padrão: 1
number_difficulty
opcionalem settings
number
number
Limita os números individuais dentro de uma conta. De 5 a 1000.
Nada. Todo o passatempo vem de suas duas configurações.
Usa como padrão o nome “Sudoku API”
Vale saber
Não envie items nem sentence — size e difficulty são toda a entrada.
O editor só oferece a dificuldade para 2x3, 3x3 e 3x4. A API a aplica a todos os tamanhos, incluindo 2x2 e 4x4.
Configuraçõ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 clássica grade 9x9. O endpoint só verifica se ele pode ser interpretado como dois números, então fique com os 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
Usa como padrão o nome “Fill in the gap API”
Vale saber
Escreva a frase completa e coloque asteriscos em volta de cada palavra a omitir: "Water boils at *100* degrees." Várias palavras dentro de um mesmo par formam uma só lacuna. Um item também pode trazer uma instrução exibida acima da frase.
Exemplo de requisição
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": "br",
"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 é escrita como [word](label).
Usa como padrão o nome “Sentence analysis API”
Vale saber
Escreva uma frase como "The [dog](noun) [barks](verb)." Palavras sem etiqueta são exibidas, mas não são perguntadas. As etiquetas noun, verb, adjective e subject são mostradas a cada jogador no próprio idioma.
Configurações que lê
Campo
Tipo
O que faz
categories
opcionalem settings
string[]
string[]
As etiquetas entre as quais os jogadores escolhem, em ordem. Se for omitido, são as etiquetas usadas nas frases. Envie para acrescentar uma etiqueta que nenhuma palavra usa, ou para definir a ordem.
Exemplo de requisição
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": "br",
"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
Usa como padrão o nome “Logic Puzzle API”
Vale saber
Toda categoria precisa ter o mesmo número de itens, de 3 a 6, todos diferentes. Uma categoria pode ser marcada como ordered (preços, horários, idades) com um unit opcional, o que permite ao gerador escrever pistas sobre mais, menos e quanto.
Configurações que lê
Campo
Tipo
O que faz
story
opcionalem settings
string
string
A história de fundo exibida acima das pistas.
difficulty
opcionalem settings
string
string
Quais tipos de pista o gerador pode usar.
Um deeasymediumhard
Padrão: "easy"
hints
opcionalem settings
boolean
boolean
Oferece um botão que mostra o próximo passo.
Padrão: true
auto_cross
opcionalem settings
boolean
boolean
Marcar uma combinação risca o restante da sua linha e coluna.
Padrão: true
clue_mode
opcionalem settings
string
string
Quem escreve as pistas que os jogadores veem: geradas a partir da tabela, suas próprias frases em free_clues, ou nenhuma.
Um degeneratedfreenone
Padrão: "generated"
free_clues
opcionalem settings
string[]
string[]
Suas próprias frases de pista, exibidas como foram escritas, com clue_mode "free". Nada as verifica.
Exemplo de requisição
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": "br",
"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
Usa como padrão o nome “Scavenger Hunt API”
Vale saber
Um passo é um objeto com title, description, code e, opcionalmente, accepted_codes (outras grafias que valem), url e link_text. Um código é verificado sem diferenciar maiúsculas de minúsculas nem espaços. O mapa com marcadores só pode ser adicionado no editor.
Exemplo de requisição
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": "br",
"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
Usa como padrão o nome “Spatial Reasoning API”
Vale saber
Objetos e 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 como suas letras.
Usa como padrão o nome “Rebus API”
Vale saber
Uma palavra é desenhada a partir de partes que, juntas, a soletram. 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 trocas de letras. Uma parte também pode ser um símbolo, como 4 para "for".
Configurações que lê
Campo
Tipo
O que faz
rebus_commas
opcionalem settings
boolean
boolean
Desenha uma primeira ou última letra descartada como uma vírgula ao lado da imagem.
Uma URL de imagem, no campo image. Este endpoint não recebe items.
Usa como padrão o nome “Jigsaw Game API”
Vale saber
A API sempre cria um quebra-cabeça 4 por 4. Quantidade de peças, peças irregulares e bordas retas são configurações do editor — enviar rows ou columns aqui não tem efeito.
A URL é armazenada exatamente como você a enviou e o arquivo nunca é copiado, então ela precisa continuar publicamente acessível durante todo o tempo em que a atividade for jogada.
Configurações que lê
Campo
Tipo
O que faz
image
obrigatório
string
string
URL absoluta da imagem a ser recortada. Enviada no nível superior, não dentro de settings.
Uma URL de imagem, dentro de settings. Este endpoint não recebe items.
Usa como padrão o nome “Sliding Puzzle API”
Vale saber
Diferente do quebra-cabeça, este endpoint lê sua imagem de settings.image. Um campo image no nível superior é ignorado e a chamada responde 400.
A URL é armazenada exatamente como você a enviou e o arquivo nunca é copiado, então ela precisa continuar publicamente acessível durante todo o tempo em que a atividade for jogada.
Configurações que lê
Campo
Tipo
O que faz
image
obrigatórioem settings
string
string
URL absoluta da imagem a ser embaralhada. Diferente da do quebra-cabeça, esta fica dentro de settings.