.. include:: ../variables.rst
.. _challenges-api:

REST API Reference
==================

Every user-facing action in the Challenges module is backed by a REST endpoint. These are
documented here for integrators who want to drive challenges from automation, external
dashboards, or third-party reward platforms.

All endpoints are served under the configured ``{{SYSTEM.BASE.API.URL}}`` prefix and require the
``X-API-Token`` header unless noted otherwise.

.. figure:: /images/challenges/lightmode/api-postman.png
   :align: center
   :width: 90 %

|br|

Challenges
----------

.. list-table::
   :header-rows: 1
   :widths: 12 38 50

   * - Method
     - Path
     - Purpose
   * - GET
     - ``/challenges``
     - List challenges. Query params: ``search``, ``status`` (active / closed / inactive),
       ``corporation``, ``page``, ``perPage``.
   * - GET
     - ``/challenges?id=N``
     - Fetch one challenge with full settings.
   * - POST
     - ``/challenges``
     - Create. Body / query params: ``name``, ``metric``, ``scope``, ``scopeid``, ``threshold``,
       ``comparator``, ``startdate``, ``enddate``, ``rewardpoints``, ``rewardbadgeid``, plus
       optional ``hcptypefilter``, ``priorperiodstart``, ``priorperiodend``, ``streakthreshold``,
       ``autoclose``, ``teamid``, ``rulejson``.
   * - PUT
     - ``/challenges?id=N``
     - Update. Same fields as create.
   * - DELETE
     - ``/challenges?id=N``
     - Delete with full cascade (results + ledger + badge grants).
   * - POST
     - ``/challenges/clone?id=N``
     - Duplicate as a new inactive challenge.
   * - POST
     - ``/challenges/compute?id=N``
     - Rewrite the results snapshot.
   * - POST
     - ``/challenges/preview?id=N``
     - Dry-run close. Returns projected winners + points without mutating.
   * - POST
     - ``/challenges/close?id=N``
     - Final close: award points, grant badges, evaluate auto-rules, queue notifications.
   * - POST
     - ``/challenges/autoclose-run``
     - Cron hook; closes all eligible challenges whose ``enddate`` has passed.
   * - GET
     - ``/challenges/results?id=N``
     - Leaderboard snapshot rows.
   * - GET
     - ``/challenges/results.csv?id=N``
     - CSV download of the leaderboard.

Points ledger
-------------

.. list-table::
   :header-rows: 1
   :widths: 12 38 50

   * - Method
     - Path
     - Purpose
   * - GET
     - ``/challenges/points``
     - Ledger list. Query params: ``participanttype``, ``participantid``, ``page``, ``perPage``.
       Response includes ``totalpoints`` (sum) and ``totalrows`` (pagination total).
   * - POST
     - ``/challenges/points/spend``
     - Record a redeem / expire / adjust. Query params: ``participanttype``,
       ``participantid``, ``points`` (positive magnitude), ``reason`` (1=redeem, 2=expire,
       3=adjust), ``notes``.
   * - GET
     - ``/challenges/badges-awarded``
     - Badge-grant list with the same filter shape as points. Paginated.

Participant profile
-------------------

.. list-table::
   :header-rows: 1
   :widths: 12 38 50

   * - Method
     - Path
     - Purpose
   * - GET
     - ``/challenges/participant``
     - Aggregate for one participant. Query params: ``participanttype``, ``participantid``.
       Response: ``balance``, ``earned``, ``spent``, ``badgecount``, ``badges[]``,
       ``activechallenges[]``, ``recentactivity[]``.

Teams
-----

.. list-table::
   :header-rows: 1
   :widths: 12 38 50

   * - Method
     - Path
     - Purpose
   * - GET
     - ``/challenges/teams``
     - List teams. Optional ``corporation=`` filter.
   * - GET
     - ``/challenges/teams?id=N``
     - One team with its ``members`` array.
   * - POST
     - ``/challenges/teams``
     - Create. Fields: ``name``, ``description``, ``corporation``.
   * - PUT
     - ``/challenges/teams?id=N``
     - Update.
   * - DELETE
     - ``/challenges/teams?id=N``
     - Soft delete (``active = 0``).

Badges
------

.. list-table::
   :header-rows: 1
   :widths: 12 38 50

   * - Method
     - Path
     - Purpose
   * - GET
     - ``/badges``
     - List badges. Query params: ``search``, ``corporation``, ``includeinactive``.
   * - GET
     - ``/badges?id=N``
     - One badge.
   * - POST
     - ``/badges``
     - Create. Fields: ``name``, ``description``, ``icon``, ``color``, ``tier``, ``active``.
   * - PUT
     - ``/badges?id=N``
     - Update.
   * - DELETE
     - ``/badges?id=N``
     - Soft delete.
   * - GET
     - ``/badges/auto-rules``
     - List badge auto-rules.
   * - POST
     - ``/badges/auto-rules``
     - Create rule. Fields: ``badgeid``, ``rule_type`` (0-2), ``threshold``.
   * - DELETE
     - ``/badges/auto-rules?id=N``
     - Delete a rule (does not revoke granted badges).

Error responses
---------------

All endpoints return ``application/json`` on error with an ``error`` string and, where
appropriate, a ``field`` hint. HTTP status codes follow the usual convention:

* ``400`` -- validation (bad enum, missing required field).
* ``403`` -- role denied (admin required).
* ``404`` -- record not found.
* ``409`` -- conflict (e.g. spend would overdraw the ledger balance).
* ``500`` -- unexpected server error -- details in the server log.

Example: close a challenge from curl
------------------------------------

.. code-block:: bash

   curl -X POST \
     -H 'X-API-Token: <token>' \
     'https://your-server/challenges/close?id=42'

   # {"success":true}

Example: paginated ledger for an auditor
----------------------------------------

.. code-block:: bash

   curl -H 'X-API-Token: <token>' \
     'https://your-server/challenges/points?participanttype=2&participantid=17&page=1&perPage=100'