System¶

Operational system endpoints.

Endpoints¶

Method	Path	Auth	Description
`GET`	`/api/health`	Requires `X-Client-Key`	Returns service and environment health status

GET /api/health¶

Returns health checks for core dependencies and environment configuration.

Authentication¶

Requires X-Client-Key unless DISABLE_CLIENT_AUTH=true.

Response¶

200 OK when all checks pass.

503 Service Unavailable when at least one check fails.

{
  "status": "ok",
  "version": "2.0.0",
  "checks": {
    "postgres": "ok",
    "redis": "ok",
    "s3": "ok",
    "mail": "ok",
    "agora": "ok",
    "env": "ok"
  },
  "env": {
    "environment": "deployed",
    "missingRequired": [],
    "missingGroups": []
  }
}

Fields¶

Field	Type	Description
`status`	`"ok" \\| "degraded"`	Aggregated health status
`checks.postgres`	`"ok" \\| "error"`	PostgreSQL connectivity check
`checks.redis`	`"ok" \\| "error"`	Redis ping check
`checks.s3`	`"ok" \\| "error"`	Storage bucket reachability check
`checks.mail`	`"ok" \\| "error"`	SMTP transport verification
`checks.agora`	`"ok" \\| "error"`	Presence check for Agora credentials
`checks.env`	`"ok" \\| "error"`	Required environment variable completeness check
`env.environment`	`"development" \\| "deployed"`	Runtime environment classification
`env.missingRequired`	`string[]`	Missing required variable names
`env.missingGroups`	`string[]`	Missing requirement groups (for example `mail`, `storage`)

Notes¶

Degraded status

In deployed environments, if required env variables are missing, checks.env becomes error, status becomes degraded, and the endpoint returns 503.

Storage requirements

For deployed environments, one full storage configuration must be present: either S3-compatible (STORAGE_*) or R2 (R2_*).