.. _api-dictionary:

Dictionary API
==============

Endpoints related to the personal dictionary and dictionary lookups.
All endpoints are prefixed with ``/api/dictionary``.

Endpoints
---------

GET /api/dictionary/lookup
~~~~~~~~~~~~~~~~~~~~~~~~~~

Look up a word definition from the Free Dictionary API.

**Query Parameters:**
- ``word`` (string, required): The word to look up.

**Response** ``200 OK``

.. code-block:: json

   {
     "word": "hello",
     "pronunciation": "həˈləʊ",
     "part_of_speech": "noun, exclamation",
     "short_definition": "an utterance of “hello”; a greeting.",
     "full_definition": "an utterance of “hello”; a greeting.",
     "examples": ["she was getting polite nods and hellos from people"],
     "synonyms": ["greeting", "welcome"]
   }

GET /api/dictionary/words
~~~~~~~~~~~~~~~~~~~~~~~

Get all dictionary words for the current user.

**Query Parameters:**
- ``search`` (string, optional): Search query for word or definition.
- ``tag`` (string, optional): Filter by tag.
- ``favorite`` (boolean, optional): Filter favorites only.

**Response** ``200 OK``

Returns an array of saved words.

POST /api/dictionary/words
~~~~~~~~~~~~~~~~~~~~~~~~~~

Add a new word to the personal dictionary.

**Request Body:**

.. code-block:: json

   {
     "word": "hello",
     "short_definition": "a greeting",
     "full_definition": "an utterance of 'hello'",
     "pronunciation": "həˈləʊ",
     "part_of_speech": "noun",
     "examples": [],
     "synonyms": [],
     "tags": ["basics"],
     "personal_notes": "First word learned",
     "is_favorite": true
   }

**Response** ``201 Created``

Returns the newly created word document.

PUT /api/dictionary/words/{word_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Update an existing dictionary word.

**Response** ``200 OK``

Returns the updated word.

DELETE /api/dictionary/words/{word_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delete a dictionary word.

**Response** ``204 No Content``

GET /api/dictionary/words/{word_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get a specific dictionary word by ID.

**Response** ``200 OK``