API Reference Overview

Complete reference for the SharpAPI v1 REST API. All endpoints return JSON and follow consistent conventions for authentication, filtering, pagination, and error handling.

Base URLPermalink for this section

https://api.sharpapi.io/api/v1

OpenAPI SpecificationPermalink for this section

The full OpenAPI 3.1 spec is available for import into tools like Postman, Insomnia, or code generators:

• Download OpenAPI Spec (JSON)

Request FormatPermalink for this section

• All requests use HTTPS
• Authentication via X-API-Key header, Authorization: Bearer header, or api_key query param
• Request bodies (where applicable) use JSON with Content-Type: application/json
• All field names are snake_case

Endpoint SummaryPermalink for this section

The REST endpoints below. All require an API key except /api/v1/health and /api/v1/deeplink/:id.

OddsPermalink for this section

EventsPermalink for this section

OpportunitiesPermalink for this section

SplitsPermalink for this section

Live Game StatePermalink for this section

StreamingPermalink for this section

Deep LinksPermalink for this section

AccountPermalink for this section

Reference DataPermalink for this section

EnterprisePermalink for this section

Historical (Enterprise)Permalink for this section

HealthPermalink for this section

Response FormatPermalink for this section

Two top-level shapes — both put data first and updated_at last, with an optional pagination block in between. There is no success field; the HTTP status code is the source of truth. See Response Conventions for the full rule set.

Paginated list responsePermalink for this section

{
  "data": [
    {
      "id": "draftkings_33483153_moneyline_PHO",
      "sportsbook": "draftkings",
      "sport": "basketball",
      "home_team": "PHI 76ers",
      "away_team": "PHO Suns",
      "market_type": "moneyline",
      "selection": "PHO Suns",
      "odds_american": -150,
      "odds_decimal": 1.667,
      "odds_probability": 0.60,
      "is_live": false
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "total": 3095,
    "has_more": true,
    "next_offset": 50,
    "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
  },
  "updated_at": "2026-01-26T02:10:37.846Z"
}

Single resource responsePermalink for this section

Used for singletons (/account, /events/:eventId) and non-paginated reference endpoints. No pagination block.

{
  "data": {
    "id": "nba_celtics_lakers_2026-02-08_b3",
    "sport": "nba",
    "home_team": "PHI 76ers",
    "away_team": "PHO Suns",
    "start_time": "2026-01-26T19:00:00Z"
  },
  "updated_at": "2026-01-26T02:10:37.846Z"
}

Error EnvelopePermalink for this section

All errors follow a consistent format:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Upgrade your plan or wait 45 seconds.",
    "docs": "https://docs.sharpapi.io/en/authentication#rate-limits"
  }
}

Standard Response HeadersPermalink for this section

Headers returned on authenticated API responses (X-Response-Cache appears only on cacheable endpoints):

Connection ReusePermalink for this section

For polling clients, the dominant cost on a fresh connection to api.sharpapi.io is the TLS handshake — typically 150–200 ms — not the API server itself, which returns in ~40–50 ms once TCP + TLS are up. Reusing a single TLS connection across requests collapses subsequent calls to roughly the server-side TTFB.

# Fresh connection — first request pays full TCP + TLS:
curl -o /dev/null -s \
  -w "ssl=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
  -H "X-API-Key: $SHARPAPI_KEY" \
  https://api.sharpapi.io/api/v1/gamestate/baseball
# → ssl=0.16s ttfb=0.20s total=0.20s
 
# Two URLs in one curl call — the second reuses the open connection:
curl -o /dev/null -s \
  -w "ssl=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
  -H "X-API-Key: $SHARPAPI_KEY" \
  https://api.sharpapi.io/api/v1/gamestate/baseball \
  https://api.sharpapi.io/api/v1/gamestate/tennis
# → ssl=0.00s ttfb=0.04s total=0.04s

RecommendationsPermalink for this section

• HTTP/1.1 keep-alive is the default in curl, Python httpx / requests.Session(), aiohttp, Node fetch / axios / undici, Go http.Client, OkHttp, and most other modern clients. Reuse a single client/session across calls — don’t construct a new client per request.
• HTTP/2 connection coalescing multiplexes many concurrent requests over one connection to the same host. Enabled by default in HTTP/2-capable clients.
• HTTP/3 (QUIC) is offered via Alt-Svc: h3=":443". Clients that opt in (curl --http3, httpx[http2,http3], Node undici with allowH2: true) skip the TCP handshake entirely on subsequent connections. Worthwhile for cold-start workloads such as serverless functions.
• For real-time data, use streaming. The /api/v1/stream endpoint keeps a single connection open and pushes deltas as they happen — no per-request handshake at all.

Tier ComparisonPermalink for this section

FilteringPermalink for this section

All list endpoints support filtering via query parameters. Filters use singular parameter names and accept comma-separated values for multi-select.

Filter ParametersPermalink for this section

ExamplesPermalink for this section

# Multiple sportsbooks (comma-separated)
curl "https://api.sharpapi.io/api/v1/odds?sportsbook=draftkings,fanduel" \
  -H "X-API-Key: YOUR_KEY"
 
# Combine filters
curl "https://api.sharpapi.io/api/v1/odds?league=nba,nhl&sportsbook=pinnacle&live=true" \
  -H "X-API-Key: YOUR_KEY"
 
# Paginate through results
curl "https://api.sharpapi.io/api/v1/odds?limit=25&offset=50" \
  -H "X-API-Key: YOUR_KEY"

Odds FormatsPermalink for this section

All odds are returned as flat fields on each odds object:

{
  "odds_american": -110,
  "odds_decimal": 1.909,
  "odds_probability": 0.5238
}

Error CodesPermalink for this section

The canonical list of error codes emitted by the API. The string in error.code is the stable contract — check it rather than the prose message.

HTTP error codesPermalink for this section

Emitted in REST responses.

WebSocket frame error codesPermalink for this section

Emitted only inside {"type": "error", "code": "..."} frames on an open WebSocket connection. They describe client-protocol mistakes and do not correspond to an HTTP status.