{"openapi":"3.0.3","info":{"title":"Team Crests API","description":"A read-only REST API for football club crests, leagues, and countries. All badge URLs link directly to Wikimedia Commons CDN. No authentication required.","version":"1.0.0","contact":{"name":"Stadion","url":"https://stadion.io"}},"servers":[{"url":"https://ai-teamcrests-api.vercel.app","description":"Production"}],"tags":[{"name":"Clubs","description":"Football club crests and metadata"},{"name":"Leagues","description":"Competition and league data"},{"name":"Countries","description":"Country-level aggregations"}],"paths":{"/api/clubs":{"get":{"tags":["Clubs"],"summary":"List clubs","description":"List clubs with optional full-text search, filtering, and pagination.","operationId":"listClubs","parameters":[{"name":"q","in":"query","description":"Full-text search on club name and alternate names","schema":{"type":"string"}},{"name":"country","in":"query","description":"Filter by country name (e.g. `England`) or 3-letter ISO code (e.g. `GBR`)","schema":{"type":"string"}},{"name":"league","in":"query","description":"Filter by Wikidata league QID (e.g. `Q9448`) or league name","schema":{"type":"string"}},{"name":"hasSvg","in":"query","description":"Filter to only clubs with (`true`) or without (`false`) an SVG crest","schema":{"type":"boolean"}},{"name":"page","in":"query","description":"Page number, 1-indexed","schema":{"type":"integer","default":1,"minimum":1}},{"name":"perPage","in":"query","description":"Results per page (max 2000)","schema":{"type":"integer","default":48,"minimum":1,"maximum":2000}}],"responses":{"200":{"description":"Paginated list of clubs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Club"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"Q18656","name":"Arsenal F.C.","slug":"arsenal-fc","countryCode":"GBR","countryName":"England","leagueId":"Q9448","leagueName":"Premier League","badge":"https://upload.wikimedia.org/wikipedia/en/5/53/Arsenal_FC.svg","badgeSvg":"https://upload.wikimedia.org/wikipedia/en/5/53/Arsenal_FC.svg","alternateNames":["Arsenal"]}],"meta":{"total":860,"page":1,"perPage":48,"pages":18}}}}}}}},"/api/clubs/{id}":{"get":{"tags":["Clubs"],"summary":"Get club","description":"Fetch a single club by its Wikidata QID or slug.","operationId":"getClub","parameters":[{"name":"id","in":"path","required":true,"description":"Wikidata QID (e.g. `Q18656`) or slug (e.g. `arsenal-fc`)","schema":{"type":"string"}}],"responses":{"200":{"description":"Club object","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Club"}}}}}},"404":{"description":"Club not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leagues":{"get":{"tags":["Leagues"],"summary":"List leagues","description":"List all competitions. Optionally filter by country.","operationId":"listLeagues","parameters":[{"name":"country","in":"query","description":"Filter by country name or ISO code","schema":{"type":"string"}}],"responses":{"200":{"description":"List of leagues","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/League"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}}}}},"/api/leagues/{id}":{"get":{"tags":["Leagues"],"summary":"Get league with clubs","description":"Fetch a single league by Wikidata QID or slug, including all its clubs.","operationId":"getLeague","parameters":[{"name":"id","in":"path","required":true,"description":"Wikidata QID (e.g. `Q9448`) or slug (e.g. `premier-league`)","schema":{"type":"string"}}],"responses":{"200":{"description":"League with embedded clubs array","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/League"},{"type":"object","properties":{"clubCount":{"type":"integer"},"clubs":{"type":"array","items":{"$ref":"#/components/schemas/Club"}}}}]}}}}}},"404":{"description":"League not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/countries":{"get":{"tags":["Countries"],"summary":"List countries","description":"List all countries with club and league counts.","operationId":"listCountries","responses":{"200":{"description":"List of countries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}}}}}},"components":{"schemas":{"Club":{"type":"object","properties":{"id":{"type":"string","description":"Wikidata QID","example":"Q18656"},"name":{"type":"string","example":"Arsenal F.C."},"slug":{"type":"string","example":"arsenal-fc"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-3","example":"GBR"},"countryName":{"type":"string","example":"England"},"leagueId":{"type":"string","description":"Wikidata QID of the league","example":"Q9448"},"leagueName":{"type":"string","example":"Premier League"},"badge":{"type":"string","nullable":true,"description":"Wikimedia Commons PNG thumbnail URL","example":"https://upload.wikimedia.org/wikipedia/en/5/53/Arsenal_FC.svg"},"badgeSvg":{"type":"string","nullable":true,"description":"Wikimedia Commons SVG URL (when source is SVG)","example":"https://upload.wikimedia.org/wikipedia/en/5/53/Arsenal_FC.svg"},"alternateNames":{"type":"array","items":{"type":"string"},"example":["Arsenal"]}},"required":["id","name","slug","countryCode","countryName","leagueId","leagueName","alternateNames"]},"League":{"type":"object","properties":{"id":{"type":"string","description":"Wikidata QID","example":"Q9448"},"name":{"type":"string","example":"Premier League"},"slug":{"type":"string","example":"premier-league"},"countryCode":{"type":"string","example":"GBR"},"countryName":{"type":"string","example":"England"},"badge":{"type":"string","nullable":true,"description":"League logo URL from Wikimedia Commons"},"sport":{"type":"string","example":"Soccer"}},"required":["id","name","slug","countryCode","countryName","sport"]},"Country":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3","example":"GBR"},"name":{"type":"string","example":"England"},"slug":{"type":"string","example":"england"},"clubCount":{"type":"integer","example":94},"leagueCount":{"type":"integer","example":4}},"required":["code","name","slug","clubCount","leagueCount"]},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching records"},"page":{"type":"integer","description":"Current page (1-indexed)"},"perPage":{"type":"integer","description":"Results per page"},"pages":{"type":"integer","description":"Total number of pages"}},"required":["total","page","perPage","pages"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"x-stats":{"clubCount":860,"leagueCount":42,"countryCount":34,"svgCount":401,"seededAt":"2026-06-30T17:36:18.373Z"}}