Every endpoint is a GET. Nothing here writes anything, so nothing you send can
break state. Responses are JSON except pronunciation audio.
| Endpoint | Purpose | Docs |
|---|---|---|
/v1/word/:word |
Look a word up | Word lookup |
/v1/word/:word/:source |
Look it up in one provider | Word lookup |
/v2/word/:word |
Same, richer shape | Versions |
/v2/word/:word/:source |
Same, one provider | Versions |
/v1/tts/:word |
Pronunciation audio | Pronunciation |
/v1/search |
Full-text search over cached entries | Search |
/v1/conjugate/:verb |
Conjugate a verb | Conjugation |
/v1/pluralize/:noun |
Pluralise a noun | Pluralization |
/v1/audio/:word |
Forvo audio (needs a key) | Pronunciation |
/v1/sources |
Which providers exist and their health | Sources endpoint |
/v1/healthz |
Liveness | Health |
/openapi.json |
Machine-readable API description | below |
/docs |
Interactive reference | below |
/openapi.json is an OpenAPI document: a standard
JSON description of every endpoint, parameter and response. Tools read it to
generate client libraries, populate Postman, or drive tests.
/docs renders that document as a browsable page. Expand an endpoint, fill in a
parameter, press the button, see the real response.
You do not need either to use this API, curl works fine, but /docs is the
fastest way to see what a parameter is called.
Both are generated from the code, so they cannot drift out of date. A test asserts every mounted route appears in the document.
Word lookups always return this envelope:
{
"headword": "casă",
"entries": [ … ],
"cache": { "hits": 8, "misses": 0 },
"errors": [ … ]
}entries: the results. Possibly empty.cache: how many entries came from cache vs a fresh fetch. Useful for understanding latency; ignorable otherwise.errors: providers that failed. This is normally empty. A non-emptyerrorswith a non-emptyentriesmeans some sources worked and some did not: the response is still usable. See Errors.
One slow or broken dictionary never fails the whole request.
Words are validated before anything else happens. A word must be:
- 1–64 characters
- letters, combining marks, spaces,
-and'only
Anything else gets 400 INVALID_INPUT. This is why /v1/word/<script> is
rejected rather than processed.
Percent-encode diacritics if your tooling needs it: cas%C4%83 is casă.
The API rate-limits itself against upstream dictionaries so it stays a polite
client, see Rate limits & robots. There
is also an inbound limit (RATE_LIMIT_PER_MIN, default 60/min per client).