{"openapi":"3.1.0","info":{"title":"FootballStack API","version":"1.0.0-beta","description":"A developer-first football data API built on OpenLigaDB current German data and OpenFootball archives. Coverage and licenses are explicit; lineups, player events and an uptime SLA are not included in this beta.","contact":{"name":"FootballStack"}},"servers":[{"url":"https://footballstack-api.netrebnic.chatgpt.site","description":"FootballStack open-data beta"}],"tags":[{"name":"System","description":"API availability and metadata"},{"name":"Competitions","description":"Coverage, source and license information"},{"name":"Matches","description":"Fixtures, results and derived match context"},{"name":"Search","description":"Human-friendly entity lookup"},{"name":"Founding Beta","description":"Founding-customer signup"}],"paths":{"/v1/health":{"get":{"operationId":"getHealth","tags":["System"],"summary":"Check API health","responses":{"200":{"description":"The API is operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/competitions":{"get":{"operationId":"listCompetitions","tags":["Competitions"],"summary":"List supported competitions","security":[{},{"bearerAuth":[]}],"responses":{"200":{"description":"Competition coverage, source and licenses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitionListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/matches":{"get":{"operationId":"listMatches","tags":["Matches"],"summary":"List fixtures and results","description":"The public preview returns at most five matches. A Founding Beta key unlocks the full result set.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"date","in":"query","description":"Kickoff date in YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"competition","in":"query","description":"Stable competition ID","schema":{"type":"string"}},{"name":"team","in":"query","description":"Stable team ID","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["scheduled","live","finished","postponed"]}},{"name":"season","in":"query","schema":{"type":"string","example":"2026/27"}},{"name":"round","in":"query","description":"Numeric matchday for providers that expose rounds","schema":{"type":"string","pattern":"^[0-9]{1,2}$","example":"34"}}],"responses":{"200":{"description":"Matching fixtures and results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"502":{"$ref":"#/components/responses/SourceUnavailable"}}}},"/v1/matches/{id}/context":{"get":{"operationId":"getMatchContext","tags":["Matches"],"summary":"Get derived match context","description":"Returns both teams' form, Elo-style rating, rest, table position, venue record, head-to-head and field freshness. The public preview ID is match_olg_83156; other IDs require a Founding Beta key.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Stable match ID","schema":{"type":"string","example":"match_olg_83156"}}],"responses":{"200":{"description":"Normalized match context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchContextResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FoundingKeyRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"502":{"$ref":"#/components/responses/SourceUnavailable"}}}},"/v1/search":{"get":{"operationId":"searchEntities","tags":["Search"],"summary":"Search teams and competitions","description":"The public preview returns at most five search results.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"example":"bayern"}],"responses":{"200":{"description":"Matching entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/founding-beta":{"post":{"operationId":"createFoundingBetaSignup","tags":["Founding Beta"],"summary":"Reserve a Founding Beta spot","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","useCase"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"email":{"type":"string","format":"email"},"projectUrl":{"type":["string","null"],"format":"uri"},"useCase":{"type":"string","minLength":15,"maxLength":1000}}}}}},"responses":{"201":{"description":"Spot reserved; checkout URL is returned when configured"},"400":{"$ref":"#/components/responses/BadRequest"},"503":{"description":"Signup persistence is temporarily unavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Founding Beta keys use the fs_live_ prefix and are stored only as SHA-256 hashes."}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"FoundingKeyRequired":{"description":"A Founding Beta key is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"QuotaExceeded":{"description":"The monthly request allowance is exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SourceUnavailable":{"description":"An upstream open-data source is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"Access":{"type":"object","required":["authenticated","plan"],"properties":{"authenticated":{"type":"boolean"},"plan":{"type":"string","example":"founding_beta"},"quota":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"period":{"type":"string","example":"2026-08"}}},"SourceAttribution":{"type":"object","required":["name","license","url","coverage"],"properties":{"name":{"type":"string","enum":["OpenLigaDB","OpenFootball"]},"license":{"type":"string","enum":["ODbL-1.0","CC0-1.0"]},"url":{"type":"string","format":"uri"},"coverage":{"type":"string"}}},"Meta":{"type":"object","required":["request_id","generated_at","environment"],"properties":{"request_id":{"type":"string","example":"req_19d5a7a8e7c4437d94"},"generated_at":{"type":"string","format":"date-time"},"environment":{"type":"string","enum":["beta"]},"count":{"type":"integer","minimum":0},"preview_limit":{"type":["integer","null"]},"access":{"$ref":"#/components/schemas/Access"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceAttribution"}}},"additionalProperties":true},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"}}}}},"Team":{"type":"object","required":["id","name","shortName","code","country","competitionId"],"properties":{"id":{"type":"string","example":"team_olg_40"},"name":{"type":"string","example":"FC Bayern München"},"shortName":{"type":"string","example":"Bayern"},"code":{"type":"string","example":"FCB"},"country":{"type":"string","example":"Germany"},"competitionId":{"type":"string","example":"comp_bundesliga_de"}}},"Match":{"type":"object","required":["id","competitionId","season","kickoffAt","status","round","venue","homeTeam","awayTeam","score","updatedAt"],"properties":{"id":{"type":"string","example":"match_olg_83156"},"competitionId":{"type":"string"},"season":{"type":"string"},"kickoffAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","live","finished","postponed"]},"round":{"type":"string"},"venue":{"type":["string","null"]},"homeTeam":{"$ref":"#/components/schemas/Team"},"awayTeam":{"$ref":"#/components/schemas/Team"},"score":{"type":"object","properties":{"home":{"type":["integer","null"]},"away":{"type":["integer","null"]}}},"updatedAt":{"type":"string","format":"date-time"}}},"Competition":{"type":"object","required":["id","name","country","code","currentSeason","availableSeasons","coverage","source"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"code":{"type":"string"},"currentSeason":{"type":"string"},"availableSeasons":{"type":"array","items":{"type":"string"}},"coverage":{"type":"object","additionalProperties":{"type":"boolean"}},"source":{"type":"object","required":["name","mode","license","url"],"properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["current","archive"]},"license":{"type":"string"},"url":{"type":"string","format":"uri"}}}}},"TeamContext":{"type":"object","properties":{"team":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"}}},"form":{"type":"string","example":"WWDWW"},"pointsLast5":{"type":"integer"},"goalsScoredLast5":{"type":"integer"},"goalsConcededLast5":{"type":"integer"},"goalsAverage":{"type":"number"},"elo":{"type":"integer"},"tablePosition":{"type":["integer","null"]},"restDays":{"type":["integer","null"]},"venueRecord":{"type":"object","properties":{"wins":{"type":"integer"},"draws":{"type":"integer"},"losses":{"type":"integer"}}}}},"HealthResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"provider":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"CompetitionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Competition"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"MatchListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"MatchContextResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"match":{"$ref":"#/components/schemas/Match"},"home":{"$ref":"#/components/schemas/TeamContext"},"away":{"$ref":"#/components/schemas/TeamContext"},"headToHead":{"type":"object","additionalProperties":{"type":"integer"}},"freshness":{"type":"object","additionalProperties":{"type":"string","format":"date-time"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"SearchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["team","competition"]},"id":{"type":"string"},"name":{"type":"string"},"subtitle":{"type":"string"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}