Infrastructure

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

The examples use the OYSTER_URL environment variable to hold the base URL of your Oyster server.

Health check (liveness)

GET /health

Always returns 200 OK. Use this as a Kubernetes liveness probe or a basic check that the server is running.

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"
}

Field	Type	Description
ready	boolean	true if all dependencies are healthy
database	string or absent	"unreachable" if the database is down
pearl	string or absent	"unreachable" if the Pearl wallet service is down

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

How to scrape 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:

Metric	Type	Description
oyster_active_accounts	gauge	Total number of accounts
oyster_active_blobs	gauge	Number of active blobs
oyster_blob_store_operations_total	counter	Blob store operations (labels: operation, result)

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"

What is the Pearl wallet service?

Pearl is the custodial wallet service that derives each Oyster account's Sui wallet. When Pearl is not configured or is unreachable, /ready reports pearl as "unreachable", and GET /api/v1/account/wallet returns 503. See What is Pearl?.

What other metrics does the server export?

The metrics table lists only part of what the server exports. The server also records HTTP request metrics through its track_http_metrics middleware, and exports additional counters. One example is oyster_delete_db_only_total, a counter of delete_blob calls where the onchain Sui delete transaction failed with a non-InsufficientBalance error but Oyster still removed the database row to keep DELETE idempotent. Its reason label takes the values upstream_error, internal_error, or other. A nonzero rate means onchain PooledBlob orphans are accumulating. The server refreshes the oyster_active_accounts and oyster_active_blobs gauges from the database on each scrape.