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",
  "timestamp": "2026-03-03T12:00:00Z",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

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¶

{
  "name": "opvs-api",
  "version": "1.0.0",
  "environment": "production",
  "docs_url": "/api/v1/docs"
}

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