.. _api-lessons:

Lessons API
===========

Endpoints related to field-based learning lessons.
All endpoints are prefixed with ``/api/lessons``.

Endpoints
---------

GET /api/lessons/fields
~~~~~~~~~~~~~~~~~~~~~~~

Get all available fields/categories for lessons.

**Response** ``200 OK``

Returns a list of fields and their lesson counts.

GET /api/lessons/by-field/{field}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get all lessons for a specific field.

**Response** ``200 OK``

Returns an array of lessons available within the specified field.

GET /api/lessons/{lesson_id}/questions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get all questions for a specific lesson.

**Response** ``200 OK``

Returns an array of questions, options, and correct answers.

POST /api/lessons/{lesson_id}/submit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Submit lesson answers to receive a score. If the user passes, they earn fluency points.

**Request Body:**

.. code-block:: json

   {
     "answers": {
       "question_id_1": "Selected Option A",
       "question_id_2": "Selected Option B"
     }
   }

**Response** ``200 OK``

.. code-block:: json

   {
     "lesson_id": "uuid",
     "score": 85.0,
     "total_questions": 10,
     "correct_answers": 8,
     "passed": true,
     "fluency_points_earned": 10,
     "message": "🎉 Great job! You earned 10 fluency points!"
   }