Puzzle REST API Reference

Use a Bearer API key. Creation saves the complete result to My Puzzles and returns browser pages, not generated file bytes.

API Keys

Authentication

Pass Authorization: Bearer YOUR_API_KEY. Cookies are not accepted by external endpoints. Keep the key on your server.

Limits and sharing

Example request

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 } }'

Example success response

{
  "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"
}

Example IDs and dates illustrate the response shape. The data object contains the saved result; requestId identifies this HTTP request.

viewUrl: Public preview page; anyone with the link can also view answers.
exportPageUrl: Browser page where the visitor chooses an available download format. It may equal viewUrl and is not a file URL.
editUrl: Owner-only editing page; sign-in and ownership are checked.
playUrl: Playable game page only for supported modes; otherwise null.

REST endpoints

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

Machine-readable OpenAPI schema

Idempotency and responses

Idempotency-Key is required for creation. Retry with the same key and body to receive the same saved puzzle. Reusing a key with a different body returns 409. A newly created puzzle returns 201; a replay returns 200.

Errors

Errors use {error:{code,message,details},requestId}. 400 is malformed JSON or request key; 401 authentication; 403 quota or entitlement; 404 unknown or unowned item; 409 key conflict; 410 deleted or unavailable share; 413 size; 415 media type; 422 invalid or unsatisfiable input; 429 rate limit with Retry-After; 503 creation unavailable.