.. _api-gamification:

Gamification API
================

Endpoints related to fluency points, badges, and leaderboards.
All endpoints are prefixed with ``/api/gamification``.

Endpoints
---------

GET /api/gamification/fluency-points
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get the current user's fluency points, current level, points needed for the next level, and progress percentage.

**Response** ``200 OK``

.. code-block:: json

   {
     "user_id": "uuid",
     "fluency_points": 120,
     "level": "Elementary",
     "next_level_points": 150,
     "progress_to_next": 80.0
   }

GET /api/gamification/badges
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get all earned badges and the available unearned badges for the current user.

**Response** ``200 OK``

Returns an object with ``earned`` and ``available`` badge lists.

GET /api/gamification/leaderboard
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get the top users leaderboard ranked by fluency points.

**Response** ``200 OK``

Returns an array of leaderboard entries.