Health Check

Check the operational status of the SharpAPI service, including backend connectivity and data freshness.


GET /api/v1/health

Authentication

No authentication required. This is a public endpoint.

Example Requests

cURL


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

JavaScript


const response = await fetch('https://api.sharpapi.io/api/v1/health');
const health = await response.json();
 
if (health.status === 'ok') {
  console.log('SharpAPI is healthy');
} else {
  console.warn(`SharpAPI status: ${health.status}`);
  for (const [name, check] of Object.entries(health.checks)) {
    if (check.status !== 'ok') {
      console.warn(`  ${name}: ${check.status} - ${check.message}`);
    }
  }
}

Python


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']}")
 
for name, check in health['checks'].items():
    icon = 'OK' if check['status'] == 'ok' else 'WARN'
    print(f"  [{icon}] {name}: {check.get('message', 'healthy')}")

Response

Healthy (200)


{
  "status": "ok",
  "version": "v1",
  "timestamp": "2026-02-08T15:00:00.123Z",
  "checks": {
    "redis": {
      "status": "ok",
      "latency_ms": 2
    },
    "data": {
      "status": "ok",
      "message": "5 sportsbook snapshots available"
    },
    "schema": {
      "status": "ok",
      "message": "All 14 required fields present"
    }
  },
  "eventLoop": {
    "min": 0.1,
    "max": 2.5,
    "mean": 0.4,
    "p99": 1.8
  }
}

Degraded (200)

When the service is partially functional, the status will be degraded:


{
  "status": "degraded",
  "version": "v1",
  "timestamp": "2026-02-08T15:00:00.123Z",
  "checks": {
    "redis": {
      "status": "ok",
      "latency_ms": 5
    },
    "data": {
      "status": "degraded",
      "message": "No snapshot data in Redis"
    },
    "schema": {
      "status": "degraded",
      "message": "Schema drift: missing fields [selectionType] in draftkings snapshot"
    }
  }
}

Down (503)

When the service is unable to function, the status will be down and the HTTP status code will be 503:


{
  "status": "down",
  "version": "v1",
  "timestamp": "2026-02-08T15:00:00.123Z",
  "checks": {
    "redis": {
      "status": "down",
      "message": "Redis unreachable"
    }
  }
}

Response Headers


X-Request-Id: req_health456def

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

Response Fields

Top-Level Fields

Field	Type	Description
`status`	string	Overall system status: `ok`, `degraded`, or `down`
`version`	string	Current API version
`timestamp`	string	ISO 8601 timestamp of this health check
`checks`	object	Individual subsystem health checks

Status Values

Status	HTTP Code	Meaning
`ok`	200	All systems operational
`degraded`	200	Functional but with reduced performance or stale data
`down`	503	Service is unavailable

Redis Check

Field	Type	Description
`status`	string	Redis connectivity status: `ok` or `down`
`latency_ms`	number \| null	Round-trip latency to Redis in milliseconds
`message`	string	Human-readable status message

Data Check

Field	Type	Description
`status`	string	Data freshness status: `ok` or `degraded`
`message`	string	Human-readable status message (e.g., “5 sportsbook snapshots available”)

Schema Check

Included on GET requests only (not HEAD). Verifies that upstream snapshot data contains all required fields.

Field	Type	Description
`status`	string	Schema compatibility status: `ok` or `degraded`
`message`	string	Human-readable status message (e.g., “All 14 required fields present”)

Event Loop

Optional object included when event loop monitoring is active. Reports main-thread delay statistics to detect blocking operations.

Field	Type	Description
`min`	number	Minimum event loop delay (ms)
`max`	number	Maximum event loop delay (ms)
`mean`	number	Mean event loop delay (ms)
`p99`	number	99th percentile event loop delay (ms)

Status Logic

The overall status is determined by the worst individual check:

ok - All checks are ok
degraded - At least one check is degraded, none are down
down - At least one check is down

Data Availability

Condition	Status	Description
1+ sportsbook snapshots	`ok`	Snapshot data available in Redis
0 snapshots in Redis	`degraded`	No snapshot data found
Redis unreachable	(not checked)	Data check is skipped when Redis is down

Use Cases

Monitoring and Alerting

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 Verification

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') {
    throw new Error('SharpAPI is currently down');
  }
 
  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 Dashboard


import requests
from datetime import datetime
 
response = requests.get('https://api.sharpapi.io/api/v1/health')
health = response.json()
 
print(f"SharpAPI Status: {health['status'].upper()}")
print(f"Version: {health['version']}")
print(f"Checked at: {health['timestamp']}")
print()
 
for name, check in health['checks'].items():
    status_icon = {'ok': 'PASS', 'degraded': 'WARN', 'down': 'FAIL'}
    print(f"  [{status_icon.get(check['status'], '???')}] {name}: {check.get('message', 'healthy')}")
 
    if name == 'redis' and check.get('latency_ms') is not None:
        print(f"        Latency: {check['latency_ms']}ms")

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