API Reference

Base URL, authentication and the built-in schema pages of the REST API.

Everything the web interface does goes through the REST API, so you can use the same API from scripts and other tools. This page covers how to reach the API and how to authenticate. The built-in schema pages list the endpoints themselves.

Base URL

https://<forestall-host>:8443/api/v1/

8443 is the REST API port set by the installer (see Requirements).

Authentication

Every request, except login, token refresh and a few public routes, needs an Authorization header. There are two ways to authenticate.

Personal API token (recommended for scripts and integrations). Create a token in Profile Menu > API Tokens and send it with every request:

Authorization: Api-Token <token>

A token acts with your own account and role. It keeps working until it expires or you revoke it. See API Tokens.

JWT access token. Exchange a username and password for a token pair:

curl -X POST https://<forestall-host>:8443/api/v1/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "<username>", "password": "<password>"}'

The response contains an access and a refresh token. Send the access token as Authorization: Bearer <access>. When it expires, get a new one from POST /api/v1/token/refresh/ with {"refresh": "<refresh>"}. Token lifetimes follow Settings > Authentication (see Authentication).

Schema pages

The API describes itself in two interactive pages served by the API host:

Page	URL
Swagger UI	https://<forestall-host>:8443/api/v1/schema/
Scalar	https://<forestall-host>:8443/api/v1/schema/scalar/
Raw schema (OpenAPI 2.0 JSON)	https://<forestall-host>:8443/api/v1/schema/swagger.json

Without a signed-in session, the schema lists only the public endpoints. To see all endpoints, click Django Login on either page and sign in with a local user that has the Admin role.

MCP

The same API tokens authenticate the Forestall MCP server at https://<forestall-host>:8443/api/v1/mcp. The API Tokens page shows ready-to-copy client configurations. See API Tokens.