Dictionary API documentation

Your API key

Get a free key from Account → API (you will need a verified FreeDict account). Send it in the X-API-Key header on every request. Keep it on your server; never put it in front-end code.

Base URL: https://freedict.com/api/v1. Every response is JSON. Successful responses wrap the result in data; errors come back as error with a code and a message, and never with a 200 status.

Look up a word

GET /words/{word}?locale=en-US

locale is required: en-US, en-GB or en-AU. It picks the pronunciation (British and Australian callers get the UK transcription where one exists).

curl "https://freedict.com/api/v1/words/serendipity?locale=en-US" \
  -H "X-API-Key: YOUR_KEY"

Python:

import requests

r = requests.get(
    "https://freedict.com/api/v1/words/serendipity",
    params={"locale": "en-US"},
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=10,
)
entry = r.json()["data"]
print(entry["definition_short"])

JavaScript (Node 18+):

const res = await fetch(
  "https://freedict.com/api/v1/words/serendipity?locale=en-US",
  { headers: { "X-API-Key": process.env.FREEDICT_KEY } }
);
const { data } = await res.json();
console.log(data.definition_short);

The response includes: word, slug, length, pos, definition_short, definitions (each with pos, sense and register), pronunciation_ipa, respelling, cefr_level and flags (proper_noun, offensive, hyphenated, multiword), plus source information for the record. A word that is not in the dictionary returns 404 word_not_found.

Translations

Add include=translations to a word or batch request to get translations in all 34 languages, grouped by language, each with the part of speech, a short gloss where there is one and a romanised form for non-Latin scripts.

curl "https://freedict.com/api/v1/words/peace?locale=en-GB&include=translations" \
  -H "X-API-Key: YOUR_KEY"

Batch lookups Starter and above

POST /words/batch with a JSON body of up to 500 words. Words that are not found are listed in not_found. A batch request counts as one call.

curl -X POST "https://freedict.com/api/v1/words/batch" \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"locale": "en-US", "words": ["apple", "banana", "cherry"]}'

Query word lists Pro and above

GET /words/query returns words that match your filters, in a fixed order for a given seed, which is what word games need: the same seed always gives the same list, so a daily puzzle never changes after the day it was set.

• locale and seed are required.
• Filters: length, length_min, length_max, pos (comma-separated), cefr_level (e.g. A2,B1), starts_with, ends_with, contains, exclude_flags (proper_noun, offensive, archaic, abbreviation, hyphenated, multiword).
• Paging: limit (default 100, up to 10,000) and offset.
• A filter the API does not support returns 422 rather than being silently ignored.

curl "https://freedict.com/api/v1/words/query?locale=en-US&seed=2026-09-28&length=5&exclude_flags=proper_noun,offensive&limit=50" \
  -H "X-API-Key: YOUR_KEY"

Dataset info

GET /meta lists the fields and filters the API supports and how many words each field is filled for, counted live, so you can check coverage before you build on a field.

Rate limits and your monthly allowance

Each plan has a per-minute limit and a monthly allowance (see pricing). Batch and query requests have a smaller per-minute allowance than single lookups because they do more work. Responses carry these headers:

• X-RateLimit-Remaining: requests left this minute.
• X-Quota-Limit and X-Quota-Used: your monthly allowance and how much of it you have used.
• Retry-After (on a 429): seconds to wait before trying again.

Only successful calls count towards your allowance. On paid plans, calls beyond the allowance keep working and are billed at your plan's overage rate; on Free, they stop until the 1st of the next month.

Errors

Status	Code	Meaning
401	unauthorised	Missing or invalid X-API-Key.
403	plan_required	Your plan does not include this endpoint.
404	word_not_found	The word is not in the dictionary.
422	unknown_locale, seed_required, bad_request, too_many, unknown_flag, filter_unavailable	Something in the request needs fixing. The message says what.
429	rate_limited	Too many requests this minute. Wait for Retry-After.
429	quota_exceeded	Free plan monthly allowance used up.

Attribution

On the Free plan, show a visible “Powered by FreeDict” link to freedict.com wherever you display our data. Free-plan responses include the text and link in meta.attribution. Paid plans do not need it. See the API terms for caching and use rules.