System endpoints

Public endpoints for health monitoring and system information. These endpoints require no authentication and are safe to poll from uptime monitors, load balancers, or CI pipelines.

Health Check

Returns the health status of the API and its dependencies.

GET /api/v1/system/health

Request

curl https://api.opvs.ai/api/v1/system/health

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "environment": "production",
  "services": {
    "postgres": "healthy",
    "redis": "healthy"
  }
}

Status Codes

Usage Notes

• Returns 200 with "status": "healthy" when all backing services (PostgreSQL, Redis) are reachable

• Returns 503 with "status": "degraded" when one or more services cannot be reached

• Response time is typically under 50ms since it only checks connection liveness, not query performance

• Safe to call at high frequency (not rate-limited)

System Info

Returns version and environment metadata about the running API instance.

GET /api/v1/system/info

Request

curl https://api.opvs.ai/api/v1/system/info

Response

{
  "app_name": "OPVS",
  "version": "1.0.0",
  "environment": "production",
  "features": [
    "Client authentication (Bearer token)",
    "Session-based dashboard auth (Better Auth)",
    "Admin API key authentication",
    "Rate limiting"
  ],
  "endpoints": {
    "docs": "/api/v1/docs",
    "health": "/api/v1/system/health",
    "register": "/api/v1/clients/register"
  }
}

Response Fields

Integration Examples

Uptime Monitor

Poll the health endpoint every 30 seconds and alert on non-200 responses:

# Simple health check script
STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://api.opvs.ai/api/v1/system/health)
if [ "$STATUS" -ne 200 ]; then
  echo "ALERT: OPVS API health check failed with status $STATUS"
fi

Docker Health Check

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/api/v1/system/health"]
  interval: 30s
  timeout: 5s
  retries: 3