# System endpoints

Source: https://opvs.ai/docs/guides/system

> Public endpoints for health monitoring and system information.

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.

```http
GET /api/v1/system/health
```

### Request

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

### Response

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

### 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.

```http
GET /api/v1/system/info
```

### Request

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

### Response

```json
{
  "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

Field

Type

Description

`app_name`

string

Service name

`version`

string

Current API version (semver)

`environment`

string

Deployment environment (`production`, `staging`, `development`)

`features`

string[]

The authentication and protection features this instance runs

`endpoints`

object

Paths to the API docs, the health check and client registration

## Integration Examples

### Uptime Monitor

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

```bash
# 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

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