Health & telemetry · OwnMediaHost Docs

Health endpoints do not require authentication and are accessible directly by external monitoring services, load balancers, and decoupled public status pages (such as OwnMediaHost-status). All health endpoints automatically set Access-Control-Allow-Origin: * to allow seamless client-side browser probing.

`GET /health`

Comprehensive system telemetry endpoint. Runs a live database probe, measures database query latency, calculates process uptime, and retrieves host disk capacity.

bash

curl https://api.example.com/health

Response (200 OK):

json

{
  "status": "operational",
  "version": "0.1.0",
  "app_env": "production",
  "uptime_seconds": 86420,
  "database": {
    "status": "connected",
    "query_latency_ms": 0.42,
    "total_media_count": 1284,
    "total_media_bytes": 15829374020
  },
  "storage": {
    "total_disk_bytes": 512000000000,
    "available_disk_bytes": 420000000000
  }
}

Telemetry Fields:

Field	Type	Description
`status`	string	`"operational"` when database responds; `"degraded"` if query fails
`version`	string	Installed platform semantic version (e.g. `"0.1.0"`)
`app_env`	string	Runtime environment (`"production"` or `"development"`)
`uptime_seconds`	integer	Continuous process runtime in seconds
`database.status`	string	SQLite connection status (`"connected"` or `"error"`)
`database.query_latency_ms`	float	Execution time of `SELECT 1` probe in milliseconds
`database.total_media_count`	integer	Number of active (non-deleted) media files in catalog
`database.total_media_bytes`	integer	Total file size in bytes stored on disk
`storage.total_disk_bytes`	integer	Total storage capacity of primary disk partition
`storage.available_disk_bytes`	integer	Free available space in bytes on primary disk partition

`GET /health/ready`

Readiness probe for reverse proxies (Caddy, Nginx) and orchestrators. Returns 200 OK only when the SQLite database is healthy and ready to accept queries; otherwise returns 500 Internal Server Error.

bash

curl https://api.example.com/health/ready

Response (200 OK):

json

{
  "success": true,
  "data": "ready"
}

`GET /health/live`

Sub-millisecond liveness probe. Instantly returns HTTP 200 OK with raw text "live" to confirm process liveness without performing database or I/O operations.

bash

curl https://api.example.com/health/live

Response (200 OK):

text

live

`GET /api/v1`

API root. Returns version info and a directory of all endpoint groups.

bash

curl https://api.example.com/api/v1

Response:

json

{
  "name": "OwnMediaHost API v1",
  "version": "1.0",
  "status": "operational",
  "endpoints": {
    "auth": "/api/v1/auth",
    "files": "/api/v1/files",
    "folders": "/api/v1/folders",
    "keys": "/api/v1/keys",
    "aliases": "/api/v1/aliases",
    "storage": "/api/v1/storage",
    "activity": "/api/v1/activity",
    "settings": "/api/v1/settings"
  }
}

`GET /api/v1/storage/stats`

Returns real-time disk and storage usage statistics.

Auth required: Yes

bash

curl -H "X-API-Key: YOUR_KEY" https://api.example.com/api/v1/storage/stats

Response:

json

{
  "success": true,
  "data": {
    "total_disk_bytes": 53687091200,
    "available_disk_bytes": 41943040000,
    "used_disk_bytes": 11744051200,
    "media_storage_bytes": 8589934592,
    "images_usage_bytes": 3221225472,
    "videos_usage_bytes": 5368709120,
    "thumbnails_usage_bytes": 104857600,
    "total_files_count": 342,
    "total_images_count": 280,
    "total_videos_count": 62,
    "total_trash_count": 5
  }
}