.. _api-flashcards:

Flashcards API
==============

Endpoints related to flashcard decks.
All endpoints are prefixed with ``/api/flashcards``.

Endpoints
---------

GET /api/flashcards/decks
~~~~~~~~~~~~~~~~~~~~~~~~~

Get all flashcard decks for the current user.

**Response** ``200 OK``

Returns an array of decks, including the cards inside each deck.

POST /api/flashcards/decks
~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a new flashcard deck.

**Request Body:**

.. code-block:: json

   {
     "name": "My New Deck",
     "cards": [
       {
         "word": "Hello",
         "pronunciation": "həˈləʊ",
         "definition": "A greeting",
         "example": "Hello world"
       }
     ]
   }

**Response** ``201 Created``

Returns the newly created deck and its cards.

PUT /api/flashcards/decks/{deck_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Update a deck's name.

**Response** ``200 OK``

DELETE /api/flashcards/decks/{deck_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delete a flashcard deck and all its cards.

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

POST /api/flashcards/decks/{deck_id}/cards
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Add a new card to an existing deck.

**Response** ``201 Created``

DELETE /api/flashcards/cards/{card_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delete a specific flashcard.

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

POST /api/flashcards/generate-from-dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Auto-generate a flashcard deck from the user's personal dictionary words.

**Query Parameters:**
- ``deck_name`` (string, optional): Name for the generated deck.
- ``tag`` (string, optional): Only include words with this tag.

**Response** ``201 Created``

Returns the generated deck and its cards.