Skip to Content
API-ReferenzÜbersicht

API-Referenz Übersicht

Vollständige Referenz für die SharpAPI v1 REST API. Alle Endpoints geben JSON zurück und folgen einheitlichen Konventionen für Authentifizierung, Filterung, Paginierung und Fehlerbehandlung.

Basis-URLPermalink zu diesem Abschnitt

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

Verwenden Sie immer api.sharpapi.io als Basis-URL, nicht sharpapi.io.

OpenAPI-SpezifikationPermalink zu diesem Abschnitt

Die vollständige OpenAPI 3.1-Spezifikation steht zum Import in Tools wie Postman, Insomnia oder Code-Generatoren zur Verfügung:

Diese Spezifikation deckt alle Endpoints, Request-/Response-Schemas und Authentifizierungsanforderungen ab.

Request-FormatPermalink zu diesem Abschnitt

  • Alle Anfragen verwenden HTTPS
  • Authentifizierung über X-API-Key-Header, Authorization: Bearer-Header oder api_key-Query-Parameter
  • Request-Bodies (sofern zutreffend) verwenden JSON mit Content-Type: application/json
  • Alle Feldnamen sind in snake_case

Endpoint-ÜbersichtPermalink zu diesem Abschnitt

SharpAPI bietet 35 Routen über 7 Namespaces hinweg, zuzüglich Referenz- und Health-Endpoints.

OddsPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/oddsJaFree
GET/api/v1/odds/deltaJaFree
GET/api/v1/odds/bestJaFree
GET/api/v1/odds/comparisonJaFree
POST/api/v1/odds/batchJaFree

EventsPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/eventsJaFree
GET/api/v1/events/:eventIdJaFree
GET/api/v1/events/:eventId/oddsJaFree
GET/api/v1/events/:eventId/marketsJaFree

OpportunitiesPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/opportunities/evJaPro
GET/api/v1/opportunities/arbitrageJaHobby
GET/api/v1/opportunities/middlesJaPro

SplitsPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/splitsJaPro
GET/api/v1/splits/historyJaPro

StreamingPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/streamJaAdd-on

AccountPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/accountJaFree
GET/api/v1/account/usageJaFree
GET/api/v1/account/keysJaFree
POST/api/v1/account/keysJaFree
DELETE/api/v1/account/keys/:keyIdJaFree
POST/api/v1/account/keys/:keyId/rotateJaFree

Referenzdaten (öffentlich)Permalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/sportsNein-
GET/api/v1/leaguesNein-
GET/api/v1/sportsbooksNein-
GET/api/v1/marketsNein-
GET/api/v1/teamsNein-

EnterprisePermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/futuresJaEnterprise
GET/api/v1/futures/oddsJaEnterprise

HealthPermalink zu diesem Abschnitt

MethodePfadAuthMin. Tier
GET/api/v1/healthNein-

Response-FormatPermalink zu diesem Abschnitt

Zwei Formen auf oberster Ebene — beide stellen data an den Anfang und updated_at ans Ende, mit einem optionalen pagination-Block dazwischen. Es gibt kein success-Feld; der HTTP-Statuscode ist die Quelle der Wahrheit. Siehe Response Conventions für das vollständige Regelwerk.

Paginierte Listen-AntwortPermalink zu diesem Abschnitt

{ "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" }
FeldBeschreibung
dataArray von Ergebnissen
pagination.limitMaximale Anzahl von Elementen pro Seite (Standard: 50, Max: 200)
pagination.offsetAktueller Offset in den Ergebnissen
pagination.countAnzahl der in dieser Antwort zurückgegebenen Elemente
pagination.totalGesamtanzahl übereinstimmender Elemente über alle Seiten hinweg. Wird auf Endpoints weggelassen, die das nicht günstig berechnen können (z. B. /odds).
pagination.has_moreOb weitere Ergebnisse über diese Seite hinaus existieren
pagination.next_offsetOffset-Wert für die nächste Seite. Bevorzugen Sie next_cursor auf Live-Daten-Endpoints.
pagination.next_cursorOpaker Cursor für die nächste Seite. Übergeben als ?cursor= — stabil gegenüber Live-Datenänderungen. Empfohlen für mehrseitige Scans. Wird von den Cursor-fähigen Endpoints (/odds, /events, /teams) gesendet und fehlt auf der letzten Seite. /odds/delta nimmt keinen cursor an und sendet hier immer null — dort wird mit next_offset + since paginiert.
updated_atISO 8601-Zeitstempel der letzten Datenaktualisierung

Antwort für einzelne RessourcePermalink zu diesem Abschnitt

Wird für Einzelressourcen (/account, /events/:eventId) und nicht-paginierte Referenz-Endpoints verwendet. Kein pagination-Block.

{ "data": { "id": "evt_abc123", "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" }

Fehler-EnvelopePermalink zu diesem Abschnitt

Alle Fehler folgen einem einheitlichen 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" } }
FeldBeschreibung
error.codeMaschinenlesbarer Fehlercode
error.messageMenschenlesbare Beschreibung
error.docsLink zur relevanten Dokumentation (optional — enthalten bei Auth-, Tier-, Rate-Limit- und Streaming-Fehlern)
error.correct_endpointDer korrekte zu verwendende Endpoint (optional — enthalten bei unknown_endpoint-Fehlern, wenn die API den Pfad als bekannte falsche Route erkennt)
error.retry_afterSekunden bis ein Wiederholungsversuch erlaubt ist (optional — enthalten bei rate_limited-Fehlern)
error.addonDas Add-on, das die Anfrage freischaltet: game_state oder websocket (optional — enthalten, wenn eine Anfrage wegen eines fehlenden Add-ons abgelehnt wird)
error.upgradeLink zum Checkout oder zur Billing-Seite, die die Anfrage freischaltet (optional — siehe Upgrade-Felder)
error.upgrade_noteEinzeiliger Hinweis mit dem Plan oder Add-on, das die Anfrage freischaltet, und seinem Preis (optional — immer zusammen mit upgrade)

Upgrade-FelderPermalink zu diesem Abschnitt

Wenn eine 403 tier_restricted-Ablehnung durch einen Self-Service-Plan (Hobby, Pro oder Sharp) oder durch ein Add-on aufgehoben werden kann, enthält das error-Objekt zusätzlich upgrade (ein Link zum Checkout dieses Plans bzw. zum Add-on auf der Billing-Seite) und upgrade_note (ein einzeiliger Hinweis). An die message werden dann nach dem ursprünglichen Satz der Plan bzw. das Add-on, sein Preis und ein Link angehängt. Die 403-Beispiele auf den Seiten zu EV und Arbitrage zeigen den vollständigen Body.

  • code, tier, required_tier und docs sind unverändert, und kein Feld wurde entfernt. Die beiden neuen Felder kommen nur hinzu.
  • Eine Ablehnung, die nur Enterprise aufhebt, enthält keines der beiden Felder, und ihre message ist nur der ursprüngliche Satz.
  • Prüfen Sie error.code, nie den Text der message: Der angehängte Satz nennt einen Preis und einen Link, und beide können sich ändern. Lesen Sie den Link aus upgrade, statt ihn aus der message herauszuparsen.
  • Auch rate_limited-Fehler können upgrade und upgrade_note enthalten, wenn ein höherer Tier Ihr Limit anhebt.

Standard-Response-HeaderPermalink zu diesem Abschnitt

Jede API-Antwort enthält diese Header:

HeaderBeispielBeschreibung
X-RateLimit-Limit300Maximale Anfragen pro Minute für Ihr Tier
X-RateLimit-Remaining299Verbleibende Anfragen im aktuellen Zeitfenster
X-RateLimit-Reset1705804800Unix-Zeitstempel, wann das Rate Limit zurückgesetzt wird
X-Data-Delay0Datenverzögerung in Sekunden (60 für Free, 0 für kostenpflichtige Tiers)
X-Request-Idreq_a1b2c3d4Eindeutige Anfrage-ID für Debugging und Support

Geben Sie den X-Request-Id-Wert an, wenn Sie sich bezüglich einer bestimmten Anfrage an den Support wenden.

Tier-VergleichPermalink zu diesem Abschnitt

FunktionFreeHobbyProSharpEnterprise
Sportsbooks2 (DK, FD)51525 (von 43)Alle
Datenverzögerung60s0s0s0s0s
Anfragen/Min121203001.000Individuell
PinnacleNeinNeinNeinJaJa
EV / Arb / MiddlesNeinNeinJaJaJa
StreamingNeinAdd-onAdd-onAdd-onInklusive
Batch max. Events10105050100

Streaming erfordert das WebSocket-Add-on (99 USD/Monat für Hobby und Pro, 149 USD/Monat für Sharp). Enterprise enthält Streaming ohne Aufpreis.

FilterungPermalink zu diesem Abschnitt

Alle Listen-Endpoints unterstützen Filterung über Query-Parameter. Filter verwenden singuläre Parameternamen und akzeptieren kommagetrennte Werte für Mehrfachauswahl.

Filter-ParameterPermalink zu diesem Abschnitt

ParameterTypBeispielBeschreibung
sportsbookstringdraftkings,fanduelNach einem oder mehreren Sportsbooks filtern
sportstringbasketball,footballNach Sportart filtern. Nur Sport-IDs; eine Liga-ID wie nba gehört in league (siehe unten)
leaguestringnba,nflNach Liga filtern
marketstringmoneyline,spreadNach Markttyp filtern
event_idstringevt_abc123Nach Event-ID filtern
is_livebooleantrueNur laufende Live-Events
sortstring-odds_americanSortierfeld mit optionalem --Präfix für absteigend
fieldsstringid,sportsbook,odds_americanKommagetrennte Felder, die in die Antwort aufgenommen werden sollen
min_oddsnumber-110Minimaler American-Odds-Filter
max_oddsnumber200Maximaler American-Odds-Filter
group_bystringeventErgebnisse nach Feld gruppieren
limitnumber25Ergebnisse pro Seite (Standard: 50, Max: 200)
offsetnumber50Paginierungs-Offset. Kann bei Live-Endpoints zu doppelten Zeilen führen, wenn sich Daten zwischen Anfragen ändern.
cursorstring—Opaker Cursor aus next_cursor. Empfohlen für mehrseitige Scans über Live-Daten — beseitigt Offset-Drift.

Veraltete AliasePermalink zu diesem Abschnitt

Ältere Schreibweisen von zwei Filtern werden weiterhin akzeptiert: event für event_id und live für is_live. Sie liefern dieselben Zeilen, es geht also nichts kaputt — die Antwort enthält jedoch Deprecation: true und einen Warning-Header, und diese Namen können in einer künftigen Version entfallen. Verwenden Sie in neuem Code die kanonischen Namen aus der Tabelle oben. Ein Termin für die Abschaltung ist nicht festgelegt und wird nicht ohne Vorankündigung erfolgen.

Liga-IDs in sportPermalink zu diesem Abschnitt

sport nimmt eine Sport-ID wie basketball oder hockey oder eine andere Schreibweise einer Sportart wie ice_hockey oder american-football. Die gültigen IDs liefert GET /api/v1/sports. Eine Liga-ID wie nba, ncaab, nfl, ncaaf, nhl, mlb, atp oder ufc gehört in league:

# Falsch: eine Liga-ID in sport curl "https://api.sharpapi.io/api/v1/odds?sport=nba" -H "X-API-Key: YOUR_KEY" # Richtig: nur NBA-Spiele curl "https://api.sharpapi.io/api/v1/odds?league=nba" -H "X-API-Key: YOUR_KEY" # Richtig: alle Basketball-Ligen curl "https://api.sharpapi.io/api/v1/odds?sport=basketball" -H "X-API-Key: YOUR_KEY"

Eine Liga-ID in sport läuft aus:

  • Bis Dienstag, 1. Dezember 2026, 15:00 UTC (10:00 Uhr ET) liefert sie weiterhin die Zeilen der ganzen Sportart, nicht nur dieser Liga: sport=nba liefert alle Basketball-Ligen, dieselben Zeilen wie sport=basketball. REST- und SSE-Antworten enthalten Deprecation: true und einen Warning-Header, der den zu verwendenden league-Filter und das Datum nennt (eine WebSocket-Verbindung erhält keinen 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"

    Bei zwei oder mehr Liga-IDs lautet der Text sport=nba,nfl are league ids, not sports; use league=nba,nfl; .... Ein sport-Wert, der eine Sportart und eine Liga-ID mischt, etwa sport=basketball,nfl, nennt nur die Liga-ID.

  • Ab diesem Datum liefert eine Liga-ID in sport 400 invalid_filter, denselben Fehler wie eine unbekannte Sportart, mit einem did_you_mean-Vorschlag, der league=<id> nennt.

Verschieben Sie jede Liga-ID jetzt von sport nach league. Eine Anfrage, die bereits league für Ligen und sport für Sportarten verwendet, ist nicht betroffen.

BeispielePermalink zu diesem Abschnitt

# 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"

Parameternamen sind immer singulär (sportsbook, nicht sportsbooks). Verwenden Sie Kommas, um mehrere Werte zu übergeben: sportsbook=draftkings,fanduel.

Odds-FormatePermalink zu diesem Abschnitt

Alle Odds werden als flache Felder auf jedem Odds-Objekt zurückgegeben:

{ "odds_american": -110, "odds_decimal": 1.909, "odds_probability": 0.5238 }
FeldBeispielBeschreibung
odds_american-110, +150Standard-US-Format
odds_decimal1.909, 2.50Multiplikator-Format
odds_probability0.5238Implizierte Wahrscheinlichkeit (0 bis 1)

FehlercodesPermalink zu diesem Abschnitt

Die kanonische Liste der von der API ausgegebenen Fehlercodes. Der String in error.code ist der stabile Vertrag — prüfen Sie diesen anstelle des prosaischen message-Felds.

HTTP-FehlercodesPermalink zu diesem Abschnitt

In REST-Antworten ausgegeben.

CodeHTTP-StatusBeschreibung
missing_api_key401Kein API-Schlüssel über X-API-Key, ?api_key= oder Authorization: Bearer übermittelt
invalid_api_key401API-Schlüssel wurde übermittelt, aber nicht erkannt
expired_api_key401API-Schlüssel ist abgelaufen — generieren Sie einen neuen im Dashboard
disabled_api_key401API-Schlüssel ist deaktiviert, üblicherweise weil das Abonnement abgelaufen ist
unauthorized401Bearer-Token-Authentifizierung fehlgeschlagen bei einem internen Endpoint (unterscheidet sich von invalid_api_key)
invalid_token401Clerk-Session-Token-Verifizierung fehlgeschlagen (nur Dashboard-Endpoints)
tier_restricted403Endpoint oder Funktion ist in Ihrem Tier nicht verfügbar — Antwort enthält tier und required_tier, dazu upgrade und upgrade_note, wenn ein Self-Service-Plan oder ein Add-on sie freischaltet (Upgrade-Felder)
not_found404Ressource nicht gefunden
method_not_allowed405HTTP-Methode wird auf dieser Route nicht unterstützt
gone410Event ist beendet oder abgelaufen — verwenden Sie /api/v1/events für aktuelle Events
unknown_endpoint410Falscher API-Pfad — Antwort enthält correct_endpoint mit der richtigen Route (z. B. /api/v1/arbitrage → /api/v1/opportunities/arbitrage)
validation_error400Request-Body oder Query-Parameter haben die Validierung nicht bestanden
offset_too_large400offset überschreitet das pro-Endpoint-Maximum (derzeit 500 bei /odds und /odds/delta). Wechseln Sie zu cursor-basierter Paginierung oder erhöhen Sie since
rate_limited429Anfragen-pro-Minute-Rate-Limit überschritten — Antwort enthält retry_after
concurrent_request_cap429Zu viele laufende Anfragen für Ihr Tier — reduzieren Sie die Parallelität oder upgraden Sie
too_many_streams429Maximale Anzahl gleichzeitiger SSE- oder WebSocket-Streams für diesen API-Schlüssel überschritten
backpressure—Wird als SSE event: error ausgegeben (kein HTTP-Status), wenn der Client nicht mithalten kann; der Server schließt anschließend den Stream
upstream_error502Vorübergehendes Problem beim Erreichen eines Upstream-Sportsbooks oder Auth-Anbieters
service_unavailable503Ein erforderlicher Dienst (z. B. Schlüsselverwaltung) ist nicht konfiguriert oder offline
not_ready503Ein vom Endpoint abhängiger Backing Store (z. B. ClickHouse, Closing-Line-Capture) ist noch nicht bereit, die Anfrage zu bedienen. Mit Backoff erneut versuchen
internal_error500Unerwarteter Serverfehler — mit Backoff erneut versuchen und bei anhaltendem Problem den Support mit X-Request-Id kontaktieren

bad_request und invalid_request sind veraltet — beide wurden in validation_error zusammengeführt. Clients, die auf die alten Strings prüfen, sollten validation_error zu ihrer Fehlerzuordnung hinzufügen.

WebSocket-Frame-FehlercodesPermalink zu diesem Abschnitt

Werden ausschließlich innerhalb von {"type": "error", "code": "..."}-Frames auf einer offenen WebSocket-Verbindung ausgegeben. Sie beschreiben Client-Protokoll-Fehler und entsprechen keinem HTTP-Status.

CodeBedeutung
invalid_messageFrame konnte nicht als JSON geparst werden oder entsprach nicht der erwarteten Struktur
unknown_message_typetype-Feld ist keiner der dokumentierten Werte (auth, subscribe, filter, refresh_token, ping)
missing_tokenauth- oder refresh_token-Frame enthielt kein token-Feld
missing_channelssubscribe-Frame enthielt kein nicht-leeres channels-Array
not_authenticatedFrame erfordert eine authentifizierte Session (subscribe, filter oder refresh_token vor auth gesendet)
already_authenticatedClient hat einen zweiten auth-Frame nach erfolgreichem ersten gesendet
Last updated on