Referência da API REST de quebra-cabeças

Use uma chave de API Bearer. A criação salva o resultado completo em Meus quebra-cabeças e retorna páginas do navegador, não o conteúdo de arquivos.

Chaves API

Autenticação

Envie Authorization: Bearer YOUR_API_KEY. As rotas externas não aceitam cookies. Guarde a chave no seu servidor.

Limites e compartilhamento

Exemplo de solicitação

curl -X POST https://puzzlegenio.com/api/v1/puzzles \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: task-000000000001' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "wordsearch", "preset": "word-search-for-kids", "title": "Animal word search", "input": { "words": [ "CAT", "DOG", "LION", "TIGER" ] }, "options": { "gridSize": 10, "allowDiagonal": false } }'

Exemplo de resposta bem-sucedida

{
  "data": {
    "savedId": "123456789",
    "shareId": "AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "type": "wordsearch",
    "preset": "word-search-for-kids",
    "viewUrl": "https://puzzlegenio.com/puzzles/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "exportPageUrl": "https://puzzlegenio.com/puzzles/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "editUrl": "https://puzzlegenio.com/word-search-for-kids?id=123456789",
    "playUrl": "https://puzzlegenio.com/word-search-maker/play/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "expiresAt": "2026-11-01T00:00:00.000Z",
    "shareState": "active",
    "savedCount": 1,
    "limit": 20,
    "formats": [
      "pdf",
      "answer-pdf"
    ],
    "itemCount": 1,
    "warnings": []
  },
  "requestId": "00000000-0000-4000-8000-000000000000"
}

Identificadores e datas são ilustrativos. data contém o resultado salvo; requestId identifica a solicitação.

viewUrl: Página pública de prévia; quem tem o link também pode ver as respostas.
exportPageUrl: Página para escolher o formato de download no navegador. Pode ser igual a viewUrl e não é um arquivo direto.
editUrl: Página de edição exclusiva do proprietário; exige login e verificação da conta.
playUrl: Página para jogar apenas nos modos compatíveis; nos demais, null.

Rotas REST

POST	/api/v1/puzzles
GET	/api/v1/puzzles
GET	/api/v1/puzzles/{savedId}
DELETE	/api/v1/puzzles/{savedId}
POST	/api/v1/puzzles/{savedId}/share
GET	/api/v1/capabilities
GET	/api/v1/results/{shareId}
POST	/api/v1/assets
POST	/api/v1/assets/import
GET	/api/v1/openapi.json

Esquema OpenAPI legível por máquinas

Idempotência e respostas

Idempotency-Key é obrigatório na criação. Repetir a mesma chave e o mesmo corpo retorna o mesmo item salvo. Usar a chave com outro corpo retorna 409. A primeira criação retorna 201; a repetição retorna 200.

Erros

Os erros seguem {error:{code,message,details},requestId}. 400 indica solicitação incorreta; 401, autenticação; 403, cota ou permissão; 404, item desconhecido ou de outra pessoa; 409, conflito; 410, compartilhamento inativo; 413, tamanho; 415, tipo de mídia; 422, entrada inválida; 429, limite de frequência com Retry-After; 503, criação indisponível.