Skip to main content

Retrieve puzzle metadata

GET 
/api/v2/puzzles

Retrieves puzzle metadata based on specific criteria. Supports two mutually exclusive request types:

1. Specific/Multiple Puzzles Request: Returns metadata for one or more specific puzzles.

  • Requires series and puzzleIds (comma-separated list).
  • Maximum 30 puzzle IDs allowed per request.

2. Time Range Request: Returns a list of puzzles within a given time range, sorted by publish time in descending order (newest first).

  • Requires series.
  • from and to define the time range (both must be in ISO 8601 format with a timezone offset).
  • limit and offset can be used for pagination.
  • hasMore is a boolean indicating if there are more puzzles available for pagination.

Puzzle Type Support:

  • Grid Games (Crossword, Codeword, KrissKross, Sudoku): Grid dimensions and word count
  • Quiz Games: Number of questions

Pagination and Ordering: Results are paginated with the limit and offset query parameters and are ordered by publicationTime in descending order (newest first). Parameter limit (integer) specifies the maximum number of puzzles to return per request and offset denotes the number of puzzles to skip (in the descending order of publicationTime) before starting to return results. To retrieve all the puzzles using this endpoint:

  1. Call the endpoint with offset=0.
  2. Process the returned puzzles.
  3. If the hasMore field is set to true, request the next page by increasing offset by limit.
  4. Repeat step 3 until a response returns hasMore field as false, indicating there are no more results.

Use Cases:

  • Puzzle Discovery: Browse available puzzles in a series by publication date
  • Content Management: Retrieve metadata for specific puzzles by ID

Examples:

Specific Puzzle Request:

curl -L 'http://localhost:8080/pmm-dev/api/v2/puzzles?series=api-demo-crossword&puzzleIds=82e56966' \
-H 'Accept: application/json'

Multiple Puzzles Request:

curl -L 'http://localhost:8080/pmm-dev/api/v2/puzzles?series=api-demo-crossword&puzzleIds=82e56966,50a2ab68,a7b2b0e0' \
-H 'Accept: application/json'

Time Range Request (Last 30 days):

curl -L 'http://localhost:8080/pmm-dev/api/v2/puzzles?series=api-demo-crossword&from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z&limit=10&offset=0' \
-H 'Accept: application/json'

Request​

Responses​

Successful response with puzzle metadata