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

Code	Meaning
200	All services healthy
503	One or more services degraded or unreachable

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

Field	Type	Description
name	string	Service identifier
version	string	Current API version (semver)
environment	string	Deployment environment (production, staging, development)
docs_url	string	Path to the interactive Swagger/OpenAPI documentation

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