🤖 AI Insights API BETA

Access contextual word analysis, semantic relationships, and AI-generated linguistic insights programmatically. The Dictionary AI Insights API provides developers with powerful NLP endpoints for vocabulary enrichment, contextual understanding, and semantic mapping.

Base URL: https://api.dictionary.dev/v1/beta

⚠️ Beta Notice

This API is currently in active development. Endpoints, request/response schemas, and rate limits may change without notice. We recommend using semantic versioning pins in your integrations.

Authentication

All API requests require an API key passed via the X-API-Key header. Keys can be generated from your Dashboard → API Keys.

HTTP Header

X-API-Key: sk_dict_live_8f7a2b9c1d4e5f6g7h8i9j0k

Alternatively, you can pass the key as a query parameter (not recommended for production):

Query Parameter

https://api.dictionary.dev/v1/beta/insights/analyze?api_key=YOUR_KEY&term=ephemeral

Endpoints

POST /insights/analyze

Generates comprehensive AI-driven insights for a given word or phrase, including contextual definitions, connotations, usage frequency, and semantic clusters.

Request Parameters

Parameter	Type	Required	Description
term	string	Required	Word or phrase to analyze (max 100 chars)
language	string	Optional	ISO 639-1 code. Defaults to `en`
depth	string	Optional	Analysis depth: `basic`, `standard`, `deep`
include_examples	boolean	Optional	Return contextual usage examples

Example Request

curl

curl -X POST https://api.dictionary.dev/v1/beta/insights/analyze \
  -H "X-API-Key: sk_dict_live_..." \
  -H "Content-Type: application/json" \
  -d '{"term": "serendipity", "depth": "deep", "include_examples": true}'

Example Response

JSON (200 OK)

{
  "status": "success",
  "term": "serendipity",
  "insights": {
    "primary_definition": "The occurrence of events by chance in a happy or beneficial way",
    "semantic_clusters": ["luck", "fortune", "chance", "happy accident"],
    "connotation": "positive",
    "usage_frequency": 0.72,
    "ai_contextual_notes": "Often used in academic and literary contexts. Carries an optimistic, fate-driven nuance.",
    "examples": [
      "Their meeting was pure serendipity.",
      "Serendipity plays a major role in scientific discovery."
    ]
  },
  "meta": {
    "request_id": "req_9f8e7d6c5b4a",
    "latency_ms": 124,
    "credits_used": 1
  }
}

GET /insights/semantic

Returns a vector-based semantic relationship map for a given term, including synonyms, antonyms, hyponyms, and contextual neighbors.

Query Parameters

Parameter	Type	Required	Description
term	string	Required	Target word or phrase
relations	string[]	Optional	Comma-separated: `synonyms,antonyms,hyponyms,hypernyms`
limit	integer	Optional	Max results per relation type (default: 10)

Example Response

JSON (200 OK)

{
  "status": "success",
  "term": "innovation",
  "semantic_map": {
    "synonyms": ["invention", "creativity", "breakthrough"],
    "antonyms": ["stagnation", "tradition", "routine"],
    "hyponyms": ["technological innovation", "process innovation"]
  }
}

Rate Limiting & Credits

The Beta API operates on a credit-based system. Each request consumes credits based on the depth parameter and response size.

Plan	Requests / min	Depth Cost	Monthly Credits
Developer	60	1x	5,000
Team	300	0.8x	50,000
Enterprise	1,000+	Custom	Unlimited

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Handling

The API uses standard HTTP status codes. All errors return a consistent JSON structure:

Error Format

{
  "status": "error",
  "error": {
    "code": "invalid_parameter",
    "message": "The 'term' field cannot be empty.",
    "request_id": "req_x7y8z9"
  }
}

Status	Code	Description
400	invalid_request	Malformed JSON or missing required parameters
401	unauthorized	Missing or invalid API key
403	forbidden	Insufficient permissions or credit balance
429	rate_limit_exceeded	Too many requests. Check `Retry-After` header
500	internal_error	Unexpected server error. Contact support

Official SDKs

Get started quickly with our official client libraries. Community packages are also available.

🐍 Python

pip install dictionary-ai

🟨 JavaScript/Node

npm install @dictionary/ai-sdk

🐹 Go

go get github.com/dictionary-dev/ai-go