Skip to main content

API Reference

The UnDercontrol backend exposes a REST API. Its complete machine-readable specification is published here:

The raw file is a Swagger 2.0 (OpenAPI 2.0) JSON document. It covers 303 paths / 400 operations / 438 definitions — every route the server registers, including the ones the web and desktop clients use.

Base URL​

InstanceBase URL
Hostedhttps://api.oatnil.com
Self-hostedwherever you deployed it — see Self-Deployment

The specification declares host: localhost:8888. That is the code generator's development default, not a real endpoint. Substitute the base URL above.

Authentication​

Almost every route requires a JWT bearer token:

Authorization: Bearer <access_token>

Obtain one from POST /auth/v2/login, and refresh it with POST /auth/refresh-token. The specification marks this as the BearerAuth security definition. A handful of routes are public (login, register, refresh-token, health, version).

Using it with an agent​

The raw JSON is served as a plain static file, so an agent can fetch it directly:

https://oatnil.com/api/openapi.json

It is also loadable by any OpenAPI tool — Postman, Insomnia, openapi-generator, Swagger Editor — by pointing at that URL.

Provenance and freshness​

The published file is a byte-for-byte copy of go-backend/docs/swagger.json in the UnDercontrol source repository, generated by swaggo/swag from the handler annotations.

To refresh it after backend changes, regenerate the committed spec and copy it across:

cd go-backend
swag init -g cmd/server/main.go -d ./ -o docs --parseDependency --parseInternal
cp docs/swagger.json ../docusaurus-opensource/static/api/openapi.json

Then update the counts quoted above, in this file and in its Chinese mirror.

Why this is published here rather than served live

The running server exposes a Swagger UI at /swagger/index.html, but its /swagger/doc.json returns 200 with an empty body. The generated docs package is imported only under //go:build dev (go-backend/cmd/server/swagger_dev.go), while release binaries are built with -tags prod, so no specification is compiled into them. This page is the published substitute.