.. _api-index:

API Reference
=============

The LinguaAI API is a RESTful HTTP API built with FastAPI. All endpoints are
served under the ``/api`` prefix.

Base URL
--------

.. code-block:: text

   http://<host>:8000

During local development the host is typically ``127.0.0.1`` or the LAN IP
configured in ``frontend/lib/services/api_config.dart``.

Interactive Documentation
-------------------------

FastAPI automatically generates interactive documentation:

- **Swagger UI** — ``http://<host>:8000/docs``
- **ReDoc** — ``http://<host>:8000/redoc``
- **OpenAPI JSON** — ``http://<host>:8000/openapi.json``

Authentication
--------------

Protected endpoints require a JWT access token sent as a Bearer token in the
``Authorization`` header:

.. code-block:: http

   GET /api/auth/me HTTP/1.1
   Authorization: Bearer <access_token>

Tokens are obtained from the login, signup, or Google OAuth endpoints and
expire after **24 hours**. Use ``POST /api/auth/refresh`` to obtain a new
token before expiry.

Response Format
---------------

All responses use ``application/json``.

**Successful response example:**

.. code-block:: json

   {
     "access_token": "eyJhbGci...",
     "token_type": "bearer",
     "expires_in": 86400,
     "refresh_token": "...",
     "user": {
       "id": "uuid",
       "email": "user@example.com",
       "full_name": "Jane Doe",
       "avatar_url": null,
       "provider": "email",
       "proficiency_level": "Intermediate",
       "goals": ["Education"],
       "focus_areas": ["Reading", "Writing"],
       "created_at": "2026-03-06T12:00:00Z"
     }
   }

**Error response example:**

.. code-block:: json

   {
     "detail": "Invalid email or password"
   }

HTTP Status Codes
-----------------

.. list-table::
   :header-rows: 1
   :widths: 15 85

   * - Code
     - Meaning
   * - ``200``
     - Request succeeded
   * - ``201``
     - Resource created (e.g. new user on signup)
   * - ``400``
     - Bad request — invalid input or business logic error
   * - ``401``
     - Unauthorised — missing, expired, or invalid token
   * - ``422``
     - Validation error — request body failed Pydantic validation
   * - ``500``
     - Internal server error

General Endpoints
-----------------

.. list-table::
   :header-rows: 1
   :widths: 10 30 60

   * - Method
     - Path
     - Description
   * - ``GET``
     - ``/``
     - Returns the root HTML welcome page
   * - ``GET``
     - ``/health``
     - Database connectivity health check

Available Modules
-----------------

.. toctree::
   :maxdepth: 1

   auth
   dictionary
   flashcards
   lessons
   gamification
   users