API Reference/

SDKs

Python SDK

The official Python SDK for the Anagrama API. Supports Python 3.9+ with both sync and async clients. Type hints included via py.typed.

Installation

pip
pip install anagrama-sdk
poetry
poetry add anagrama-sdk

Configuration

Create a client with your API key. The SDK automatically reads ANAGRAMA_API_KEY from the environment, so you can omit it if the env var is set.

.env
ANAGRAMA_API_KEY=ak_your_key_here
Python
from anagrama_sdk import Anagrama

# Explicit key
client = Anagrama(api_key="ak_your_key_here")

# Or reads ANAGRAMA_API_KEY from env automatically
client = Anagrama()

First request

Python
from anagrama_sdk import Anagrama

client = Anagrama()

# Fetch 3 random words between 5-8 letters
response = client.words.random(
    count=3,
    min_length=5,
    max_length=8,
)
print(response.words)
# => ["tiger", "flame", "grove"]
print(response.count)
# => 3

Parameters: count (1–10, default 1), min_length (3–15, default 3), max_length (3–15, default 15). All optional.

Common patterns

Daily word

Python
response = client.words.daily()
print(f"Today's word ({response.date}): {response.word}")
# => "Today's word (2026-02-15): flame"

Validate a word

Python
result = client.words.validate(word="flame")
print(result.valid)
# => True

Generate a puzzle

Python
puzzle = client.puzzles.generate(difficulty="medium")
print(puzzle.target, puzzle.scramble)

Dictionary lookup

Python
entry = client.dictionary.lookup("flame")
print(entry.word, len(entry.results))

Fetch a wordset

Python
wordset = client.wordsets.retrieve(
    "ws_Ab3xK9mQ",
    random="true",
    limit=5,
    scramble="true",
)
print(wordset.name, wordset.word_count)
# => "Animals" 5

Async client

Use AsyncAnagrama for async/await workflows with FastAPI, Django, or asyncio:

Python
from anagrama_sdk import AsyncAnagrama

client = AsyncAnagrama()

async def get_words():
    response = await client.words.random(count=3)
    return response.words

Error handling

API errors raise typed exceptions. Use except to handle specific status codes:

Python
from anagrama_sdk import Anagrama, APIStatusError, RateLimitError

client = Anagrama()

try:
    response = client.words.random(count=3)
except RateLimitError as e:
    print(f"Rate limited: {e.status_code}")  # 429
    print(e.message)
except APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")

Available exception classes: BadRequestError, AuthenticationError, NotFoundError, RateLimitError, InternalServerError.

Type hints

The SDK ships with py.typed and full type annotations. Works with mypy, pyright, and IDE autocompletion:

Python
from anagrama_sdk.types import (
    WordRandomResponse,
    WordDailyResponse,
    WordsetResponse,
)

response: WordRandomResponse = client.words.random(count=3)
words: list[str] = response.words
Was this page helpful?
TypeScriptGo
Anagrama API Docs | Developer Reference