Public API v1

GET/api/v1/meta

API and dataset versions, data license and counts of the served dictionary

Parameters

No parameters.

Responses

• 200OK — PublicMetaV1ResT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/meta'

Try it in the playground

GET/api/v1/openapi.json

The OpenAPI 3 document of the public API (this contract)

Parameters

No parameters.

Responses

• 200OK — object
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT
• 503Not available: the OpenAPI document is not ready, or the suggestion queue is full — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/openapi.json'

GET/api/v1/search

Search dictionary entries (flat list, no meanings)

Tiers in relevance order: exact, phrasal, starts-with, phrases, ends-with, contains. When none matches, a trigram similarity tier answers typos (`meta.fuzzy: true`, `similarity` on every item; Postgres instances only). A term shorter than 3 characters searches the exact and prefix tiers only (`meta.short_term: true`). Cacheable: the answer carries `ETag`, `Last-Modified` and `Cache-Control` like every public GET.

Parameters

Responses

• 200OK — PublicSearchV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/search'

Try it in the playground

GET/api/v1/search/detailed

Search dictionary entries with pagination, meanings and translations

The detailed search: the same term and tiers, paged, with meanings and translations joined on request; the fields travel in the query string (`translation_languages` as a repeated key). Cacheable like every public GET.

Parameters

Responses

• 200OK — PublicSearchDetailedV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/search/detailed'

Try it in the playground

GET/api/v1/words/{word}

All entries of a headword: parts of speech, forms, meanings, translations, links

Parameters

Responses

• 200OK — PublicHeadwordV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/run'

Try it in the playground

GET/api/v1/words/{word}/meanings

The meanings of a headword across its entries

Parameters

Responses

• 200OK — PublicHeadwordMeaningsV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/run/meanings'

Try it in the playground

GET/api/v1/words/{word}/translations

The short and per-meaning translations of a headword

Parameters

Responses

• 200OK — PublicHeadwordTranslationsV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/run/translations'

Try it in the playground

GET/api/v1/words/{word}/forms

The inflected forms of a headword across its entries

Parameters

Responses

• 200OK — PublicHeadwordFormsV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/run/forms'

Try it in the playground

GET/api/v1/words/{word}/synonyms

The synonyms of a headword, per meaning

One item per linked headword and meaning; each names its `meaning_id`, `word_id` and `part_of_speech`.

Parameters

Responses

• 200OK — PublicHeadwordLinksV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/run/synonyms'

Try it in the playground

GET/api/v1/words/{word}/antonyms

The antonyms of a headword, per meaning

One item per linked headword and meaning; each names its `meaning_id`, `word_id` and `part_of_speech`.

Parameters

Responses

• 200OK — PublicHeadwordLinksV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/run/antonyms'

Try it in the playground

GET/api/v1/words/id/{id}

One dictionary entry by its numeric id

Parameters

Responses

• 200OK — PublicWordV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words/id/1'

Try it in the playground

GET/api/v1/words

List dictionary entries by filters, cursor-paged and ordered by (word, id)

Every enum filter accepts a repeated key; values of one filter are OR-ed, filters are AND-ed. `search` keeps the headwords starting with the prefix (an autocomplete or an A–Z browser: cacheable, unlike the search). Pass `meta.next_cursor` back as `cursor` to read the next page.

Parameters

Responses

• 200OK — PublicWordsV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/words'

Try it in the playground

GET/api/v1/random

A random dictionary entry matching the filters (base forms unless form_of_word is given)

Parameters

Responses

• 200OK — PublicWordV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl 'https://your-instance.example/api/v1/random'

Try it in the playground

POST/api/v1/words/batch

Up to 50 headwords in one request

Every spelling is matched like `GET /words/{word}`; the answer keeps the request order, collapses duplicates, and lists the spellings without an entry under `meta.not_found` instead of failing. One request against the rate limit, whatever the size of the batch.

Request body · WordsBatchV1ReqDTO

Responses

• 200OK — PublicWordsBatchV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT

Example

curl -X POST 'https://your-instance.example/api/v1/words/batch' \
  -H 'Content-Type: application/json' \
  -d '{"words":["example"]}'

Try it in the playground

POST/api/v1/suggestions

Report a mistake in the dictionary data

Files a report for the instance admin to review: what is wrong with a headword (optionally one specific entry of it) and, ideally, what would be right. The headword must exist in the dictionary. Strictly rate-limited; once too many reports are waiting for the admin the endpoint answers 503 until the queue is worked down.

Request body · CreateSuggestionV1ReqDTO

Responses

• 201OK — PublicSuggestionCreatedV1ResT
• 400Invalid input: an unknown field, a value outside the allowed set, or a foreign cursor — PublicApiErrorT
• 404Nothing matches — PublicApiErrorT
• 429Rate limit of the public prefix exceeded (PUBLIC_API_RATE_LIMIT); retry after the window — PublicApiErrorT
• 503Not available: the OpenAPI document is not ready, or the suggestion queue is full — PublicApiErrorT

Example

curl -X POST 'https://your-instance.example/api/v1/suggestions' \
  -H 'Content-Type: application/json' \
  -d '{"headword":"example"}'

Try it in the playground