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

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

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.