{"openapi":"3.1.0","info":{"title":"TourneyRadar API","version":"1.0.0","description":"A free, keyless REST API for over-the-board chess tournament data.","license":{"name":"Apache-2.0","url":"https://github.com/AnayDhawan/tourneyradar-api/blob/main/LICENSE"}},"servers":[{"url":"https://tourneyradar-api.vercel.app","description":"Production"}],"components":{"schemas":{"Tournament":{"type":"object","properties":{"id":{"type":"string","example":"cr_1371843"},"name":{"type":"string","example":"Chennai Open 2026"},"location":{"type":"string","example":"Chennai, India"},"city":{"type":"string","example":"Chennai"},"state":{"type":"string","example":"Tamil Nadu"},"country":{"type":"string","example":"India"},"country_code":{"type":"string","example":"IN"},"lat":{"type":["number","null"],"example":13.0827},"lng":{"type":["number","null"],"example":80.2707},"category":{"type":"string","enum":["Classical","Rapid","Blitz"],"example":"Classical"},"date":{"type":"string","example":"2026-06-01"},"end_date":{"type":"string","example":"2026-06-07"},"fide_rated":{"type":"boolean","example":true},"time_control":{"type":"string","example":"90+30"},"rounds":{"type":"number","example":9},"organizer_name":{"type":"string","example":"Chennai Chess Association"},"registration_link":{"type":["string","null"]},"source_url":{"type":"string","example":"https://chess-results.com/tnr1371843.aspx"},"status":{"type":"string","example":"published"}},"required":["id","name","category","date","fide_rated","status"]},"PageMeta":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":50},"total":{"type":"number","example":248},"hasMore":{"type":"boolean","example":true}},"required":["page","limit","total","hasMore"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Tournament not found"},"status":{"type":"number","example":404}},"required":["error","status"]},"Country":{"type":"object","properties":{"country_code":{"type":"string","example":"IN"},"country":{"type":["string","null"],"example":"India"}},"required":["country_code","country"]},"Stats":{"type":"object","properties":{"total":{"type":"number","example":1842,"description":"Total published tournaments"},"upcoming":{"type":"number","example":612,"description":"Published tournaments with a date today or later"},"countries":{"type":"number","example":94,"description":"Distinct countries with a published tournament"},"byCategory":{"type":"object","properties":{"Classical":{"type":"number","example":1120},"Rapid":{"type":"number","example":480},"Blitz":{"type":"number","example":242}},"required":["Classical","Rapid","Blitz"],"description":"Published tournament count per category"},"lastScrapedAt":{"type":["string","null"],"example":"2026-08-24T03:12:00Z","description":"Timestamp of the most recent scrape run, or null if none recorded"}},"required":["total","upcoming","countries","byCategory","lastScrapedAt"]}},"parameters":{}},"paths":{"/v1/tournaments":{"get":{"tags":["Tournaments"],"operationId":"listTournaments","summary":"List tournaments","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"IN","description":"2-letter ISO country code"},"required":false,"description":"2-letter ISO country code","name":"country","in":"query"},{"schema":{"type":"string","enum":["Classical","Rapid","Blitz"],"example":"Classical"},"required":false,"name":"category","in":"query"},{"schema":{"type":["boolean","null"],"example":true},"required":false,"name":"upcoming","in":"query"},{"schema":{"type":["boolean","null"],"example":true},"required":false,"name":"fide_rated","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"},"required":false,"name":"date_from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-31"},"required":false,"name":"date_to","in":"query"},{"schema":{"type":"string","minLength":1,"example":"Chess Association"},"required":false,"name":"organizer","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"example":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"A page of published tournaments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tournament"}},"meta":{"$ref":"#/components/schemas/PageMeta"}},"required":["data","meta"]}}}},"304":{"description":"Not modified, matches the If-None-Match ETag"},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tournaments/{id}":{"get":{"tags":["Tournaments"],"operationId":"getTournament","summary":"Get a single tournament by id","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","example":"cr_1371843"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The tournament","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tournament"}},"required":["data"]}}}},"304":{"description":"Not modified, matches the If-None-Match ETag"},"400":{"description":"Invalid id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tournament not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/countries":{"get":{"tags":["Countries"],"operationId":"listCountries","summary":"List countries that have tournament data","responses":{"200":{"description":"Every distinct country with a published tournament","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}},"required":["data"]}}}},"304":{"description":"Not modified, matches the If-None-Match ETag"},"500":{"description":"Query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"get":{"tags":["Search"],"operationId":"searchTournaments","summary":"Full-text search across tournament name, organizer, and location","parameters":[{"schema":{"type":"string","minLength":1,"example":"open"},"required":true,"name":"q","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"example":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"Matching tournaments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tournament"}},"meta":{"$ref":"#/components/schemas/PageMeta"}},"required":["data","meta"]}}}},"304":{"description":"Not modified, matches the If-None-Match ETag"},"400":{"description":"Missing or invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"tags":["Stats"],"operationId":"getStats","summary":"Aggregate figures across all published tournaments","responses":{"200":{"description":"Tournament totals, coverage, and the last scrape time","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Stats"}},"required":["data"]}}}},"304":{"description":"Not modified, matches the If-None-Match ETag"},"500":{"description":"Query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}