API Documentation

This page documents every machine-facing API currently implemented: REST JSON endpoints, MCP JSON-RPC tools, and OpenAI-compatible chat endpoints.

Base URLs

https://api.allthewords.app/api/v1 for REST endpoints
https://api.allthewords.app/mcp for MCP JSON-RPC
https://api.allthewords.app/v1 for OpenAI-compatible endpoints

Common behavior

Content type: application/json; charset=utf-8
CORS: Access-Control-Allow-Origin: *
Methods supported: GET, POST, OPTIONS
Error envelope format:

{
  "error": {
    "code": "invalid_language",
    "message": "unsupported language code",
    "details": {
      "lang": "xx"
    }
  }
}

REST API

GET /api/v1/healthz

Health check endpoint for uptime and deployment probes.

{
  "status": "ok",
  "service": "allthewords-api",
  "api_version": "v1",
  "time": "2026-03-12T12:34:56Z"
}

GET /api/v1/languages

Returns supported languages and dictionary sizes.

GET /api/v1/search/pattern

Pattern search over one language dictionary.

Required query params: lang, pattern
Optional query params: contains, excludes, limit, offset
Wildcard support: _ 含める文字 ? 含める文字; * 含める文字 % 含める文字

GET /api/v1/search/anagram

Anagram search over one language dictionary.

Required query params: lang, letters
Optional query params: min_length, max_length, limit, offset
Blank tile support: ? 含める文字 _

GET /api/v1/stats/languages/{lang}

Returns detailed dictionary and usage-behavior statistics for one language.

GET /api/v1/stats/global

Returns aggregate dictionary and behavior statistics across all languages.

GET /api/v1/word/{lang}/{word}

Get detailed information about a specific word including definition, related words, and cross-language availability.

Required: lang (language code), word (the word to look up)
Returns: word details, definition (if available), word families, and cross-language matches

{
  "word": "hello",
  "language": "en",
  "language_name": "English",
  "length": 5,
  "points": 8,
  "has_points": true,
  "definition": {
    "phonetic": "/həˈloʊ/",
    "audio_url": "https://...",
    "meanings": [...],
    "source": "wiktionary"
  },
  "word_families": {
    "starts_with": [{"word": "hellos", "length": 6, "points": 9}],
    "ends_with": [],
    "contains": [{"word": "shell", "length": 5, "points": 8}]
  },
  "cross_languages": [
    {"code": "de", "name": "German", "flag": "🇩🇪", "points": 6}
  ]
}

MCP API

MCP endpoint is JSON-RPC at POST /mcp.

Implemented methods:

initialize
tools/list
tools/call

Available MCP tools

list_languages
search_pattern
search_anagram
get_language_stats
get_global_stats
get_word_details — Get word definition, families, and cross-language info

Example tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_pattern",
    "arguments": {
      "lang": "en",
      "pattern": "_a_e",
      "contains": "r",
      "limit": 10
    }
  }
}

OpenAI-compatible API

GET /v1/models

Returns currently exposed model list for integration clients.

POST /v1/chat/completions

Supports OpenAI-compatible request/response format, including tool-calling style responses. This endpoint maps to the same functionality exposed via MCP tools.

Tool-calling example

{
  "model": "allthewords-mcp-1",
  "messages": [
    {
      "role": "user",
      "content": "lang=en pattern=_a_e contains=r"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_pattern"
      }
    }
  ],
  "tool_choice": "auto"
}

Pagination and limits

REST and MCP search calls support limit and offset.
Default limit: 100.
Maximum limit: 1000.
Response includes total, returned, and has_more.
API rate limit: 120 requests per 60 seconds for /api/v1/*, /v1/*, and /mcp.
/api/v1/healthz is excluded from rate limiting for monitoring probes.
When limited, responses return 429 with Retry-After, X-RateLimit-Limit, and X-RateLimit-Window headers.

Word object fields

Each word in the response includes:

word - word: The word itself
length - length: Number of letters
points - points: Scrabble/Wordfeud point value

Search response fields

Search responses include these fields:

tool - tool: Either 'pattern' or 'anagram'
language - language: Language code
query - query: The search query used
total - total: Total number of matching words
returned - returned: Number of words in this response
has_more - has_more: True if more results available
offset - offset: Current pagination offset
limit - limit: Current pagination limit
description - description: Human-readable search summary
words - words: Array of Word objects

Error handling

Authentication

No authentication required. This is a public API.

Error codes

missing_pattern - missing_pattern: Pattern parameter is required
missing_letters - missing_letters: Letters parameter is required
missing_lang - missing_lang: Language parameter is required
invalid_language - invalid_language: Language code not supported
invalid_length_range - invalid_length_range: min_length exceeds max_length
rate_limited - rate_limited: Too many requests (120 per 60s)
method_not_allowed - method_not_allowed: HTTP method not supported
request_too_large - request_too_large: Request body exceeds 64KB limit

OpenAPI Specification

Download the complete OpenAPI 3.0 specification

Download openapi.yaml

Quick curl examples

curl "https://api.allthewords.app/api/v1/languages"

curl "https://api.allthewords.app/api/v1/search/pattern?lang=en&pattern=_a_e&contains=r&limit=20"

curl "https://api.allthewords.app/api/v1/search/anagram?lang=en&letters=react?&min_length=3&max_length=7"

curl -X POST "https://api.allthewords.app/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

curl -X POST "https://api.allthewords.app/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model":"allthewords-mcp-1","messages":[{"role":"user","content":"lang=en pattern=_a_e"}],"tools":[{"type":"function","function":{"name":"search_pattern"}}],"tool_choice":"auto"}'