API service (@uptime/api) #
The Fastify control plane owns one local admin, sessions, monitor configuration, latency history, and request-history queries. It is used for local single-admin development and standalone PostgreSQL deployments.
Note
API Implementation Scope:
@uptime/api(apps/api): The Fastify-based standalone application.@uptime/api-worker(apps/api-worker): The unified multi-tenant API codebase used in hosted deployments. In production, it deploys to Cloudflare Workers with D1. In staging, it compiles to a Node 24 ESM bundle (pnpm --filter @uptime/api-worker build:node) running in Docker containeruptime-staging-node-apion VPS217.217.227.164backed by PostgreSQL 18.- For staging VPS operations, see the canonical VPS staging runbook.
Configuration #
Set the API variables from the repository .env.example. Generate an Argon2id
hash outside the process (for example with a short-lived local Node command) and
set it as ADMIN_PASSWORD_HASH; the service inserts the single ADMIN_EMAIL
and that hash only when admins is empty. It never accepts or persists a
plaintext password.
The app exposes /health without authentication. Protected /api operations
require the browser session, an opaque, HMAC-hashed token in an HttpOnly,
strict-SameSite cookie. Set SESSION_COOKIE_SECURE=true when serving over HTTPS.
Running #
Run after the workspace dependencies have been installed:
pnpm --filter @uptime/api typecheck
pnpm --filter @uptime/api test
pnpm --filter @uptime/api start
The isolated tests cover SSRF literal policy and deterministic aggregate status and percentile behavior. A database-backed integration suite is intentionally left to the repository integration pass, where the disposable PostgreSQL service can exercise auth, CRUD, pagination, and persisted observations.