Skip to main content
Version: 1.0.0

Hoserva API

The Hoserva API. This file is the whole API: every capability the web UI or the CLI has is a documented operation here, and nothing else. The web UI and the CLI call the API only through clients generated from this specification. This version covers /api/v1/ versioning, the two authentication schemes, the shared error model, the job resource and its lifecycle, and every Server-Sent Events event type on /api/v1/events, together with the operations of each feature area. The API is extended, never replaced, as capabilities are added.

Authentication​

Web UI session, issued at login over TCP. The cookie alone is not enough, because a browser sends it to every service on the same host name whatever the port: a request authenticated with it must also carry the session's second secret in the X-Hoserva-Session-Secret header (returned by login and createFirstAdmin), or it is refused with 401 unauthorized. getCatalogTemplateIcon and getCatalogTemplateScreenshot do not need the header, since an <img> element cannot send one. A request that changes state is also refused with 403 forbidden when its Origin header is not the server's own origin or its Sec-Fetch-Site header says it came from elsewhere.

Security Scheme Type:

apiKey

Cookie parameter name:

hoserva_session