Puzzles API

Fetch, generate, and validate puzzles. All puzzle endpoints require a tenant API key via the X-API-Key header.

GET/api/v1/puzzles

List Puzzles

Paginated list of puzzles with optional filters.

Parameter	Type	Required	Description
`puzzleType`	string	No	Filter by type (e.g. sudoku, wordsearch)
`difficulty`	string	No	Filter by difficulty (easy, medium, hard, expert)
`locale`	string	No	Locale filter
`limit`	integer	No	Items per page (default: 20)
`cursor`	string	No	Cursor for next page

bash

curl -X GET "https://api.puzzlesection.app/api/v1/puzzles?puzzleType=sudoku&difficulty=medium&limit=10" \
  -H "X-API-Key: ps_live_xxxxxxxxxxxx"

GET/api/v1/puzzles/daily/:date

Get Daily Puzzles

Returns all daily puzzles for a given date. Optionally filter by type.

Parameter	Type	Required	Description
`date`	string	Yes	Date in YYYY-MM-DD format (path parameter)
`type`	string	No	Filter by puzzle type (query parameter)

bash

curl -X GET "https://api.puzzlesection.app/api/v1/puzzles/daily/2026-03-05?type=sudoku" \
  -H "X-API-Key: ps_live_xxxxxxxxxxxx"

Response

JSON

1{
2  "date": "2026-03-05",
3  "puzzles": [
4    {
5      "id": "550e8400-e29b-41d4-a716-446655440000",
6      "type": "sudoku",
7      "difficulty": "medium",
8      "date": "2026-03-05",
9      "estimatedTime": 480,
10      "isPremium": false,
11      "data": {
12        "grid": [[0, 0, 3, 0, 2, 0, 6, 0, 0], ...],
13        "given": [[false, false, true, ...], ...],
14        "difficulty": "medium"
15      },
16      "createdAt": "2026-03-04T00:00:00Z",
17      "updatedAt": "2026-03-04T00:00:00Z"
18    }
19  ]
20}

SDK Equivalent

TypeScript

const { data } = await client.puzzles.getDaily({
  date: '2026-03-05',
  types: ['sudoku'],
});

GET/api/v1/puzzles/:id

Get Puzzle by ID

Retrieve a specific puzzle by its UUID.

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Puzzle identifier

bash

curl -X GET "https://api.puzzlesection.app/api/v1/puzzles/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: ps_live_xxxxxxxxxxxx"

POST/api/v1/puzzles/generate

Generate Puzzle

Generate a new puzzle on demand.

Parameter	Type	Required	Description
`puzzleType`	string	Yes	Puzzle type to generate
`difficulty`	string	No	Desired difficulty
`locale`	string	No	Locale for word-based puzzles
`dictionaryId`	string	No	Custom dictionary ID
`contentTags`	string[]	No	Content tags for themed puzzles

bash

curl -X POST "https://api.puzzlesection.app/api/v1/puzzles/generate" \
  -H "X-API-Key: ps_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "puzzleType": "wordsearch", "difficulty": "easy", "locale": "en" }'

POST/api/v1/puzzles/batch

Batch Generate

Generate multiple puzzles in a single request.

JSON

{
  "requests": [
    { "puzzleType": "sudoku", "difficulty": "medium" },
    { "puzzleType": "wordsearch", "difficulty": "easy", "locale": "en" }
  ]
}

POST/api/v1/puzzles/batch-lookup

Batch Lookup

Fetch multiple puzzles by ID in a single request.

JSON

{ "ids": ["uuid-1", "uuid-2", "uuid-3"] }

POST/api/v1/puzzles/:id/validate

Validate Solution

Check if a submitted solution is correct.

bash

curl -X POST "https://api.puzzlesection.app/api/v1/puzzles/550e8400-.../validate" \
  -H "X-API-Key: ps_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "solution": { "grid": [[5, 3, 4, ...], ...] } }'

SDK Equivalent

TypeScript

const { data } = await client.puzzles.validateSolution('550e8400-...', {
  grid: [[5, 3, 4, ...], ...]
});
// data: { valid: boolean, errors?: string[] }

The Puzzle Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`type`	PuzzleType	One of 14 types: sudoku, wordsearch, crossword, nonogram, colornonogram, picturepath, crossmath, kakuro, slitherlink, mosaic, wordpath, wordladder, breadcrumb, hashi
`difficulty`	string	easy, medium, hard, or expert
`date`	string	Publication date (YYYY-MM-DD)
`estimatedTime`	number	Estimated solve time in seconds
`isPremium`	boolean	Whether this puzzle requires premium access
`data`	PuzzleData	Type-specific puzzle data (grid, clues, etc.)
`createdAt`	string	ISO timestamp
`updatedAt`	string	ISO timestamp