All The Words API Documentation

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: _ and ? for unknown single character; * and % also accepted by backend compatibility layer

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: ? and _

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.

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

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 per client IP across /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.

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"}'