REST API

Everything the web UI does, it does through the same public API. There is no private back channel.

Base path and versioning

All endpoints live under /api/v1. The actuator endpoints sit outside it, unprefixed, at /actuator/**.

The contract is described by an OpenAPI 3.1 document maintained in the qnop-api module of the main repository.

The spec is a build-time artifact

qnop does not serve the OpenAPI document at runtime — there is no /v3/api-docs and no bundled Swagger UI. Read the specification from the repository, or use the generated client and endpoint artifacts described below.

Authentication

One scheme: a bearer token in the Authorization header.

curl -H "Authorization: Bearer $TOKEN" https://qnop.example.com/api/v1/dashboard

Obtain a token from POST /api/v1/auth/login. The refresh token is returned as an HttpOnly cookie rather than in the body, so browser clients refresh without JavaScript ever touching it; POST /api/v1/auth/refresh exchanges it.

A small set of endpoints is deliberately public: GET /config and the unauthenticated auth routes (login, refresh, register, e-mail verification, forgot- and reset-password). Everything else requires the bearer token.

Resource groups

Group	Path	What it covers
Config	/config	public instance capabilities
Auth	/auth/…	login, refresh, logout, registration, password flows
Users	/users/…	profiles, own settings
Teams	/teams/…	teams and membership
Documents	/documents/…	upload, versions, rendered output, inter-version diff, workflow, participants, archive
Annotations	/annotations/…, /comments/…	annotations, placements, threads, reactions, resolve/reopen/dismiss
Search	/search/…	federated search, and per-type searches
Dashboard	/dashboard	the landing aggregate
Audit	/audit/events	the audit trail — AUDITOR or ADMIN
Administration	/admin/…	settings, OIDC providers, mail templates, users, teams, storage consistency, scheduler

Binary and multipart operations — document upload, new versions, original downloads, avatars, branding and attachments — are intentionally outside the generated contract and are documented in the repository instead.

Generated artifacts

The API model and endpoint interfaces are published to GitHub Packages under io.qnop, with sources and javadoc:

• io.qnop:qnop-api-model — the request and response types
• io.qnop:qnop-api-endpoint — the endpoint interfaces
• io.qnop:qnop-spi — the extension contract, see Extending qnop

The server modules themselves are not published as libraries; the deployable artifact is the container image.