Health Check

Check the operational status of the SharpAPI service — Valkey connectivity, snapshot data freshness, and the running build version.

GET /api/v1/health

AuthenticationPermalink for this section

No authentication required. This is a public endpoint. (A HEAD request returns the status code only, with no body.)

Example RequestsPermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/health"

const response = await fetch('https://api.sharpapi.io/api/v1/health');
const health = await response.json();
 
if (health.status === 'ok') {
  console.log(`SharpAPI healthy (build ${health.version}, odds ${health.newest_odds_age_s}s old)`);
} else {
  console.warn(`SharpAPI status: ${health.status} — valkey=${health.valkey}, odds age=${health.newest_odds_age_s}s`);
}

import requests
 
response = requests.get('https://api.sharpapi.io/api/v1/health')
health = response.json()
 
print(f"Status:  {health['status']}")
print(f"Version: {health['version']}")
print(f"Valkey:  {health['valkey']}")
print(f"Odds age: {health['newest_odds_age_s']}s")

ResponsePermalink for this section

The response is a flat object — there is no checks/timestamp wrapper.

Healthy (200)Permalink for this section

{
  "status": "ok",
  "valkey": "ok",
  "newest_odds_age_s": 1,
  "version": "9a3294e"
}

When Pinnacle CDN-cadence reporting is available, a pinnacle panel is also included (see Optional diagnostic panels).

Degraded (200)Permalink for this section

Valkey is reachable but the in-memory store has no fresh snapshot data (newest snapshot is older than 60s, or none is loaded). The HTTP code stays 200 so load balancers keep routing here during a shared upstream-data incident:

{
  "status": "degraded",
  "valkey": "ok",
  "newest_odds_age_s": 142,
  "version": "9a3294e"
}

Starting (503)Permalink for this section

The process is up and listening but cold-start (book load, cache prime, engine boot) is not finished. Blue/green deploys gate on this:

{
  "status": "starting",
  "valkey": "ok",
  "newest_odds_age_s": -1,
  "version": "9a3294e"
}

Down (503)Permalink for this section

Valkey is unreachable:

{
  "status": "down",
  "valkey": "down",
  "newest_odds_age_s": -1,
  "version": "9a3294e"
}

Response HeadersPermalink for this section

X-Request-Id: 1782526326424224-82519

Response FieldsPermalink for this section

Status ValuesPermalink for this section

Status LogicPermalink for this section

The overall status is derived directly from two signals — there are no per-subsystem checks:

1. Cold start → starting (503) until the process finishes loading books, priming caches, and booting engines.
2. Valkey unreachable → down (503).
3. Valkey OK but stale/empty store (newest snapshot < 0 or > 60s) → degraded (200).
4. Otherwise → ok (200).

Optional diagnostic panelsPermalink for this section

pinnaclePermalink for this section

When present, reports how often Pinnacle’s CDN is publishing updates per sport/league key (a low-cadence signal, not an error). Real panel, truncated — the full map currently carries ~16 keys mixing sports (soccer, tennis) and league buckets (mlb, nba, nfl):

{
  "pinnacle": {
    "sports": {
      "soccer": { "cdn_fetch_pct_1h": 0.83, "cdn_fetch_pct_24h": 0.83 },
      "mlb":    { "cdn_fetch_pct_1h": 0.14, "cdn_fetch_pct_24h": 0.17, "note": "low cadence normal for pre-match / player props" },
      "boxing": { "cdn_fetch_pct_1h": 0.11, "cdn_fetch_pct_24h": 0.12, "note": "low cadence — Pinnacle's CDN does not publish updates frequently for this sport" }
    },
    "updated_at": "2026-07-02T18:09:36.432589794Z"
  }
}

source_healthPermalink for this section

When enabled, carries the same per-book streaming/CDN-poll health the WebSocket/SSE source_health control frame reports, for REST-only consumers and support.

Use CasesPermalink for this section

Monitoring and AlertingPermalink for this section

Use the health endpoint in your monitoring stack (Prometheus, Datadog, UptimeRobot, etc.) to detect issues:

# Simple health check for monitoring scripts
STATUS=$(curl -s https://api.sharpapi.io/api/v1/health | jq -r '.status')
if [ "$STATUS" != "ok" ]; then
  echo "ALERT: SharpAPI status is $STATUS"
fi

Pre-Request Health VerificationPermalink for this section

Check health before making critical requests:

async function safeRequest(endpoint) {
  const health = await fetch('https://api.sharpapi.io/api/v1/health')
    .then(r => r.json());
 
  if (health.status === 'down' || health.status === 'starting') {
    throw new Error(`SharpAPI is not ready (status: ${health.status})`);
  }
 
  if (health.status === 'degraded') {
    console.warn('SharpAPI is degraded - data may be stale');
  }
 
  return fetch(`https://api.sharpapi.io/api/v1${endpoint}`, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }).then(r => r.json());
}

Uptime DashboardPermalink for this section

import requests
 
response = requests.get('https://api.sharpapi.io/api/v1/health')
health = response.json()
 
print(f"SharpAPI Status: {health['status'].upper()}")
print(f"Build:           {health['version']}")
print(f"Valkey:          {health['valkey']}")
print(f"Newest odds:     {health['newest_odds_age_s']}s old")

Related EndpointsPermalink for this section

• Account Info - Check your account status and limits
• API Reference Overview - Full API documentation