API & OpenAPI docs

Everything the admin UI does, it does over Taranac’s own REST API — the web interface is just a client. That API is fully described by an OpenAPI schema generated from the code itself, and the platform can serve that schema as interactive documentation: Swagger UI, Redoc and the raw openapi.json.

That documentation surface is off by default. It is a single environment flag away, and this page explains what you get when you turn it on, why you probably should not leave it on in production, and where to browse it without installing anything.

.env · DOCS_ENABLED

DOCS_ENABLED=false default

/docs /redoc /openapi.json 404

The schema is never generated and never leaves the box.

DOCS_ENABLED=true

Swagger UI Redoc openapi.json 200

no auth anyone who can reach the host can read the full API shape.

One flag gates all three routes. Off (the default) — /docs, /redoc and /openapi.json return 404. On — they are served, and served without authentication.

Browse it on the public demo

The quickest way to see the API is the public demo instance, which runs with the docs surface enabled on purpose:

demo.taranac.pro/docs — Swagger UI
demo.taranac.pro/redoc — Redoc, with the tags nested into collapsible domain groups
demo.taranac.pro/openapi.json — the raw schema, for generating a client

The demo runs the same images as your install, so what you read there is what your instance exposes.

The three routes

Route	What it is
`/docs`	Swagger UI — the flat, ordered tag list, with an Authorize button and try-it-out request forms
`/redoc`	Redoc — the same schema rendered as a reference document, with tags nested into domain groups (Network, AAA · TACACS+, NAC, Configuration Tracker, …)
`/openapi.json`	The raw OpenAPI schema, for client generators, Postman/Insomnia imports and API diffing

Note that all three are mounted at the application root, not under /api/. The bundled edge (the edge container) already proxies them; a third-party reverse proxy in front of Taranac that only forwards /api/* will not reach them.

Turning it on

DOCS_ENABLED lives in the .env file in your deployment bundle directory and defaults to false:

DOCS_ENABLED=false  # Swagger/Redoc/openapi.json — keep off in production

Set it to true and recreate the api container so it picks the new value up:

./taranac up -d      # recreates containers whose env changed

To turn it back off, set it to false and run ./taranac up -d again. When the flag is off, FastAPI is built with no documentation URLs at all: the three routes 404, and the schema is never even generated.

The API link in the admin UI

When the flag is on, admins get an API item in the sidebar’s Advanced section that opens /docs in a new tab. The UI reads the flag from the backend (it is carried on /auth/me as docs_enabled), so the link can never point at a disabled endpoint — no flag, no link.

What the schema documents

The schema is not raw FastAPI output — the tag taxonomy, the per-tag descriptions and the Markdown overview at the top are maintained in the product as a first-class surface, and CI fails if a route carries a tag that is not described. The conventions it documents are the same ones the whole API follows:

Convention	Behaviour
Base path	Management endpoints live under `/api/v1`. Health probes (`/healthz`, `/ready`) and a few deliberately public surfaces (captive-portal flows, CA / certificate downloads) are mounted at the root.
Auth	`POST /api/v1/auth/login` returns a token; send it as `Authorization: Bearer <token>`. In Swagger UI, paste it into Authorize.
Authorization	Endpoints are gated by RBAC permissions — `GET /api/v1/rbac/schema` lists them. Admin accounts bypass the gate.
Errors	A consistent body `{ "detail", "code", "field" }`, localized from the `Accept-Language` header (`en` / `ru`).
Validation	Request bodies are strict: unknown fields are rejected with `422`, lengths and ranges are bounded, blank optional text normalizes to `null`.
Timestamps	Stored and returned in UTC (ISO-8601); clients localize.
Pagination	List endpoints accept `page`, `per_page`, `search`, `sort_by`, `sort_order` and return `{ items, total, total_by_filter }`.

Tags are grouped by domain — Authentication & Access, Identity, Network, AAA · TACACS+, AAA · RADIUS, AAA · Policy & Logs, NAC, NAC · PKI, Configuration Tracker, Monitoring & Ops, System Settings, Reports, System — which is the fastest way to find the endpoints behind a screen you are looking at in the UI.

CLI & scripts — the ./taranac wrapper and the .env file this flag lives in
Settings reference — the runtime settings surface, edited in the UI rather than in .env
RBAC — the permissions that gate every endpoint
Versioning & releases — what a version covers, and what that means for API stability