Infrastructure

These endpoints are used for health monitoring and observability. They do not require authentication and are not under the /api/v1/ prefix.

Health Check (Liveness)

GET /health

Always returns 200 OK. Use this as a Kubernetes liveness probe or a simple "is the server running?" check.

Example:

curl -s "$OYSTER_URL/health" | jq

Response (200 OK):

{
  "status": "ok"
}

Readiness Check

GET /ready

Returns 200 OK when all dependencies are healthy, or 503 Service Unavailable if any dependency is unreachable. Use this as a Kubernetes readiness probe to gate traffic until the server is fully operational.

Example:

curl -s "$OYSTER_URL/ready" | jq

Response (200 OK, all healthy):

{
  "ready": true
}

Response (503 Service Unavailable, degraded):

{
  "ready": false,
  "database": "unreachable",
  "pearl": "unreachable"
}

The database and pearl fields are only present when the corresponding service is unhealthy.

Prometheus Metrics

GET /metrics

Returns metrics in Prometheus text exposition format. Scrape this endpoint with Prometheus, Grafana Agent, or any compatible collector.

Example:

curl -s "$OYSTER_URL/metrics"

Response (200 OK):

# HELP oyster_active_accounts Number of active accounts
# TYPE oyster_active_accounts gauge
oyster_active_accounts 42

# HELP oyster_active_blobs Number of active blobs
# TYPE oyster_active_blobs gauge
oyster_active_blobs 1337

# HELP oyster_blob_store_operations_total Blob store operations
# TYPE oyster_blob_store_operations_total counter
oyster_blob_store_operations_total{operation="store",result="success"} 500
oyster_blob_store_operations_total{operation="read",result="success"} 2000
oyster_blob_store_operations_total{operation="delete",result="success"} 100

Available metrics:

OpenAPI Documentation

GET /api/docs

Serves an interactive API documentation UI (powered by Scalar). Open this URL in your browser to explore and test all endpoints interactively.

open "$OYSTER_URL/api/docs"