Pular para o conteúdo
Você está visualizando o novo Puzzel.org Voltar para o site atual
API para desenvolvedores

Crie atividades a partir do seu próprio sistema

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

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.

CampoTipoO que faz
account_api_key
obrigatório
string
stringA chave de API da sua conta. Ela vai no corpo, não em um header.
email
obrigatório
string
stringO 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.

Entrar

As chaves de API são liberadas quando uma assinatura começa, então uma conta gratuita ainda não tem uma.

Ver os planos

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.

CampoTipoO que faz
account_api_key
obrigatório
string
stringA chave de API da sua conta. Ela vai no corpo, não em um header.
email
obrigatório
string
stringO endereço com o qual sua conta do Puzzel.org entra. A chave só é válida junto com ele.
title
opcional
string
stringO nome que a atividade recebe no seu painel. Deixe de fora e o endpoint usa seu próprio nome padrão.
language
opcional
string
stringDecide 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
stringDeixe 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.

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

StatusO 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

Palavras cruzadas

Encaixa suas respostas em uma grade e numera as definições para você.

#
POST /api/public/v1/crossword Pelo menos 2 em items
Conteúdo

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.
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"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Abrir o editor Voltar ao topo

Caça-palavras

Esconde suas palavras em uma grade de letras, nas direções e na forma que você escolher.

#
POST /api/public/v1/wordseeker Pelo menos 2 em items
Conteúdo

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ê
CampoTipoO que faz
hidden_solution
opcional em settings
string
stringAs 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
opcional em 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 de westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Padrão: ["east", "southeast", "south"]
template
opcional em settings
string
stringRecorta a grade em um formato, em vez de deixá-la quadrada.
Um de squarecirclecrossdiamondpyramidsmileystarcross_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"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Abrir o editor Voltar ao topo

Acróstico

Empilha suas respostas para que uma coluna forme uma palavra escondida.

#
POST /api/public/v1/acrostic Pelo menos 1 em items
Conteúdo

Um array de palavras. Juntas, elas precisam fornecer todas as letras da palavra escondida.

Usa como padrão o nome “Acrostic API”

Vale saber
  • Se as respostas não conseguirem fornecer as letras que a solução precisa, a chamada responde 500 em vez de salvar uma grade pela metade.
  • O gerador reordena suas respostas para fazer a coluna funcionar, então a ordem que você envia não é a ordem que os jogadores veem.
Configurações que lê
CampoTipoO que faz
hidden_solution
obrigatório em settings
string
stringA palavra que a coluna destacada forma. Este endpoint não funciona sem ela.
Exemplo de requisição
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": "br",
  "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"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Abrir o editor Voltar ao topo

Palavras embaralhadas

api_e_word_scramble

#
POST /api/public/v1/word-scramble Pelo menos 1 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ê
CampoTipoO que faz
hidden_solution
opcional em settings
string
stringUma 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"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Abrir o editor Voltar ao topo

Forca

Transforma suas palavras ou frases em rodadas de adivinhar a letra.

#
POST /api/public/v1/hangman Pelo menos 1 em items
Conteúdo

Um array de palavras ou frases curtas. A pista é a dica que os jogadores veem.

Usa como padrão o nome “Hangman API”

Exemplo de requisição
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": "br",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Abrir o editor Voltar ao topo

Wordle

Transforma cada palavra que você envia em um jogo de adivinhar a palavra.

#
POST /api/public/v1/wordle Pelo menos 1 em items
Conteúdo

Um array de palavras. Os jogadores têm uma rodada para cada palavra.

Usa como padrão o nome “Wordle API”

Vale saber
  • Criado com a configuração de verificar se os palpites são palavras reais ativada. Desative-a no editor se suas palavras forem nomes ou inventadas.
Exemplo de requisição
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": "br",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Abrir o editor Voltar ao topo

Exercício de digitação

api_e_typing_practice

#
POST /api/public/v1/typing-practice Pelo menos 1 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"
}
Abrir o editor Voltar ao topo

Roda da fortuna

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Pelo menos 1 em items
Conteúdo

api_c_wheel_of_fortune

Usa como padrão o nome “Wheel of Fortune API”

Vale saber
  • Criado com “mostrar o resultado somente na roda”, então o resultado é lido na roda em vez de anunciado ao lado dela.
Exemplo de requisição
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": "br",
  "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"
    }
  ]
}'
Sucesso 
{
  "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"
}
Abrir o editor Voltar ao topo
Cartões e pares

Memory

Cartões virados para baixo, para virar e combinar em pares.

#
POST /api/public/v1/memory Pelo menos 2 em items
Conteúdo

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.
Exemplo de requisição
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": "br",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Abrir o editor Voltar ao topo

Jogo de associação

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Pelo menos 2 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.
Exemplo de requisição
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": "br",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Abrir o editor Voltar ao topo

Cartões de estudo

api_e_flash_cards

#
POST /api/public/v1/flash-cards Pelo menos 1 em items
Conteúdo

api_c_flash_cards

Usa como padrão o nome “Flash Cards API”

Vale saber
  • 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.
Exemplo de requisição
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": "br",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Abrir o editor Voltar ao topo

Jogo de categorias

Cartões para classificar na categoria a que pertencem.

#
POST /api/public/v1/categorize Pelo menos 2 em items
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.
Exemplo de requisição
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": "br",
  "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"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Abrir o editor Voltar ao topo

Ordenação

Uma sequência que os jogadores precisam reorganizar.

#
POST /api/public/v1/reorder Pelo menos 1 em items
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.
Exemplo de requisição
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": "br",
  "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"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Abrir o editor Voltar ao topo
Perguntas e respostas

Quiz

Perguntas de múltipla escolha e abertas, pontuadas conforme os jogadores avançam.

#
POST /api/public/v1/quiz Pelo menos 1 em items
Conteúdo

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, 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."
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Abrir o editor Voltar ao topo

Jogo de tabuleiro

api_e_board_game

#
POST /api/public/v1/board-game Pelo menos 1 em items
Conteúdo

api_c_board_game

Usa como padrão o nome “Board Game API”

Vale saber
  • question_type é "multiple_choice", em que a opção certa traz isCorrect true, ou "open_answer", que usa correct_answer no lugar. Se for omitido, é tratado como múltipla escolha.
Configurações que lê
CampoTipoO que faz
number_of_tiles
opcional em settings
number
numberQuantas casas o tabuleiro tem. Entre 10 e 75.
Padrão: 30
game_mode
opcional em settings
string
stringSe os jogadores correm até a chegada ou coletam itens pelo caminho.
Um de race_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"
}
Abrir o editor Voltar ao topo
Frases e números

Criptograma

Transforma uma frase em um código para decifrar, um caractere de cada vez.

#
POST /api/public/v1/cryptogram Não recebe items
Conteúdo

Uma frase, no campo sentence. Este endpoint não recebe items.

Usa como padrão o nome “Cryptogram API”

Vale saber
  • Qualquer coisa que você enviar em items é ignorada — o passatempo é montado apenas a partir de sentence.
Configurações que lê
CampoTipoO que faz
sentence
obrigatório
string
stringA frase a ser criptografada. Os jogadores a decodificam caractere por caractere.
helpers
opcional em settings
string
stringQuais caracteres são revelados de graça como ponto de partida: nenhum, os mais comuns, as vogais, ou os que você mesmo listar.
Um de nonemost_commonvowelscustom
Padrão: "none"
character_list
opcional em settings
string
stringO alfabeto a partir do qual a cifra é construída. Se deixado vazio, a criptografia escolhe o seu próprio.
extra_letters
opcional em settings
string
stringOs caracteres revelados quando helpers é "custom". Ignorado para os outros modos de ajuda.
hide_unused_characters
opcional em settings
boolean
booleanDeixa de fora da chave os caracteres que a frase nunca usa.
Padrão: false
Exemplo de requisição
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": "br",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Abrir o editor Voltar ao topo

Exercício de cálculo

Esconde uma frase atrás de contas — resolva a conta, revele a letra.

#
POST /api/public/v1/calculation Não recebe items
Conteúdo

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ê
CampoTipoO que faz
sentence
obrigatório
string
stringA frase que os jogadores revelam ao resolver as contas.
difficulty_level
opcional em settings
number
numberO maior resultado que uma conta pode ter.
Um de 20501001000
Padrão: "100"
operators
opcional em settings
string[]
string[]Quais operações podem aparecer. x é multiplicação, : é divisão.
Um de +-x:
Padrão: ["+", "-", "x", ":"]
max_operations
opcional em settings
number
numberQuantas operações uma conta pode encadear.
Um de 123
Padrão: 1
number_difficulty
opcional em settings
number
numberLimita os números individuais dentro de uma conta. De 5 a 1000.
Padrão: 100
Exemplo de requisição
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": "br",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Abrir o editor Voltar ao topo

Sudoku

Gera uma grade resolvida e depois retira números dela.

#
POST /api/public/v1/sudoku Não recebe items
Conteúdo

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ê
CampoTipoO que faz
size
opcional em settings
string
stringO 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.
Um de 2x22x33x33x44x4
Padrão: "3x3"
difficulty_level
opcional em settings
string
stringQuantos números ficam na grade para começar.
Um de easynormalhard
Padrão: "normal"
Exemplo de requisição
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": "br",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Abrir o editor Voltar ao topo
Imagens

Quebra-cabeça

Corta uma imagem em peças para arrastar e remontar.

#
POST /api/public/v1/jigsaw Não recebe items
Conteúdo

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ê
CampoTipoO que faz
image
obrigatório
string
stringURL absoluta da imagem a ser recortada. Enviada no nível superior, não dentro de settings.
Exemplo de requisição
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": "br",
  "image": "https://example.com/orchard.jpg"
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Abrir o editor Voltar ao topo

Quebra-cabeça deslizante

Embaralha uma imagem em peças que deslizam até o lugar certo.

#
POST /api/public/v1/slidingpuzzle Não recebe items
Conteúdo

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ê
CampoTipoO que faz
image
obrigatório em settings
string
stringURL absoluta da imagem a ser embaralhada. Diferente da do quebra-cabeça, esta fica dentro de settings.
Exemplo de requisição
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": "br",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Abrir o editor Voltar ao topo

Algo não está se comportando como deveria?

Envie a requisição que você tentou e o erro que recebeu de volta, e você terá uma resposta de verdade, da pessoa que escreveu o endpoint.

E-mail para suporte