{"openapi":"3.1.0","info":{"title":"WinServe Tennis API","description":"Junior tennis player search, match prediction, and tournament-fit recommendation API","version":"0.2.1"},"paths":{"/service-meta":{"get":{"summary":"Service Meta","description":"JSON service catalog for automation (formerly returned by GET /).","operationId":"service_meta_service_meta_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ops/scraper-health":{"get":{"summary":"Ops Scraper Health","operationId":"ops_scraper_health_ops_scraper_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/future-tournaments":{"get":{"summary":"List Future Tournaments","operationId":"list_future_tournaments_future_tournaments_get","parameters":[{"name":"recommendable_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only rows with is_recommendable true","default":false,"title":"Recommendable Only"},"description":"Only rows with is_recommendable true"},{"name":"strict_recommendable_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only junior-targetable rows (is_recommendable and audience_type = junior)","default":false,"title":"Strict Recommendable Only"},"description":"Only junior-targetable rows (is_recommendable and audience_type = junior)"},{"name":"audience_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["junior","adult","mixed","school","team","unknown"],"type":"string"},{"type":"null"}],"description":"Exact match on audience_type (junior/adult/mixed/school/team/unknown)","title":"Audience Type"},"description":"Exact match on audience_type (junior/adult/mixed/school/team/unknown)"},{"name":"tournament_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Exact match on tournament_type","title":"Tournament Type"},"description":"Exact match on tournament_type"},{"name":"start_date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"normalized_start_date >= this date","title":"Start Date From"},"description":"normalized_start_date >= this date"},{"name":"start_date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"normalized_start_date <= this date","title":"Start Date To"},"description":"normalized_start_date <= this date"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"US state code","title":"State"},"description":"US state code"},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Substring match on level (ILIKE)","title":"Level"},"description":"Substring match on level (ILIKE)"},{"name":"surface","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Substring match on surface (ILIKE)","title":"Surface"},"description":"Substring match on surface (ILIKE)"},{"name":"source_system","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Exact source_system (e.g. usta_clubspark)","title":"Source System"},"description":"Exact source_system (e.g. usta_clubspark)"},{"name":"source_group","in":"query","required":false,"schema":{"anyOf":[{"enum":["usta","utr"],"type":"string"},{"type":"null"}],"description":"Broad filter: usta (source_system like usta%%), utr (like utr%%)","title":"Source Group"},"description":"Broad filter: usta (source_system like usta%%), utr (like utr%%)"},{"name":"us_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only events with US-like two-letter state codes","default":false,"title":"Us Only"},"description":"Only events with US-like two-letter state codes"},{"name":"division_contains","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Substring match on level or tournament name (gender/division hint)","title":"Division Contains"},"description":"Substring match on level or tournament name (gender/division hint)"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Search name or city (ILIKE)","title":"Q"},"description":"Search name or city (ILIKE)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":0,"default":0,"title":"Offset"}},{"name":"planning_tier","in":"query","required":false,"schema":{"anyOf":[{"enum":["planning_calendar","recommendable_now","waiting_for_field"],"type":"string"},{"type":"null"}],"description":"Filter by server-derived planning tier","title":"Planning Tier"},"description":"Filter by server-derived planning tier"},{"name":"confidence_status","in":"query","required":false,"schema":{"anyOf":[{"enum":["low","medium","high"],"type":"string"},{"type":"null"}],"description":"Filter by entry-mapping calendar confidence (not player-specific)","title":"Confidence Status"},"description":"Filter by entry-mapping calendar confidence (not player-specific)"},{"name":"has_entry_list","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"True: at least one entry row scraped","title":"Has Entry List"},"description":"True: at least one entry row scraped"},{"name":"include_high_school","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include High School tennis rows in the result set","default":false,"title":"Include High School"},"description":"When true, include High School tennis rows in the result set"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FutureTournamentRow"},"title":"Response List Future Tournaments Future Tournaments Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tournaments/upcoming":{"get":{"summary":"List Tournaments Upcoming","description":"Upcoming ``future_tournaments`` with planning tiers (60–180d calendar), not recommendable-only by default.","operationId":"list_tournaments_upcoming_tournaments_upcoming_get","parameters":[{"name":"player_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Optional: when state is omitted, default filters to this player's home state (US)","title":"Player Id"},"description":"Optional: when state is omitted, default filters to this player's home state (US)"},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"recommendable_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Recommendable Only"}},{"name":"strict_recommendable_only","in":"query","required":false,"schema":{"type":"boolean","description":"When true, only junior-targetable rows. Default false for full planning calendar.","default":false,"title":"Strict Recommendable Only"},"description":"When true, only junior-targetable rows. Default false for full planning calendar."},{"name":"audience_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["junior","adult","mixed","school","team","unknown"],"type":"string"},{"type":"null"}],"title":"Audience Type"}},{"name":"tournament_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Tournament Type"}},{"name":"start_date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date From"}},{"name":"start_date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date To"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"title":"State"}},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Level"}},{"name":"surface","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Surface"}},{"name":"source_system","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Source System"}},{"name":"source_group","in":"query","required":false,"schema":{"anyOf":[{"enum":["usta","utr"],"type":"string"},{"type":"null"}],"title":"Source Group"}},{"name":"us_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Us Only"}},{"name":"division_contains","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Division Contains"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":0,"default":0,"title":"Offset"}},{"name":"planning_tier","in":"query","required":false,"schema":{"anyOf":[{"enum":["planning_calendar","recommendable_now","waiting_for_field"],"type":"string"},{"type":"null"}],"title":"Planning Tier"}},{"name":"confidence_status","in":"query","required":false,"schema":{"anyOf":[{"enum":["low","medium","high"],"type":"string"},{"type":"null"}],"title":"Confidence Status"}},{"name":"has_entry_list","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Entry List"}},{"name":"include_high_school","in":"query","required":false,"schema":{"type":"boolean","description":"Show High School tennis in the planning calendar","default":false,"title":"Include High School"},"description":"Show High School tennis in the planning calendar"},{"name":"include_blocked_levels","in":"query","required":false,"schema":{"type":"boolean","description":"Debug/explicit opt-in: include player-stage blocked levels such as L6/L7 for advanced profiles.","default":false,"title":"Include Blocked Levels"},"description":"Debug/explicit opt-in: include player-stage blocked levels such as L6/L7 for advanced profiles."},{"name":"hide_past_days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":0,"description":"Hide tournaments whose end/start window ended more than this many days ago.","default":7,"title":"Hide Past Days"},"description":"Hide tournaments whose end/start window ended more than this many days ago."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FutureTournamentRow"},"title":"Response List Tournaments Upcoming Tournaments Upcoming Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tournaments/{tournament_id}":{"get":{"summary":"Get Future Tournament Row","operationId":"get_future_tournament_row_tournaments__tournament_id__get","parameters":[{"name":"tournament_id","in":"path","required":true,"schema":{"type":"integer","title":"Tournament Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FutureTournamentRow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/future-tournaments/{tournament_id}/entries":{"get":{"summary":"List Future Tournament Entries","operationId":"list_future_tournament_entries_future_tournaments__tournament_id__entries_get","parameters":[{"name":"tournament_id","in":"path","required":true,"schema":{"type":"integer","title":"Tournament Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"default":500,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FutureTournamentEntryRow"},"title":"Response List Future Tournament Entries Future Tournaments  Tournament Id  Entries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/search":{"get":{"summary":"Search Players","operationId":"search_players_players_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Player name search","title":"Q"},"description":"Player name search"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlayerSearchResult"},"title":"Response Search Players Players Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/by-name":{"get":{"summary":"Get Player By Name","operationId":"get_player_by_name_players_by_name_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":2,"title":"Name"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}":{"get":{"summary":"Get Player","operationId":"get_player_players__player_id__get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/recommendation-profile":{"get":{"summary":"Get Player Recommendation Profile Endpoint","operationId":"get_player_recommendation_profile_endpoint_players__player_id__recommendation_profile_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerRecommendationProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/profile":{"get":{"summary":"Get Player Profile","description":"Longitudinal performance snapshot: prefers latest `player_profile_snapshots` row, else live rollups.","operationId":"get_player_profile_players__player_id__profile_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/rating-history":{"get":{"summary":"Get Player Rating History","description":"Rating curve from `player_ratings`, with snapshot dates filling gaps when present.","operationId":"get_player_rating_history_players__player_id__rating_history_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"default":500,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerRatingHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/yearly-record":{"get":{"summary":"Get Player Yearly Record","description":"Wins and losses by calendar year from dated matches.","operationId":"get_player_yearly_record_players__player_id__yearly_record_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerYearlyRecordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/matches":{"get":{"summary":"List Player Matches","description":"Recent canonical matches for dashboard match history (no internal ids exposed in row payload).","operationId":"list_player_matches_players__player_id__matches_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":40,"title":"Limit"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date To"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlayerMatchHistoryRow"},"title":"Response List Player Matches Players  Player Id  Matches Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/tournament-recommendations":{"get":{"summary":"List Recommended Tournaments For Player","description":"Rank future tournaments for this player using the same entry-based scoring as\n``POST /recommend/tournament/{tournament_id}``. Tournaments without entries are included\nwith zero expected wins and low mapping confidence.","operationId":"list_recommended_tournaments_for_player_players__player_id__tournament_recommendations_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"start_date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"normalized_start_date >= this date","title":"Start Date From"},"description":"normalized_start_date >= this date"},{"name":"start_date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"normalized_start_date <= this date","title":"Start Date To"},"description":"normalized_start_date <= this date"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"US state code","title":"State"},"description":"US state code"},{"name":"us_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only events with US-like two-letter state codes","default":true,"title":"Us Only"},"description":"Only events with US-like two-letter state codes"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Max tournaments to return after ranking","default":50,"title":"Limit"},"description":"Max tournaments to return after ranking"},{"name":"strict_recommendable_only","in":"query","required":false,"schema":{"type":"boolean","description":"When true, only junior-targetable tournaments (is_recommendable and audience_type = junior)","default":true,"title":"Strict Recommendable Only"},"description":"When true, only junior-targetable tournaments (is_recommendable and audience_type = junior)"},{"name":"recommendation_mode","in":"query","required":false,"schema":{"enum":["junior","adult"],"type":"string","description":"junior: gender/age title filters + development-first ranking; adult: legacy ordering.","default":"junior","title":"Recommendation Mode"},"description":"junior: gender/age title filters + development-first ranking; adult: legacy ordering."},{"name":"include_preliminary","in":"query","required":false,"schema":{"type":"boolean","description":"When false, return a stronger subset only (higher confidence / more entries). When true, include low-confidence planning previews.","default":true,"title":"Include Preliminary"},"description":"When false, return a stronger subset only (higher confidence / more entries). When true, include low-confidence planning previews."},{"name":"include_high_school","in":"query","required":false,"schema":{"type":"boolean","description":"When true, allow High School tennis into recommendation candidates","default":false,"title":"Include High School"},"description":"When true, allow High School tennis into recommendation candidates"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecommendedTournamentSummary"},"title":"Response List Recommended Tournaments For Player Players  Player Id  Tournament Recommendations Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/recommended-tournaments":{"get":{"summary":"List Recommended Tournaments For Player","description":"Rank future tournaments for this player using the same entry-based scoring as\n``POST /recommend/tournament/{tournament_id}``. Tournaments without entries are included\nwith zero expected wins and low mapping confidence.","operationId":"list_recommended_tournaments_for_player_players__player_id__recommended_tournaments_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"start_date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"normalized_start_date >= this date","title":"Start Date From"},"description":"normalized_start_date >= this date"},{"name":"start_date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"normalized_start_date <= this date","title":"Start Date To"},"description":"normalized_start_date <= this date"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"US state code","title":"State"},"description":"US state code"},{"name":"us_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only events with US-like two-letter state codes","default":true,"title":"Us Only"},"description":"Only events with US-like two-letter state codes"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Max tournaments to return after ranking","default":50,"title":"Limit"},"description":"Max tournaments to return after ranking"},{"name":"strict_recommendable_only","in":"query","required":false,"schema":{"type":"boolean","description":"When true, only junior-targetable tournaments (is_recommendable and audience_type = junior)","default":true,"title":"Strict Recommendable Only"},"description":"When true, only junior-targetable tournaments (is_recommendable and audience_type = junior)"},{"name":"recommendation_mode","in":"query","required":false,"schema":{"enum":["junior","adult"],"type":"string","description":"junior: gender/age title filters + development-first ranking; adult: legacy ordering.","default":"junior","title":"Recommendation Mode"},"description":"junior: gender/age title filters + development-first ranking; adult: legacy ordering."},{"name":"include_preliminary","in":"query","required":false,"schema":{"type":"boolean","description":"When false, return a stronger subset only (higher confidence / more entries). When true, include low-confidence planning previews.","default":true,"title":"Include Preliminary"},"description":"When false, return a stronger subset only (higher confidence / more entries). When true, include low-confidence planning previews."},{"name":"include_high_school","in":"query","required":false,"schema":{"type":"boolean","description":"When true, allow High School tennis into recommendation candidates","default":false,"title":"Include High School"},"description":"When true, allow High School tennis into recommendation candidates"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecommendedTournamentSummary"},"title":"Response List Recommended Tournaments For Player Players  Player Id  Recommended Tournaments Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/tournaments/planning-calendar":{"get":{"summary":"Get Player Planning Calendar","description":"Player-aware 60–180 day planning view: buckets derived from ``future_tournaments`` + entry stats.\n\nUses the same title/level guardrails as recommendations when ``recommendation_mode=junior``.","operationId":"get_player_planning_calendar_players__player_id__tournaments_planning_calendar_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"days_ahead","in":"query","required":false,"schema":{"type":"integer","maximum":400,"minimum":30,"description":"Forward window from today for calendar rows","default":180,"title":"Days Ahead"},"description":"Forward window from today for calendar rows"},{"name":"us_only","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Us Only"}},{"name":"include_high_school","in":"query","required":false,"schema":{"type":"boolean","description":"Show High School tennis in explicit planning filters","default":false,"title":"Include High School"},"description":"Show High School tennis in explicit planning filters"},{"name":"recommendation_mode","in":"query","required":false,"schema":{"enum":["junior","adult"],"type":"string","description":"junior: title/eligibility filters; adult: no title filter on calendar buckets.","default":"junior","title":"Recommendation Mode"},"description":"junior: title/eligibility filters; adult: no title filter on calendar buckets."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningCalendarForPlayerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/predict/match":{"post":{"summary":"Predict Match","operationId":"predict_match_predict_match_post","parameters":[{"name":"recommendation_mode","in":"query","required":false,"schema":{"enum":["junior","adult"],"type":"string","description":"junior: confidence-shrunk probabilities; adult: raw Elo-style curve only.","default":"junior","title":"Recommendation Mode"},"description":"junior: confidence-shrunk probabilities; adult: raw Elo-style curve only."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictMatchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictMatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/predict/match-by-name":{"post":{"summary":"Predict Match By Name","operationId":"predict_match_by_name_predict_match_by_name_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictMatchByNameRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictMatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recommend/opponents/{player_id}":{"get":{"summary":"Recommend Opponents","operationId":"recommend_opponents_recommend_opponents__player_id__get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"min_probability","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"default":0.45,"title":"Min Probability"}},{"name":"max_probability","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"default":0.8,"title":"Max Probability"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecommendedOpponent"},"title":"Response Recommend Opponents Recommend Opponents  Player Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recommend/tournament-fit":{"post":{"summary":"Recommend Tournament Fit","operationId":"recommend_tournament_fit_recommend_tournament_fit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TournamentFitRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TournamentFitResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recommend/tournament/{tournament_id}":{"post":{"summary":"Recommend Tournament From Entries","description":"Recommend tournament fit using real registration rows linked to `players` and ratings.\n\nOpponents are distinct `player_id` values from `future_tournament_entries` with a current\nrating for `rating_type`. Unmapped registration rows affect coverage / confidence only.","operationId":"recommend_tournament_from_entries_recommend_tournament__tournament_id__post","parameters":[{"name":"tournament_id","in":"path","required":true,"schema":{"type":"integer","title":"Tournament Id"}},{"name":"recommendation_mode","in":"query","required":false,"schema":{"enum":["junior","adult"],"type":"string","description":"junior: eligibility filters + confidence-aware matchups; adult: legacy math only.","default":"junior","title":"Recommendation Mode"},"description":"junior: eligibility filters + confidence-aware matchups; adult: legacy math only."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TournamentRecommendRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealTournamentRecommendResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/players/{player_id}/tournaments/{tournament_id}/fit":{"get":{"summary":"Get Player Tournament Fit","description":"GET alias for tournament fit (dashboard-friendly; same payload as POST focal_player_id=player_id).","operationId":"get_player_tournament_fit_players__player_id__tournaments__tournament_id__fit_get","parameters":[{"name":"player_id","in":"path","required":true,"schema":{"type":"integer","title":"Player Id"}},{"name":"tournament_id","in":"path","required":true,"schema":{"type":"integer","title":"Tournament Id"}},{"name":"rating_type","in":"query","required":false,"schema":{"type":"string","default":"ELO_INTERNAL_V2","title":"Rating Type"}},{"name":"external_event_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"If set, only registration rows for this ClubSpark event id (UUID string).","title":"External Event Id"},"description":"If set, only registration rows for this ClubSpark event id (UUID string)."},{"name":"recommendation_mode","in":"query","required":false,"schema":{"enum":["junior","adult"],"type":"string","description":"Same semantics as POST /recommend/tournament/{tournament_id}.","default":"junior","title":"Recommendation Mode"},"description":"Same semantics as POST /recommend/tournament/{tournament_id}."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealTournamentRecommendResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"FutureTournamentEntryRow":{"properties":{"id":{"type":"integer","title":"Id"},"tournament_id":{"type":"integer","title":"Tournament Id"},"source_system":{"type":"string","title":"Source System"},"external_event_id":{"type":"string","title":"External Event Id","default":""},"external_player_id":{"type":"string","title":"External Player Id"},"player_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Player Id"},"player_name_raw":{"type":"string","title":"Player Name Raw"},"seed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seed"},"rating_snapshot":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating Snapshot"},"entry_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entry Status"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"}},"type":"object","required":["id","tournament_id","source_system","external_player_id","player_name_raw"],"title":"FutureTournamentEntryRow","description":"Registration line from `future_tournament_entries` (ClubSpark public GraphQL)."},"FutureTournamentRow":{"properties":{"id":{"type":"integer","title":"Id"},"source_system":{"type":"string","title":"Source System"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"source_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Display Name"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Level"},"surface":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Surface"},"tournament_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Type"},"audience_type":{"type":"string","enum":["junior","adult","mixed","school","team","unknown"],"title":"Audience Type","default":"unknown"},"visibility_category":{"type":"string","enum":["junior_default_visible","high_school","other"],"title":"Visibility Category","default":"other"},"is_recommendable":{"type":"boolean","title":"Is Recommendable","default":true},"is_junior":{"type":"boolean","title":"Is Junior","default":false},"normalized_start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Normalized Start Date"},"normalized_end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Normalized End Date"},"division_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Division Hint"},"registration_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Status"},"entries_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entries Status"},"last_entries_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Entries Sync At"},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen At"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"identification_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Identification Code"},"entry_count":{"type":"integer","title":"Entry Count","default":0},"mapped_entry_count":{"type":"integer","title":"Mapped Entry Count","default":0},"has_entry_list":{"type":"boolean","title":"Has Entry List","default":false},"planning_tier":{"type":"string","enum":["planning_calendar","recommendable_now","waiting_for_field"],"title":"Planning Tier","default":"planning_calendar"},"field_status":{"type":"string","enum":["no_field_yet","partial_field","full_field"],"title":"Field Status","default":"no_field_yet"},"confidence_status":{"type":"string","enum":["low","medium","high"],"title":"Confidence Status","default":"low"},"data_freshness_status":{"type":"string","enum":["fresh","aging","stale"],"title":"Data Freshness Status","default":"aging"},"entry_data_reason":{"type":"string","title":"Entry Data Reason","default":"waiting_for_entry_list"},"preview_recommendation_label":{"type":"string","title":"Preview Recommendation Label","default":"early_preview"},"entry_data_explanation":{"type":"string","title":"Entry Data Explanation","default":""},"recommendation_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recommendation Label"},"recommendation_basis":{"anyOf":[{"type":"string","enum":["stale","needs_refresh","calendar_only","stage_fit_only","entry_list_partial","field_backed","draw_backed","blocked_by_player_stage","insufficient_data","early_preview","waiting_for_entry_list","not_enough_data"]},{"type":"null"}],"title":"Recommendation Basis"},"eligible":{"type":"boolean","title":"Eligible","default":true},"data_confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Confidence"},"freshness_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freshness Status"},"entry_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entry Status"},"level_gate_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Level Gate Status"},"can_field_score":{"type":"boolean","title":"Can Field Score","default":false},"can_show_expected_wins":{"type":"boolean","title":"Can Show Expected Wins","default":false},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"suppressed_metrics":{"items":{"type":"string"},"type":"array","title":"Suppressed Metrics"},"tournament_purpose":{"anyOf":[{"type":"string","enum":["core_development","stretch_assessment","confidence_match_volume","backup","skip","calendar_watch","needs_refresh","not_enough_data"]},{"type":"null"}],"title":"Tournament Purpose"},"tournament_purpose_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Purpose Label"},"field_player_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Field Player Count"},"field_mapped_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Field Mapped Count"},"field_mapped_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Field Mapped Rate"},"player_field_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Player Field Percentile"},"player_field_position_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player Field Position Label"},"stronger_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stronger Players Count"},"similar_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Similar Players Count"},"weaker_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Weaker Players Count"},"field_strength_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Strength Label"},"field_fit_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Fit Label"},"field_fit_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Field Fit Score"},"field_fit_reasons":{"items":{"type":"string"},"type":"array","title":"Field Fit Reasons"}},"type":"object","required":["id","source_system"],"title":"FutureTournamentRow","description":"Row from `future_tournaments` (ClubSpark + optional TennisLink) with planning-calendar metadata."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PlanningCalendarForPlayerResponse":{"properties":{"recommended_now":{"$ref":"#/components/schemas/PlanningCalendarSection"},"worth_watching":{"$ref":"#/components/schemas/PlanningCalendarSection"},"waiting_for_field":{"$ref":"#/components/schemas/PlanningCalendarSection"}},"type":"object","required":["recommended_now","worth_watching","waiting_for_field"],"title":"PlanningCalendarForPlayerResponse"},"PlanningCalendarSection":{"properties":{"tournaments":{"items":{"$ref":"#/components/schemas/FutureTournamentRow"},"type":"array","title":"Tournaments"}},"type":"object","required":["tournaments"],"title":"PlanningCalendarSection","description":"Player-aware bucket of future tournaments for long-range planning."},"PlayerDetail":{"properties":{"id":{"type":"integer","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"state_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Code"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"rating_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating Type"},"rating_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Value"},"matches_used":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matches Used"},"wins_last_10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Wins Last 10"},"losses_last_10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Losses Last 10"},"total_wins":{"type":"integer","title":"Total Wins","default":0},"total_losses":{"type":"integer","title":"Total Losses","default":0}},"type":"object","required":["id","display_name"],"title":"PlayerDetail"},"PlayerMatchHistoryRow":{"properties":{"match_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Match Date"},"tournament_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Name"},"division":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Division"},"opponent_display_name":{"type":"string","title":"Opponent Display Name"},"won":{"type":"boolean","title":"Won"},"score_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Text"},"opponent_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Opponent Rating"}},"type":"object","required":["opponent_display_name","won"],"title":"PlayerMatchHistoryRow","description":"Recent canonical matches for dashboard match history (opponent identity only in UI)."},"PlayerPredictionView":{"properties":{"id":{"type":"integer","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"state_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Code"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"rating_type":{"type":"string","title":"Rating Type"},"rating_value":{"type":"number","title":"Rating Value"},"matches_used":{"type":"integer","title":"Matches Used"},"wins_last_10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Wins Last 10"},"losses_last_10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Losses Last 10"}},"type":"object","required":["id","display_name","rating_type","rating_value","matches_used"],"title":"PlayerPredictionView"},"PlayerProfileResponse":{"properties":{"player_id":{"type":"integer","title":"Player Id"},"display_name":{"type":"string","title":"Display Name"},"state_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Code"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"rating_type":{"type":"string","title":"Rating Type"},"rating_value":{"type":"number","title":"Rating Value"},"matches_used":{"type":"integer","title":"Matches Used"},"snapshot_date":{"type":"string","format":"date","title":"Snapshot Date"},"profile_source":{"type":"string","enum":["snapshot","live"],"title":"Profile Source","description":"snapshot: latest player_profile_snapshots row; live: computed today without snapshot."},"total_wins":{"type":"integer","title":"Total Wins"},"total_losses":{"type":"integer","title":"Total Losses"},"wins_last_30":{"type":"integer","title":"Wins Last 30"},"losses_last_30":{"type":"integer","title":"Losses Last 30"},"wins_last_90":{"type":"integer","title":"Wins Last 90"},"losses_last_90":{"type":"integer","title":"Losses Last 90"},"matches_last_30":{"type":"integer","title":"Matches Last 30"},"matches_last_90":{"type":"integer","title":"Matches Last 90"},"performance_trend":{"type":"string","enum":["hot","steady","cold","inactive"],"title":"Performance Trend"}},"type":"object","required":["player_id","display_name","rating_type","rating_value","matches_used","snapshot_date","profile_source","total_wins","total_losses","wins_last_30","losses_last_30","wins_last_90","losses_last_90","matches_last_30","matches_last_90","performance_trend"],"title":"PlayerProfileResponse","description":"Latest snapshot (or live rollups) plus a simple form trend label."},"PlayerRatingHistoryResponse":{"properties":{"player_id":{"type":"integer","title":"Player Id"},"rating_type":{"type":"string","title":"Rating Type"},"history":{"items":{"$ref":"#/components/schemas/RatingHistoryPoint"},"type":"array","title":"History"}},"type":"object","required":["player_id","rating_type","history"],"title":"PlayerRatingHistoryResponse"},"PlayerRecommendationProfileResponse":{"properties":{"player_id":{"type":"integer","title":"Player Id"},"competitive_stage":{"type":"string","title":"Competitive Stage"},"primary_levels":{"items":{"type":"string"},"type":"array","title":"Primary Levels"},"stretch_levels":{"items":{"type":"string"},"type":"array","title":"Stretch Levels"},"fallback_levels":{"items":{"type":"string"},"type":"array","title":"Fallback Levels"},"blocked_levels":{"items":{"type":"string"},"type":"array","title":"Blocked Levels"},"primary_goal":{"type":"string","title":"Primary Goal"},"recommendation_mode":{"type":"string","title":"Recommendation Mode"},"max_travel_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Travel Minutes"},"preferred_states":{"items":{"type":"string"},"type":"array","title":"Preferred States"},"profile_source":{"type":"string","enum":["db","config","rating_fallback"],"title":"Profile Source"},"is_active":{"type":"boolean","title":"Is Active","default":true}},"type":"object","required":["player_id","competitive_stage","primary_levels","stretch_levels","fallback_levels","blocked_levels","primary_goal","recommendation_mode","profile_source"],"title":"PlayerRecommendationProfileResponse"},"PlayerSearchResult":{"properties":{"id":{"type":"integer","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"state_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Code"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"rating_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating Type"},"rating_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Value"},"matches_used":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matches Used"},"wins_last_10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Wins Last 10"},"losses_last_10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Losses Last 10"}},"type":"object","required":["id","display_name"],"title":"PlayerSearchResult"},"PlayerYearlyRecordResponse":{"properties":{"player_id":{"type":"integer","title":"Player Id"},"years":{"items":{"$ref":"#/components/schemas/YearlyRecordRow"},"type":"array","title":"Years"}},"type":"object","required":["player_id","years"],"title":"PlayerYearlyRecordResponse"},"PredictMatchByNameRequest":{"properties":{"player_a_name":{"type":"string","title":"Player A Name"},"player_b_name":{"type":"string","title":"Player B Name"},"rating_type":{"type":"string","title":"Rating Type","default":"ELO_INTERNAL_V2"}},"type":"object","required":["player_a_name","player_b_name"],"title":"PredictMatchByNameRequest"},"PredictMatchRequest":{"properties":{"player_a_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Player A Id"},"player_b_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Player B Id"},"rating_type":{"type":"string","title":"Rating Type","default":"ELO_INTERNAL_V2"}},"type":"object","required":["player_a_id","player_b_id"],"title":"PredictMatchRequest"},"PredictMatchResponse":{"properties":{"rating_type":{"type":"string","title":"Rating Type"},"player_a":{"$ref":"#/components/schemas/PlayerPredictionView"},"player_b":{"$ref":"#/components/schemas/PlayerPredictionView"},"player_a_win_probability":{"type":"number","title":"Player A Win Probability"},"player_b_win_probability":{"type":"number","title":"Player B Win Probability"},"favored_player_id":{"type":"integer","title":"Favored Player Id"},"favored_player_name":{"type":"string","title":"Favored Player Name"},"rating_diff_a_minus_b":{"type":"number","title":"Rating Diff A Minus B"},"recommendation_mode":{"type":"string","enum":["junior","adult"],"title":"Recommendation Mode","default":"junior"},"player_a_win_probability_raw":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Player A Win Probability Raw"},"player_b_win_probability_raw":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Player B Win Probability Raw"},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score"},"confidence_band_low_a":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Band Low A"},"confidence_band_high_a":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Band High A"},"limited_data_flag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Limited Data Flag"},"volatility_flag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Volatility Flag"},"prediction_explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prediction Explanation"}},"type":"object","required":["rating_type","player_a","player_b","player_a_win_probability","player_b_win_probability","favored_player_id","favored_player_name","rating_diff_a_minus_b"],"title":"PredictMatchResponse"},"RatingHistoryPoint":{"properties":{"as_of_date":{"type":"string","format":"date","title":"As Of Date"},"rating_value":{"type":"number","title":"Rating Value"},"matches_used":{"type":"integer","title":"Matches Used"}},"type":"object","required":["as_of_date","rating_value","matches_used"],"title":"RatingHistoryPoint"},"RealTournamentRecommendResponse":{"properties":{"tournament_id":{"type":"integer","title":"Tournament Id"},"tournament_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Name"},"rating_type":{"type":"string","title":"Rating Type"},"focal_player":{"$ref":"#/components/schemas/PlayerPredictionView"},"total_entries":{"type":"integer","title":"Total Entries"},"mapped_entries":{"type":"integer","title":"Mapped Entries"},"mapping_coverage_pct":{"type":"number","title":"Mapping Coverage Pct"},"confidence_level":{"type":"string","enum":["high","medium","low"],"title":"Confidence Level"},"field_size":{"type":"integer","title":"Field Size"},"average_field_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Field Rating"},"stronger_players":{"type":"integer","title":"Stronger Players"},"equal_band_players":{"type":"integer","title":"Equal Band Players"},"weaker_players":{"type":"integer","title":"Weaker Players"},"average_win_probability_vs_field":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Win Probability Vs Field"},"median_win_probability_vs_field":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Win Probability Vs Field"},"estimated_expected_wins":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Estimated Expected Wins"},"recommendation_label":{"type":"string","title":"Recommendation Label"},"recommendation_reason":{"type":"string","title":"Recommendation Reason"},"entries_status":{"type":"string","title":"Entries Status","default":"never_synced"},"last_entries_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Entries Sync At"},"entries_explanation":{"type":"string","title":"Entries Explanation","default":""},"best_matchups":{"items":{"$ref":"#/components/schemas/TournamentMatchupView"},"type":"array","title":"Best Matchups"},"toughest_matchups":{"items":{"$ref":"#/components/schemas/TournamentMatchupView"},"type":"array","title":"Toughest Matchups"},"recommendation_mode":{"type":"string","enum":["junior","adult"],"title":"Recommendation Mode","default":"junior"},"junior_recommendation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Junior Recommendation Score"},"development_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Development Classification"},"workload_flag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workload Flag"},"explanation_bullets":{"items":{"type":"string"},"type":"array","title":"Explanation Bullets"},"projected_competitiveness_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Projected Competitiveness Band"},"parent_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Note"},"readiness_state":{"type":"string","enum":["ready","preliminary","waiting_entries","low_confidence","not_enough_data"],"title":"Readiness State","default":"not_enough_data"},"signup_display_label":{"type":"string","title":"Signup Display Label","default":"Not enough data"},"recommendation_score_0_100":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Recommendation Score 0 100"},"likely_round_reached":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Likely Round Reached"},"round_reach_probabilities":{"items":{"$ref":"#/components/schemas/RoundReachPoint"},"type":"array","title":"Round Reach Probabilities"},"field_backed":{"type":"boolean","title":"Field Backed","default":false},"recommendation_basis":{"type":"string","enum":["stale","needs_refresh","calendar_only","stage_fit_only","entry_list_partial","field_backed","draw_backed","blocked_by_player_stage","insufficient_data","early_preview","waiting_for_entry_list","not_enough_data"],"title":"Recommendation Basis","default":"not_enough_data"},"eligible":{"type":"boolean","title":"Eligible","default":true},"data_confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Confidence"},"freshness_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freshness Status"},"entry_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entry Status"},"level_gate_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Level Gate Status"},"can_field_score":{"type":"boolean","title":"Can Field Score","default":false},"can_show_expected_wins":{"type":"boolean","title":"Can Show Expected Wins","default":false},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"suppressed_metrics":{"items":{"type":"string"},"type":"array","title":"Suppressed Metrics"},"tournament_purpose":{"anyOf":[{"type":"string","enum":["core_development","stretch_assessment","confidence_match_volume","backup","skip","calendar_watch","needs_refresh","not_enough_data"]},{"type":"null"}],"title":"Tournament Purpose"},"tournament_purpose_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Purpose Label"},"field_player_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Field Player Count"},"field_mapped_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Field Mapped Count"},"field_mapped_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Field Mapped Rate"},"player_field_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Player Field Percentile"},"player_field_position_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player Field Position Label"},"stronger_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stronger Players Count"},"similar_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Similar Players Count"},"weaker_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Weaker Players Count"},"field_strength_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Strength Label"},"field_fit_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Fit Label"},"field_fit_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Field Fit Score"},"field_fit_reasons":{"items":{"type":"string"},"type":"array","title":"Field Fit Reasons"}},"type":"object","required":["tournament_id","rating_type","focal_player","total_entries","mapped_entries","mapping_coverage_pct","confidence_level","field_size","stronger_players","equal_band_players","weaker_players","recommendation_label","recommendation_reason","best_matchups","toughest_matchups"],"title":"RealTournamentRecommendResponse","description":"Tournament fit from `future_tournament_entries` + `player_rating_current`."},"RecommendedOpponent":{"properties":{"opponent_id":{"type":"integer","title":"Opponent Id"},"opponent_name":{"type":"string","title":"Opponent Name"},"opponent_state_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opponent State Code"},"opponent_country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opponent Country Code"},"opponent_rating":{"type":"number","title":"Opponent Rating"},"rating_diff_player_minus_opponent":{"type":"number","title":"Rating Diff Player Minus Opponent"},"focal_win_probability":{"type":"number","title":"Focal Win Probability"},"category":{"type":"string","enum":["good_target","coin_flip","avoid"],"title":"Category"}},"type":"object","required":["opponent_id","opponent_name","opponent_rating","rating_diff_player_minus_opponent","focal_win_probability","category"],"title":"RecommendedOpponent"},"RecommendedTournamentSummary":{"properties":{"tournament_id":{"type":"integer","title":"Tournament Id"},"tournament_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Name"},"normalized_start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Normalized Start Date"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"tournament_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Type"},"audience_type":{"type":"string","enum":["junior","adult","mixed","school","team","unknown"],"title":"Audience Type","default":"unknown"},"visibility_category":{"type":"string","enum":["junior_default_visible","high_school","other"],"title":"Visibility Category","default":"other"},"total_entries":{"type":"integer","title":"Total Entries"},"mapped_entries":{"type":"integer","title":"Mapped Entries"},"mapping_coverage_pct":{"type":"number","title":"Mapping Coverage Pct"},"confidence_level":{"type":"string","enum":["high","medium","low"],"title":"Confidence Level"},"recommendation_label":{"type":"string","title":"Recommendation Label"},"recommendation_reason":{"type":"string","title":"Recommendation Reason"},"estimated_expected_wins":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Estimated Expected Wins"},"average_field_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Field Rating"},"entries_status":{"type":"string","title":"Entries Status","default":"never_synced"},"last_entries_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Entries Sync At"},"entries_explanation":{"type":"string","title":"Entries Explanation","default":""},"recommendation_mode":{"type":"string","enum":["junior","adult"],"title":"Recommendation Mode","default":"junior"},"junior_recommendation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Junior Recommendation Score"},"development_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Development Classification"},"workload_flag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workload Flag"},"explanation_bullets":{"items":{"type":"string"},"type":"array","title":"Explanation Bullets"},"projected_competitiveness_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Projected Competitiveness Band"},"parent_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Note"},"readiness_state":{"type":"string","enum":["ready","preliminary","waiting_entries","low_confidence","not_enough_data"],"title":"Readiness State","default":"not_enough_data"},"signup_display_label":{"type":"string","title":"Signup Display Label","default":"Not enough data"},"recommendation_score_0_100":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Recommendation Score 0 100"},"likely_round_reached":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Likely Round Reached"},"round_reach_probabilities":{"items":{"$ref":"#/components/schemas/RoundReachPoint"},"type":"array","title":"Round Reach Probabilities"},"field_backed":{"type":"boolean","title":"Field Backed","default":false},"recommendation_basis":{"type":"string","enum":["stale","needs_refresh","calendar_only","stage_fit_only","entry_list_partial","field_backed","draw_backed","blocked_by_player_stage","insufficient_data","early_preview","waiting_for_entry_list","not_enough_data"],"title":"Recommendation Basis","default":"not_enough_data"},"calendar_planning_tier":{"anyOf":[{"type":"string","enum":["planning_calendar","recommendable_now","waiting_for_field"]},{"type":"null"}],"title":"Calendar Planning Tier"},"calendar_field_status":{"anyOf":[{"type":"string","enum":["no_field_yet","partial_field","full_field"]},{"type":"null"}],"title":"Calendar Field Status"},"calendar_confidence_status":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Calendar Confidence Status"},"preview_recommendation_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Recommendation Label"},"eligible":{"type":"boolean","title":"Eligible","default":true},"data_confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Confidence"},"freshness_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freshness Status"},"entry_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entry Status"},"level_gate_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Level Gate Status"},"can_field_score":{"type":"boolean","title":"Can Field Score","default":false},"can_show_expected_wins":{"type":"boolean","title":"Can Show Expected Wins","default":false},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"suppressed_metrics":{"items":{"type":"string"},"type":"array","title":"Suppressed Metrics"},"tournament_purpose":{"anyOf":[{"type":"string","enum":["core_development","stretch_assessment","confidence_match_volume","backup","skip","calendar_watch","needs_refresh","not_enough_data"]},{"type":"null"}],"title":"Tournament Purpose"},"tournament_purpose_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Purpose Label"},"field_player_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Field Player Count"},"field_mapped_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Field Mapped Count"},"field_mapped_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Field Mapped Rate"},"player_field_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Player Field Percentile"},"player_field_position_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player Field Position Label"},"stronger_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stronger Players Count"},"similar_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Similar Players Count"},"weaker_players_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Weaker Players Count"},"field_strength_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Strength Label"},"field_fit_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Fit Label"},"field_fit_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Field Fit Score"},"field_fit_reasons":{"items":{"type":"string"},"type":"array","title":"Field Fit Reasons"}},"type":"object","required":["tournament_id","total_entries","mapped_entries","mapping_coverage_pct","confidence_level","recommendation_label","recommendation_reason"],"title":"RecommendedTournamentSummary","description":"Ranked future tournament for a player using registration-derived field strength."},"RoundReachPoint":{"properties":{"stage":{"type":"string","title":"Stage"},"probability":{"type":"number","title":"Probability"}},"type":"object","required":["stage","probability"],"title":"RoundReachPoint"},"TournamentFitRequest":{"properties":{"focal_player_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Focal Player Id"},"candidate_player_ids":{"items":{"type":"integer"},"type":"array","minItems":1,"title":"Candidate Player Ids"},"rating_type":{"type":"string","title":"Rating Type","default":"ELO_INTERNAL_V2"},"tournament_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Name"}},"type":"object","required":["focal_player_id","candidate_player_ids"],"title":"TournamentFitRequest"},"TournamentFitResponse":{"properties":{"tournament_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tournament Name"},"rating_type":{"type":"string","title":"Rating Type"},"focal_player":{"$ref":"#/components/schemas/PlayerPredictionView"},"field_size":{"type":"integer","title":"Field Size"},"average_field_rating":{"type":"number","title":"Average Field Rating"},"stronger_players":{"type":"integer","title":"Stronger Players"},"equal_band_players":{"type":"integer","title":"Equal Band Players"},"weaker_players":{"type":"integer","title":"Weaker Players"},"average_win_probability_vs_field":{"type":"number","title":"Average Win Probability Vs Field"},"median_win_probability_vs_field":{"type":"number","title":"Median Win Probability Vs Field"},"estimated_expected_wins":{"type":"number","title":"Estimated Expected Wins"},"recommendation_label":{"type":"string","enum":["strong_fit","good_fit","neutral_fit","tough_fit","very_tough_fit"],"title":"Recommendation Label"},"recommendation_reason":{"type":"string","title":"Recommendation Reason"},"best_matchups":{"items":{"$ref":"#/components/schemas/TournamentMatchupView"},"type":"array","title":"Best Matchups"},"toughest_matchups":{"items":{"$ref":"#/components/schemas/TournamentMatchupView"},"type":"array","title":"Toughest Matchups"}},"type":"object","required":["rating_type","focal_player","field_size","average_field_rating","stronger_players","equal_band_players","weaker_players","average_win_probability_vs_field","median_win_probability_vs_field","estimated_expected_wins","recommendation_label","recommendation_reason","best_matchups","toughest_matchups"],"title":"TournamentFitResponse"},"TournamentMatchupView":{"properties":{"opponent_id":{"type":"integer","title":"Opponent Id"},"opponent_name":{"type":"string","title":"Opponent Name"},"opponent_rating":{"type":"number","title":"Opponent Rating"},"focal_win_probability":{"type":"number","title":"Focal Win Probability"},"difficulty_bucket":{"type":"string","enum":["favorable","competitive","dangerous"],"title":"Difficulty Bucket"},"p_raw":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P Raw"},"p_final":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P Final"},"confidence_band_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Band Low"},"confidence_band_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Band High"},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score"},"volatility_flag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Volatility Flag"},"limited_data_flag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Limited Data Flag"},"matchup_explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matchup Explanation"}},"type":"object","required":["opponent_id","opponent_name","opponent_rating","focal_win_probability","difficulty_bucket"],"title":"TournamentMatchupView"},"TournamentRecommendRequest":{"properties":{"focal_player_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Focal Player Id"},"rating_type":{"type":"string","title":"Rating Type","default":"ELO_INTERNAL_V2"},"external_event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Event Id","description":"If set, only registration rows for this ClubSpark event id (UUID string)."}},"type":"object","required":["focal_player_id"],"title":"TournamentRecommendRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"YearlyRecordRow":{"properties":{"year":{"type":"integer","title":"Year"},"wins":{"type":"integer","title":"Wins"},"losses":{"type":"integer","title":"Losses"},"matches":{"type":"integer","title":"Matches"}},"type":"object","required":["year","wins","losses","matches"],"title":"YearlyRecordRow"}}}}