Health API
Public liveness and deployment-info probes for load balancers, Docker health checks, and clients discovering how an instance is configured.
The Health API is how anything outside Alaf Server checks that an instance is alive and learns how it's set
up — its version, auth mode, and which cloud (if any) it targets. Load balancers and Docker health checks
hit GET /api/health; the CLI and dashboard read GET /api/health/env to decide which login flow to show.
From the terminal it's the alaf server status command. Both routes are available on every
instance (self-hosted, desktop, and cloud).
Base path & auth
All paths are relative to your instance, under /api — e.g. https://your-host/api/health.
Both endpoints are public — no token or session is required, so probes work before login and from
load balancers. Authenticated calls elsewhere send a personal access token as a bearer header
(Authorization: Bearer <token>, created with alaf server token create); the dashboard
uses a session cookie. See the API overview and auth model for details.
Endpoints
| Method & path | Permission | What it does |
|---|---|---|
GET /api/health | public | Liveness probe — returns { status, timestamp }. |
GET /api/health/env | public | Static deployment info: mode, version, auth/team mode, and cloud URLs. |
Liveness probe
GET /api/healthReturns 200 with a fixed body as long as the process is serving requests. Use it as a container or
load-balancer health check — it touches no database and never requires auth.
curl https://your-host/api/health
# → {"status":"ok","timestamp":"2026-07-19T04:29:00.000Z"}Deployment info
GET /api/health/envStatic, cache-friendly description of how the instance is configured. Clients read this to pick the right
login flow and to reach the correct cloud endpoints — the dashboard uses these values rather than a
hard-coded table. Reads that depend on the database (teamMode, migration fields) fall back to safe
defaults if the settings table is unavailable mid-migration, so this route stays up.
The response shape:
Prop
Type
curl https://your-host/api/health/env# Same info from the CLI (add --json for the raw payload):
alaf server statusErrors you might see
Connection refused / timeout
These routes never return an auth or permission error — a failure means the process isn't reachable
(wrong host/port, container still starting, or the instance is down). alaf server status reports this as
Cannot reach the API at <url>. Confirm the instance is running and the URL is correct, then retry.