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

The HireNext REST API is documented interactively using the OpenAPI 3.1 standard.

Interactive documentation (Swagger UI)
---------------------------------------

The full interactive API reference is available at:

* **HireNext API docs** — ``https://hirenext.dev.desp.space/backend/docs``

You can authenticate directly in the Swagger UI by clicking **Authorize** and completing the DESP
OAuth2 flow.

The static version of the API documentation (Swagger UI served from the DESP portal) is available
from the service registry page.

Base URL
--------

All API endpoints are prefixed with ``/api/v1/``.

Production base URL::

    https://hirenext.dev.desp.space/backend/api/v1/

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

All endpoints (except ``/auth/login``, ``/auth/callback``, ``/health``, and ``/``) require a
valid session cookie (``access_token``) obtained through the DESP OAuth2 Authorization Code flow.

Endpoint groups
---------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tag
     - Endpoints
   * - ``weather``
     - Forecast retrieval (CSV upload or saved span), parameter listing, cache management.
   * - ``spans``
     - CRUD operations for high-voltage line segments.
   * - ``dlr``
     - DLR severity map generation.
   * - ``admin``
     - Usage statistics and Polytope health monitoring (requires ``forecast_cache`` role).
   * - ``authentication``
     - Login, callback, token refresh, logout, and current-user endpoints.

Error codes
-----------

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

   * - HTTP status
     - Meaning
   * - ``400``
     - Bad request — invalid parameters or malformed input (e.g., CSV without ``lat``/``lon``
       columns).
   * - ``401``
     - Unauthorised — missing or expired session cookie.
   * - ``403``
     - Forbidden — authenticated but insufficient role/scope.
   * - ``404``
     - Not found — the requested span does not exist or does not belong to the current user.
   * - ``422``
     - Unprocessable entity — request body failed schema validation.
   * - ``500``
     - Internal server error — unexpected backend failure.