API Reference/

Puzzle API

Beta

Generate Puzzle

Generate a complete Anagrama puzzle. Returns everything needed to build a word puzzle game: the target word, scrambled letters, a letter pool with decoy letters, pre-computed hints, all valid alternate anagram answers, and definitions.

GET/api/v1/puzzles/generate

Requires API key

Returns a fully-formed puzzle with target word, scrambled letters, letter pool, hints, alternate answers, and definitions. Use the optional parameters to control difficulty and replay specific puzzles.

Query Parameters

NameDescription
difficulty
stringPuzzle difficulty: easy, medium, or hard. Controls word length and number of decoy letters in the pool. Defaults to medium.
seed
stringReplay a specific puzzle. Pass a seed from a previous response to get the exact same puzzle.
hardMode
booleanWhen true, hints are disabled (maxHints returns 0). Defaults to false.

Request

bash
curl "https://api.playanagrama.com/api/v1/puzzles/generate?difficulty=medium" \
  -H "Authorization: Bearer ak_your_key_here"

Response Fields

NameDescription
seed
stringPuzzle seed. Pass this back to replay the exact same puzzle.
difficulty
stringThe difficulty level used.
target
stringThe target answer word.
scramble
stringThe target word with letters shuffled (for display).
pool
stringFull letter bank: target letters + cloned letters + decoy letters, shuffled. This is what players pick from.
wordLength
integerLength of the target word.
maxAttempts
integerMaximum guesses allowed (always 5).
maxHints
integerMaximum hints available. 3 in normal mode, 0 when hardMode=true.
feedbackMode
stringAlways "wordle" (positional letter marks).
hints
object[]Pre-computed hint reveal order. Each hint has order (sequence number), position (index in the target word), and letter.
alts
string[]Other valid anagram answers (words with the same letters as the target).
definitions
objectDefinitions for the target word and all alternates. Keys are words, values are definition strings.
metadata
objectPuzzle metadata: vowelCount, hasRepeats, poolSize, altCount.

Response 200

JSON
{
  "seed": "djE6bWVkaXVtOnBsYW5l",
  "difficulty": "medium",
  "target": "plane",
  "scramble": "lneap",
  "pool": "lneapxqzp",
  "wordLength": 5,
  "maxAttempts": 5,
  "maxHints": 3,
  "feedbackMode": "wordle",
  "hints": [
    {
      "order": 0,
      "position": 3,
      "letter": "n"
    },
    {
      "order": 1,
      "position": 0,
      "letter": "p"
    },
    {
      "order": 2,
      "position": 4,
      "letter": "e"
    }
  ],
  "alts": [
    "panel",
    "penal"
  ],
  "definitions": {
    "plane": "noun. A flat surface or a powered aircraft.",
    "panel": "noun. A distinct section of a surface.",
    "penal": "adjective. Relating to punishment."
  },
  "metadata": {
    "vowelCount": 2,
    "hasRepeats": false,
    "poolSize": 9,
    "altCount": 2
  }
}

Response 200 — Hard mode

JSON
{
  "seed": "djE6aGFyZDpjcmFuZXM",
  "difficulty": "hard",
  "target": "cranes",
  "scramble": "nrsace",
  "pool": "nrsacedlwxpy",
  "wordLength": 6,
  "maxAttempts": 5,
  "maxHints": 0,
  "feedbackMode": "wordle",
  "hints": [],
  "alts": [
    "caners",
    "nacres"
  ],
  "definitions": {
    "cranes": "noun. Large wading birds or lifting machines.",
    "caners": "noun. People who make or repair cane chairs.",
    "nacres": "noun. Plural of nacre (mother of pearl)."
  },
  "metadata": {
    "vowelCount": 2,
    "hasRepeats": false,
    "poolSize": 12,
    "altCount": 2
  }
}

Response 400 — Invalid params

JSON
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid difficulty value. Must be easy, medium, or hard."
  }
}

Response 400 — Invalid seed

JSON
{
  "error": {
    "code": "INVALID_SEED",
    "message": "Seed decodes but the word is no longer in the dictionary."
  }
}
Pass the seed from a response back as a query parameter to replay the exact same puzzle — useful for challenges and sharing. The alts array contains other valid words that can be formed from the same letters as the target. Use GET /api/v1/words/validate to check if a player's guess is a real word before comparing it to the target.

Implementing Wordle Marks

Compare the player's guess to the target using positional marks. Each letter is marked as correct (right letter, right position), present (right letter, wrong position), or absent (letter not in target).

javascript
function wordleMarks(guess, target) {
  const marks = Array(target.length).fill("absent");
  const need = {};
  for (const ch of target) need[ch] = (need[ch] || 0) + 1;

  // First pass: mark correct positions
  for (let i = 0; i < target.length; i++) {
    if (guess[i] === target[i]) {
      marks[i] = "correct";
      need[guess[i]]--;
    }
  }

  // Second pass: mark present letters
  for (let i = 0; i < target.length; i++) {
    if (marks[i] !== "correct" && need[guess[i]] > 0) {
      marks[i] = "present";
      need[guess[i]]--;
    }
  }

  return marks; // ["correct", "absent", "present", ...]
}
Was this page helpful?
Overview
Anagrama API Docs | Developer Reference