Health Check
Check the operational status of the SharpAPI service and how fresh its odds data is.
GET /api/v1/healthAuthenticationPermalink 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
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-82519The health endpoint does not return rate-limit or tier headers since it does not require authentication.
Response FieldsPermalink for this section
| Field | Type | Description |
|---|---|---|
status | string | Overall status: ok, degraded, starting, or down |
newest_odds_age_s | integer | Seconds 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
| Status | HTTP Code | Meaning |
|---|---|---|
ok | 200 | Fresh odds data is loaded (last refresh 60s ago or less) |
degraded | 200 | Up, but no fresh odds data (last refresh more than 60s ago, or none loaded) |
starting | 503 | Process up but start-up not finished |
down | 503 | A core backend dependency is unreachable |
Status LogicPermalink for this section
The overall status is derived in this order:
- Start-up not finished →
starting(503). - Core backend dependency unreachable →
down(503). - Stale or empty odds data (the last refresh is more than 60 seconds old, or none has completed) →
degraded(200). - 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"
fiPre-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")Related EndpointsPermalink for this section
- Account Info - Check your account status and limits
- API Reference Overview - Full API documentation