Dictionary API Documentation

Welcome to the Dictionary API. Our RESTful interface provides programmatic access to over 15 million words across 100+ languages. Whether you're building language tools, educational platforms, or AI applications, our API is designed for speed, accuracy, and developer experience.

ℹ️

All API responses are returned in JSON format. Authentication is required for all endpoints except the health check.

Authentication

Authenticate your requests using Bearer tokens or API keys. You can generate your credentials from the Developer Dashboard.

Bearer Token (Recommended)

Include your token in the Authorization header:

HTTP Header

Authorization: Bearer sk_live_51M7v8xJ2kL9pQr4wZ

API Key

Alternatively, pass your key via the x-api-key header:

HTTP Header

x-api-key: sk_live_51M7v8xJ2kL9pQr4wZ

Base URL

All API requests should be made to:

URL

https://api.dictionary.com/v1

⚠️

Sandbox/Test mode uses https://sandbox-api.dictionary.com/v1. Ensure you switch to production URLs before deploying.

Endpoints

Search Words

GET /search

Fuzzy search across our entire dictionary. Supports partial matches, typo tolerance, and language filtering.

Parameter	Type	Description
`q` Required	string	The word or phrase to search
`lang`	string	ISO 639-1 code (default: `en`)
`limit`	integer	Max results (1-20, default: 10)

Example Request

cURL

curl -X GET "https://api.dictionary.com/v1/search?q=ephemeral&lang=en&limit=5" \\
  -H "Authorization: Bearer sk_live_51M7v8xJ2kL9pQr4wZ"

Example Response

JSON

{
  "results": [
    {
      "word": "ephemeral",
      "phonetic": "/əˈfem.ər.əl/",
      "part_of_speech": "adjective",
      "score": 0.98
    },
    {
      "word": "ephemeris",
      "phonetic": "/ɪˈfem.ər.ɪs/",
      "part_of_speech": "noun",
      "score": 0.72
    }
  ],
  "total": 12,
  "page": 1
}

GET /define/{word}

Retrieve comprehensive definitions, etymology, examples, and usage notes for a specific word.

Path Parameter	Type	Description
`word` Required	string	URL-encoded word to look up
`lang`	string	Language code (default: `en`)
`include`	string	Comma-separated: `examples,synonyms,etymology,audio`

Example Response

JSON

{
  "word": "ephemeral",
  "phonetic": "/əˈfem.ər.əl/",
  "part_of_speech": "adjective",
  "definitions": [
    {
      "definition": "Lasting for a very short time; transitory.",
      "examples": ["The ephemeral beauty of cherry blossoms."]
    }
  ],
  "etymology": "Greek ephēmeros 'lasting only a day'",
  "audio_url": "https://cdn.dictionary.com/audio/ephemeral.mp3"
}

POST /translate

Translate words or short phrases between supported language pairs with context-aware accuracy.

Request Body

JSON

{
  "text": "The quick brown fox jumps over the lazy dog",
  "source_lang": "en",
  "target_lang": "es"
}

Response

JSON

{
  "translated_text": "El rápido zorro marrón salta sobre el perro perezoso",
  "source_lang": "en",
  "target_lang": "es",
  "confidence": 0.96
}

Error Handling

The API uses standard HTTP status codes and returns detailed error objects when requests fail.

Status Code	Meaning	Description
400	Bad Request	Invalid parameters or malformed JSON
401	Unauthorized	Missing or invalid API key/token
403	Forbidden	API key lacks required permissions
404	Not Found	Word or endpoint does not exist
429	Rate Limited	Too many requests. Retry after `Retry-After` header
500	Server Error	Internal failure. Contact support if persistent

Rate Limits

Rate limits apply per API key. Exceeding limits returns a 429 status. Limits reset per minute.

Free Tier: 60 requests/minute
Pro Tier: 1,000 requests/minute
Enterprise: Custom limits (up to 50,000 req/min)

Monitor your usage via the X-RateLimit-Remaining and X-RateLimit-Reset response headers.