Skip to Content
API ReferenceHealth Check

Health Check

Check the operational status of the SharpAPI service and how fresh its odds data is.

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.) Only GET and HEAD are accepted — see Other methods.

Example RequestsPermalink for this section

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

ResponsePermalink for this section

The response is a flat object with exactly two fields, status and newest_odds_age_s. There is no checks/timestamp wrapper, and no build or backend diagnostics are returned.

Healthy (200)Permalink for this section

{ "status": "ok", "newest_odds_age_s": 1 }

Degraded (200)Permalink for this section

The service is up but has no fresh odds data (the last completed refresh is more than 60s old, or none has completed). The HTTP code stays 200 so load balancers keep routing here during an upstream-data incident:

{ "status": "degraded", "newest_odds_age_s": 142 }

Starting (503)Permalink for this section

The process is up and listening but start-up (loading odds, priming caches) is not finished. Retry shortly:

{ "status": "starting", "newest_odds_age_s": -1 }

Down (503)Permalink for this section

A core backend dependency is unreachable:

{ "status": "down", "newest_odds_age_s": 9 }

Response HeadersPermalink for this section

X-Request-Id: 1782526326424224-82519

The health endpoint does not return rate-limit or tier headers since it does not require authentication.

Response FieldsPermalink for this section

FieldTypeDescription
statusstringOverall status: ok, degraded, starting, or down
newest_odds_age_sintegerSeconds since the API last completed a refresh of its odds data. -1 when no odds data has loaded yet. This measures the refresh cycle, not the age of any individual price.

Earlier versions of this endpoint also returned a build identifier and backend diagnostics. They are no longer part of the public response — read only status and newest_odds_age_s.

Status ValuesPermalink for this section

StatusHTTP CodeMeaning
ok200Fresh odds data is loaded (last refresh 60s ago or less)
degraded200Up, but no fresh odds data (last refresh more than 60s ago, or none loaded)
starting503Process up but start-up not finished
down503A core backend dependency is unreachable

Status LogicPermalink for this section

The overall status is derived in this order:

  1. Start-up not finished → starting (503).
  2. Core backend dependency unreachable → down (503).
  3. Stale or empty odds data (the last refresh is more than 60 seconds old, or none has completed) → degraded (200).
  4. Otherwise → ok (200).

Other methodsPermalink for this section

Any method other than GET or HEAD returns 405 Method Not Allowed with an Allow: GET, HEAD header:

curl -i -X POST "https://api.sharpapi.io/api/v1/health"
HTTP/1.1 405 Method Not Allowed Allow: GET, HEAD X-Error-Code: method_not_allowed
{ "error": { "code": "method_not_allowed", "message": "Method not allowed" } }

See HTTP error codes.

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"Newest odds: {health['newest_odds_age_s']}s old")
Last updated on