Developer API

Quickstart

No signup, no key. One GET request:

curl "https://thewordindex.com/api/v1/query?pattern=c_t"

Response (abridged):

{
  "data": {
    "words": [{"word": "cat", "length": 3, "tier": 1, "syllables": 1}],
    "total": 1,
    "returned": 1,
    "offset": 0,
    "has_more": false
  },
  "meta": {
    "api_version": "v1",
    "source": "The Word Index compiled lexicon (source-bounded membership facts)",
    "data_version": "…",
    "build_id": "…",
    "attribution": "…",
    "docs_url": "…/developers",
    "terms_url": "…/terms"
  }
}

Base URL and versioning

All endpoints live under https://thewordindex.com/api/v1/. The v1 path segment is a compatibility promise: fields documented here are not renamed or removed within v1; new optional fields may be added. Breaking changes would ship as /api/v2/ with v1 kept running through a documented sunset window.

Results come from one compiled, versioned lexicon release. meta.data_version and meta.build_id identify it exactly; the source catalogue at /about/data records every source artifact, licence state, and limitation. Commonness tier values (1–5) are build-specific ranking bands for that release, not universal usage claims, and membership never implies validity in any specific word game.

By default all endpoints exclude spellings on the release's offensive-word list; pass safe=false to include them.

Endpoints

curl "https://thewordindex.com/api/v1/query?letters=aeg&length=7&max_tier=3"

{
  "data": {
    "word": "listen",
    "length": 6,
    "tier": 1,
    "syllables": 2,
    "definitions": [],
    "note": "No definition is published for this spelling. …"
  },
  "meta": {…}
}

curl "https://thewordindex.com/api/v1/define?word=listen"

curl "https://thewordindex.com/api/v1/rhymes?word=light&limit=10"

curl "https://thewordindex.com/api/v1/anagrams?letters=listen"

curl "https://thewordindex.com/api/v1/random?length=6&count=3"

Response envelope

Every successful response is {"data": …, "meta": …}. The meta block is identical across endpoints:

Word records are the same everywhere: {"word", "length", "tier", "syllables"}. syllables is null when the release retains no pronunciation for the word. tier is a build-specific commonness band (1 = most commonly observed in the pinned frequency artifact), documented at /about/data.

Errors

Errors use one envelope, always served with Cache-Control: no-store:

{
  "error": {"code": "invalid_parameter", "message": "…", "status": 400},
  "meta": {"api_version": "v1", "docs_url": "…/developers"}
}

Requests with undeclared query parameter names terminate with a plain 404 before reaching the API (part of this site's URL contract), so check parameter spelling first when debugging.

Rate limits and fair use

Per-IP token bucket: sustained 5 requests/second with a burst of 20, shared across all v1 endpoints. That is deliberately generous for interactive applications; if you need sustained bulk throughput, please contact us instead of distributing load across IPs.

• Cache responses on your side where you can; results are stable within one data_version.
• Identify your application with a descriptive User-Agent.
• Do not use the API to reconstruct and redistribute the full compiled lexicon; source licence review for bulk redistribution is not complete (see /about/data).
• No SLA is offered; the API serves the same infrastructure as the site.

CORS and caching

All v1 GET responses include Access-Control-Allow-Origin: *, so browser clients on any origin can call the API directly with fetch. Only simple GET requests are supported — no preflighted methods, no credentials, no custom request headers required.

Successful responses are publicly cacheable for a short window (Cache-Control: public, max-age=60); error responses are never stored. The X-Data-Version response header mirrors meta.data_version.

Attribution

The API is free without a key. In return we ask that public applications showing our data include the meta.attribution line, or a link back to The Word Index, near the displayed results. The underlying source artifacts, their licences, and their current legal review states are catalogued at /about/data — please do not present membership in this lexicon as proof of universal English usage or of validity in any specific word game.

Try it