Skip to Content
API ReferenceOverview

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

Always use api.sharpapi.io as the base URL, not sharpapi.io.

OpenAPI SpecificationPermalink for this section

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

This spec covers all endpoints, request/response schemas, and authentication requirements.

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

MethodPathAuthMin Tier
GET/api/v1/oddsYesFree
GET/api/v1/odds/deltaYesFree
GET/api/v1/odds/bestYesFree
GET/api/v1/odds/comparisonYesFree
POST/api/v1/odds/batchYesFree
GET/api/v1/odds/closingYesPro

EventsPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/eventsYesFree
GET/api/v1/events/:eventIdYesFree
GET/api/v1/events/:eventId/oddsYesFree
GET/api/v1/events/:eventId/marketsYesFree

OpportunitiesPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/opportunities/evYesPro
GET/api/v1/opportunities/arbitrageYesHobby
GET/api/v1/opportunities/middlesYesPro
GET/api/v1/opportunities/middles/summaryYesPro
GET/api/v1/opportunities/middles/:idYesPro
GET/api/v1/opportunities/low_holdYesPro

SplitsPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/splitsYesPro
GET/api/v1/splits/historyYesPro

Live Game StatePermalink for this section

MethodPathAuthMin Tier
GET/api/v1/gamestateYesGame State add-on
GET/api/v1/gamestate/:sportYesGame State add-on

StreamingPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/streamYesWebSocket add-on
GET/api/v1/stream/oddsYesWebSocket add-on
GET/api/v1/stream/opportunitiesYesWebSocket add-on
GET/api/v1/stream/allYesWebSocket add-on
GET/api/v1/stream/events/:eventIdYesWebSocket add-on
GET/api/v1/stream/gamestateYesGame State add-on
MethodPathAuthMin Tier
GET/api/v1/deeplink/:idNo-
POST/api/v1/deeplinks/batchYesFree

AccountPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/accountYesFree
GET/api/v1/account/usageYesFree
GET/api/v1/account/keysYesFree
POST/api/v1/account/keysYesFree
DELETE/api/v1/account/keys/:keyIdYesFree
POST/api/v1/account/keys/:keyId/rotateYesFree

Reference DataPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/sportsYesFree
GET/api/v1/leaguesYesFree
GET/api/v1/sportsbooksYesFree
GET/api/v1/marketsYesFree
GET/api/v1/teamsYesFree
GET/api/v1/injuriesYesEnterprise

EnterprisePermalink for this section

MethodPathAuthMin Tier
GET/api/v1/futuresYesEnterprise
GET/api/v1/futures/oddsYesEnterprise

Historical (Enterprise)Permalink for this section

MethodPathAuthMin Tier
GET/api/v1/historical/oddsYesEnterprise
GET/api/v1/historical/odds/movementsYesEnterprise
GET/api/v1/historical/odds/closingYesEnterprise
GET/api/v1/historical/odds/clvYesEnterprise

/api/v1/historical/odds/movements needs event_id, sportsbook (1 to 5 sportsbook IDs, comma-separated) and market (one market type, e.g. point_spread). Optional from and to (RFC 3339 or Unix seconds; from inclusive, to exclusive) narrow it to a time window, for example the last two hours before kickoff. Rows come oldest first, 1,000 per request by default (limit, up to 10,000); data.truncated: true means more rows exist, so narrow the window. is_opening: true marks the first time SharpAPI observed this selection in this series; it is not the market’s opening price.

The historical-odds tree was reorganized in June 2026 so every view nests under /api/v1/historical/*. The old paths /api/v1/historical/clv and /api/v1/odds/historical still work as deprecated aliases (responses carry Deprecation: true and a Link header pointing to the canonical path) — use /api/v1/historical/odds/clv and /api/v1/historical/odds in new integrations. No withdrawal date has been announced; the old paths will not be removed without advance notice.

HealthPermalink for this section

MethodPathAuthMin Tier
GET/api/v1/healthNo-

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" }
FieldDescription
dataArray of results
pagination.limitMaximum items per page (default: 50, max: 200)
pagination.offsetCurrent offset into results
pagination.countNumber of items returned in this response
pagination.totalTotal matching items across all pages. Omitted on endpoints that can’t compute it cheaply (e.g. /odds).
pagination.has_moreWhether more results exist beyond this page
pagination.next_offsetOffset value to use for the next page. Prefer next_cursor on live-data endpoints.
pagination.next_cursorOpaque cursor for the next page. Pass as ?cursor= — stable against live data changes. Recommended for multi-page scans. Sent by the cursor-supporting endpoints (/odds, /events, /teams) and omitted on the last page. /odds/delta takes no cursor and always sends null here — it pages with next_offset + since.
updated_atISO 8601 timestamp of when the data was last refreshed

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": "basketball", "league": "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" } }
FieldDescription
error.codeMachine-readable error code
error.messageHuman-readable description
error.docsLink to relevant documentation (optional — included on auth, tier, rate limit, and streaming errors)
error.correct_endpointThe correct endpoint to use (optional — included on unknown_endpoint errors when the API recognizes the path as a known wrong route)
error.retry_afterUnix-millisecond timestamp of when the next request window opens — not a seconds duration (optional — included on rate_limited errors). For a seconds-based delay, read the standard Retry-After response header.
error.addonThe add-on that unlocks the request: game_state or websocket (optional — included when a request is refused for a missing add-on)
error.upgradeLink to the checkout or billing page that unlocks the request (optional — see Upgrade fields)
error.upgrade_noteOne-line note naming the plan or add-on that unlocks the request, and its price (optional — always sent together with upgrade)

Upgrade fieldsPermalink for this section

When a 403 tier_restricted refusal can be lifted by a self-serve plan (Hobby, Pro or Sharp) or by an add-on, the error object also carries upgrade (a link to that plan’s checkout, or to the add-on on the billing page) and upgrade_note (a one-line note). The message then has the plan or add-on, its price and a link appended after the original sentence. The 403 examples on the EV and arbitrage pages show the full body.

  • code, tier, required_tier and docs are unchanged, and no field was removed. The two new fields are only added.
  • A refusal that only Enterprise lifts carries neither field, and its message is the original sentence alone.
  • Match on error.code, never on the message text: the appended sentence names a price and a link, and both can change. Read the link from upgrade rather than parsing it out of message.
  • rate_limited errors can carry upgrade and upgrade_note too, when a higher tier raises your limit.

Standard Response HeadersPermalink for this section

Headers returned on authenticated API responses (X-Response-Cache appears only when an answer was served from the response cache):

HeaderExampleDescription
X-RateLimit-Limit300Maximum requests per minute for your tier
X-RateLimit-Remaining299Requests remaining in the current window
X-RateLimit-Reset1705804800Unix timestamp when the rate limit resets
X-Data-Delay0Data delay in seconds (60 for Free, 0 for paid tiers)
X-Request-Id1782526326424224-82519Unique request identifier for debugging and support
X-Response-CacheHITSent only when the answer was served from the server-side response cache (a sub-second-TTL cache on odds, reference data and opportunities) instead of being recomputed. A freshly computed answer has no X-Response-Cache header
Alt-Svch3=":443"; ma=86400Indicates HTTP/3 (QUIC) is available on this host. Clients that opt in skip the TCP + TLS handshake on subsequent connections — see Connection Reuse below

Include the X-Request-Id value when contacting support about a specific request.

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.

For a polling client hitting /api/v1/odds once per second, the TLS cost amortizes to ~0 after the first request. The 150 ms handshake matters most for serverless / short-lived clients that close the connection between calls.

Tier ComparisonPermalink for this section

FeatureFreeHobbyProSharpEnterprise
Sportsbooks2 (DK, FD)51525 (choose any)All (unlimited)
Data Delay60s0s0s0s0s
Requests/min121203001,000Custom
PinnacleNoNoNoYesYes
ArbitrageNoYesYesYesYes
EV / Middles / Low Hold / SplitsNoNoYesYesYes
StreamingNoAdd-onAdd-onAdd-onIncluded
Batch max events10105050100

Streaming requires the WebSocket add-on ($99/mo on Hobby and Pro, $149/mo on Sharp). Enterprise includes streaming at no extra cost.

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

ParameterTypeExampleDescription
sportsbookstringdraftkings,fanduelFilter by one or more sportsbooks
sportstringbasketball,footballFilter by sport. Takes sport ids only; a league id such as nba goes in league (see below)
leaguestringnba,nflFilter by league
marketstringmoneyline,spreadFilter by market type
event_idstringnba_celtics_lakers_2026-02-08_b3Filter by event ID
is_livebooleantrueOnly live/in-progress events
sortstring-odds_americanSort field with optional - prefix for descending. Supported on the opportunities endpoints; ignored on odds endpoints.
min_oddsnumber-110Minimum American odds filter
max_oddsnumber200Maximum American odds filter
group_bystringeventGroup results by field
limitnumber25Results per page (default: 50, max: 200)
offsetnumber50Pagination offset. May produce duplicate rows on live endpoints when data changes between requests.
cursorstring—Opaque cursor from next_cursor. Recommended for multi-page scans over live data — eliminates offset drift.

Deprecated aliasesPermalink for this section

Older spellings of two filters are still accepted: event for event_id, and live for is_live. They return the same rows, so nothing breaks — but the response carries Deprecation: true and a Warning header, and these names may be withdrawn in a future version. Use the canonical names above in new code. No withdrawal date has been announced and the response carries no Sunset header; the aliases will not be withdrawn without advance notice.

League ids in sportPermalink for this section

sport takes a sport id, such as basketball or hockey, or another spelling of a sport, such as ice_hockey or american-football. The valid ids are listed by GET /api/v1/sports. A league id, such as nba, ncaab, nfl, ncaaf, nhl, mlb, atp or ufc, belongs in league:

# Wrong: a league id in sport curl "https://api.sharpapi.io/api/v1/odds?sport=nba" -H "X-API-Key: YOUR_KEY" # Right: NBA games only curl "https://api.sharpapi.io/api/v1/odds?league=nba" -H "X-API-Key: YOUR_KEY" # Right: every basketball league curl "https://api.sharpapi.io/api/v1/odds?sport=basketball" -H "X-API-Key: YOUR_KEY"

A league id in sport is being phased out:

  • Until Tuesday, December 1, 2026, 15:00 UTC (10:00 AM ET), it still returns the rows of the whole sport, not just that league: sport=nba returns every basketball league, the same rows as sport=basketball. REST and SSE responses carry Deprecation: true and a Warning header that names the league filter to use and the date (a WebSocket connection gets no header):

    Deprecation: true Warning: 299 - "sport=nba is a league id, not a sport; use league=nba; from Tue, 01 Dec 2026 15:00:00 GMT a league id in sport= returns 400 invalid_filter"

    With two or more league ids the text reads sport=nba,nfl are league ids, not sports; use league=nba,nfl; .... A sport value that mixes a sport and a league id, such as sport=basketball,nfl, names only the league id.

  • From that date, a league id in sport returns 400 invalid_filter, the same error an unknown sport gets, with a did_you_mean suggestion naming league=<id>.

Move any league id from sport to league now. A request that already uses league for leagues and sport for sports is unaffected.

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&is_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"

Parameter names are always singular (sportsbook, not sportsbooks). Use commas to pass multiple values: sportsbook=draftkings,fanduel.

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 }
FieldExampleDescription
odds_american-110, +150Standard US format
odds_decimal1.909, 2.50Multiplier format
odds_probability0.5238Implied probability (0 to 1)

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.

CodeHTTP StatusDescription
missing_api_key401No API key supplied via X-API-Key, ?api_key=, or Authorization: Bearer
invalid_api_key401API key was supplied but is not recognized
expired_api_key401API key has expired — generate a new one in the dashboard
disabled_api_key401API key is disabled, usually because the subscription lapsed
unauthorized401Bearer-token auth failed on an internal endpoint (distinct from invalid_api_key)
invalid_token401Clerk session token failed verification (dashboard-only endpoints)
tier_restricted403Endpoint or feature is not available on your tier — response includes tier and required_tier, plus upgrade and upgrade_note when a self-serve plan or add-on unlocks it (Upgrade fields)
book_not_selected403A requested sportsbook is allowed by your tier but excluded by your dashboard book selection — response details lists requested / selected
not_found404Resource not found
method_not_allowed405HTTP method is not supported on this route
gone410Event has ended or expired — use /api/v1/events for current events
unknown_endpoint410Wrong API path — response includes correct_endpoint with the right route (e.g. /api/v1/arbitrage → /api/v1/opportunities/arbitrage)
validation_error400Request body or query parameters failed validation
invalid_filter400One or more filter values failed registry validation — response details.fields lists the rejected values, with did_you_mean suggestions
offset_too_large400offset exceeds the per-endpoint maximum (currently 500 on /odds and /odds/delta). Switch to cursor-based pagination or advance since
cursor_expired400The pagination cursor is no longer valid (live data shifted past it) — restart the scan without cursor
rate_limited429Per-minute request rate limit exceeded — response includes retry_after
concurrent_request_cap429Too many in-flight requests for your tier — reduce parallelism or upgrade
too_many_streams429Maximum concurrent SSE or WebSocket streams exceeded for this API key
backpressure—Emitted as an SSE event: error (not an HTTP status) when the client cannot keep up; server then closes the stream
upstream_error502Temporary issue reaching an upstream sportsbook or auth provider
service_unavailable503A required service (e.g. key management) is not configured or is offline
book_unavailable503A requested sportsbook is temporarily unavailable (no current snapshot in the store). When every requested book is paused, details.idle_reason is "paused" and there is no Retry-After; see Paused books
not_ready503A backing store the endpoint depends on (e.g. ClickHouse, closing-line capture) is not yet ready to serve the request. Retry with backoff
internal_error500Unexpected server error — retry with backoff and contact support with X-Request-Id if it persists

bad_request and invalid_request are deprecated — both were collapsed into validation_error. Clients that match on the old strings should add validation_error to their error map.

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.

CodeMeaning
invalid_messageFrame could not be parsed as JSON or did not match the expected shape
unknown_message_typetype field is not one of the documented values (auth, subscribe, filter, refresh_token, ping)
missing_tokenauth or refresh_token frame did not include a token field
missing_channelssubscribe frame did not include a non-empty channels array
not_authenticatedFrame requires an authenticated session (sent subscribe, filter, or refresh_token before auth)
already_authenticatedClient sent a second auth frame after the first one succeeded
Last updated on