Health API

Health check and heartbeat endpoints for monitoring

Health API

Monitor system health and configure heartbeat schedules.

Health check

GET /api/health

No authentication required. Returns system health metrics including CPU and memory usage.

Response

{
  "status": "ok",
  "health": "healthy",
  "timestamp": "2026-03-19T00:00:00Z",
  "cpu": {
    "usage": 15.3,
    "cores": 4
  },
  "memory": {
    "usage": 42.1,
    "total": 8589934592,
    "used": 3617054720,
    "free": 4972879872
  },
  "uptime": 86400
}

The health field reflects overall system status:

Value	Condition
healthy	CPU and memory usage both at or below 70%
degraded	CPU or memory usage above 70% but at or below 85%
unhealthy	CPU or memory usage above 85%

Error response

When the system is unhealthy, the response body uses status: "error" rather than a top-level error field:

{
  "status": "error",
  "health": "unhealthy",
  "timestamp": "2026-03-19T00:00:00Z"
}

Code	Description
500	System unhealthy. Response includes status, health, and timestamp fields.

Get heartbeat settings

GET /api/heartbeat

Requires session authentication.

Response

{
  "heartbeat": {
    "frequency": "3h",
    "enabled": true,
    "lastHeartbeat": "2026-03-19T00:00:00Z",
    "nextHeartbeat": "2026-03-19T03:00:00Z"
  },
  "message": "Heartbeat scheduling database integration pending"
}

Update heartbeat settings

POST /api/heartbeat

Requires session authentication.

Request body

Field	Type	Required	Description
frequency	string	No	Heartbeat interval (for example, 3h)
enabled	boolean	No	Enable or disable heartbeats

Response

{
  "frequency": "3h",
  "enabled": true,
  "lastUpdated": "2026-03-19T00:00:00Z",
  "lastHeartbeat": "2026-03-19T00:00:00Z",
  "nextHeartbeat": "2026-03-19T03:00:00Z",
  "message": "Heartbeat settings will persist to database once integration is complete"
}

Delete heartbeat settings

DELETE /api/heartbeat

Requires session authentication. Resets heartbeat configuration to defaults.

Response

{
  "success": true,
  "message": "Heartbeat settings reset - database cleanup will occur once integration is complete"
}