{"openapi":"3.1.0","info":{"title":"Nikke Tierlist & Recommendation API","version":"1.0.0","description":"API for Nikke unit tierlist, analytics, and AI-powered recommendations"},"components":{"schemas":{},"parameters":{}},"paths":{"/nikkes":{"get":{"tags":["Nikkes"],"summary":"List all nikkes with optional filters","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by name (case-insensitive)"},{"name":"tier","in":"query","schema":{"type":"string"},"description":"Filter by tier (T0-T5)"},{"name":"element","in":"query","schema":{"type":"string"},"description":"Filter by element"},{"name":"weapon","in":"query","schema":{"type":"string"},"description":"Filter by weapon type"},{"name":"role","in":"query","schema":{"type":"string"},"description":"Filter by role"},{"name":"manufacturer","in":"query","schema":{"type":"string"},"description":"Filter by manufacturer (Tetra, Elysion, Missilis, Pilgrim, Abnormal)"},{"name":"burst_level","in":"query","schema":{"type":"integer","minimum":0,"maximum":3},"description":"Filter by burst level (0-3)"},{"name":"include_sr","in":"query","schema":{"type":"boolean","default":false},"description":"If true, include SR-rarity units (default false: SR units are excluded)"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number (default 1)"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"minimum":1,"maximum":500},"description":"Items per page (default 25, max 500)"}],"operationId":"get_NikkeList","responses":{"200":{"description":"List of Nikke units with pagination metadata","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"tier":{"type":"string"},"general_tier":{"type":["string","null"]},"raid_tier":{"type":["string","null"]},"element":{"type":"string"},"weapon":{"type":"string"},"role":{"type":"string"},"rarity":{"type":"string","enum":["SSR","SR"]},"manufacturer":{"type":"string"},"burst_type":{"type":["string","null"]},"investment_priority":{"type":["string","null"]},"skill1_target":{"type":["number","null"]},"skill2_target":{"type":["number","null"]},"burst_target":{"type":["number","null"]},"skill1_name":{"type":["string","null"]},"skill2_name":{"type":["string","null"]},"burst_name":{"type":["string","null"]},"special_requirements":{"type":["string","null"]},"special_notes":{"type":["string","null"]},"normalized_notes":{"type":["string","null"]}},"required":["name","tier","element","weapon","role"]}},"count":{"type":"number"},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"}},"required":["success","data","count","total","page","limit"]}}}}}}},"/nikkes/top-teams":{"get":{"tags":["Nikkes"],"summary":"Get top 3 meta teams per boss element","description":"Returns the top 3 most-used team compositions for each boss weakness element. Data is sourced from union raid analysis and is not the full recommendations engine.","parameters":[{"name":"element","in":"query","required":false,"schema":{"type":"string","enum":["fire","water","wind","electric","iron"],"description":"Optional: filter to specific element. Returns all elements if not specified."}}],"operationId":"get_TopTeamsEndpoint","responses":{"200":{"description":"Top 3 teams per element retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"number"},"team":{"type":"string","description":"Pipe-separated unit names"},"units":{"type":"array","items":{"type":"string"}},"usage":{"type":"number"},"avg_damage":{"type":"number"}}}}}}}}}},"400":{"description":"Invalid element parameter"}}}},"/nikkes/recommendations/weaknesses":{"get":{"tags":["Recommendations"],"summary":"List available boss weaknesses","description":"Returns available boss weakness elements with cluster counts, team totals, and usage statistics from competitive union raid data.","operationId":"get_RecommendationWeaknesses","responses":{"200":{"description":"Weakness list with summary stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"weaknesses":{"type":"array","items":{"type":"object","properties":{"element":{"type":"string"},"total_teams":{"type":"number"},"total_usage":{"type":"number"},"cluster_count":{"type":"number"}},"required":["element","total_teams","total_usage","cluster_count"]}},"metadata":{"type":"object","properties":{"version":{"type":"string"},"min_usage_threshold":{"type":"number"},"generated_at":{"type":"string"}},"required":["version","min_usage_threshold"]}},"required":["success","weaknesses","metadata"]}}}}}}},"/nikkes/recommendations/by-weakness":{"get":{"tags":["Recommendations"],"summary":"Get teams by boss weakness","description":"Returns all team compositions for a specific boss weakness element, ordered by usage count. Includes damage stats, meta flags, and cluster grouping.","parameters":[{"name":"weakness","in":"query","required":true,"schema":{"type":"string","enum":["fire","water","wind","electric","iron"]},"description":"Boss weakness element (fire, water, wind, electric, iron)"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Max teams to return (default 50)"}],"operationId":"get_RecommendationByWeakness","responses":{"200":{"description":"Teams for the specified weakness"},"404":{"description":"No data found for the specified weakness"}}}},"/nikkes/recommendations/team-search":{"get":{"tags":["Recommendations"],"summary":"Search teams by units owned","description":"Find team compositions containing all of your selected units for a specific boss weakness. Pass multiple units as comma-separated values. Returns matching teams with missing unit slots highlighted.","parameters":[{"name":"weakness","in":"query","required":true,"schema":{"type":"string","enum":["fire","water","wind","electric","iron"]},"description":"Boss weakness element (fire, water, wind, electric, iron)"},{"name":"selected_units","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated unit names (e.g. Crown,Rapi)"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":50},"description":"Max teams to return (default 20)"}],"operationId":"get_RecommendationTeamSearch","responses":{"200":{"description":"Matching teams found"},"404":{"description":"No data found for the specified weakness"}}}},"/nikkes/recommendations/similar-teams":{"get":{"tags":["Recommendations"],"summary":"Find similar teams in a cluster","description":"Returns alternative team compositions from the same cluster — teams with similar archetypes but different unit swaps.","parameters":[{"name":"weakness","in":"query","required":true,"schema":{"type":"string","enum":["fire","water","wind","electric","iron"]},"description":"Boss weakness element (fire, water, wind, electric, iron)"},{"name":"cluster_id","in":"query","required":true,"schema":{"type":"integer"},"description":"Cluster ID from a previous team result"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":50},"description":"Max teams to return (default 10)"}],"operationId":"get_RecommendationSimilarTeams","responses":{"200":{"description":"Similar teams in the cluster"},"404":{"description":"No cluster found for the specified weakness and cluster_id"}}}},"/nikkes/recommendations/unit-pairing":{"get":{"tags":["Recommendations"],"summary":"Get unit pairing suggestions","description":"Find units that frequently appear alongside your selected units in competitive team compositions. Pass multiple units as comma-separated values. Results are weighted by team usage count.","parameters":[{"name":"weakness","in":"query","required":true,"schema":{"type":"string","enum":["fire","water","wind","electric","iron"]},"description":"Boss weakness element (fire, water, wind, electric, iron)"},{"name":"selected_units","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated unit names (e.g. Crown,Rapi)"},{"name":"limit","in":"query","schema":{"type":"integer","default":15,"minimum":1,"maximum":50},"description":"Max suggestions to return (default 15)"}],"operationId":"get_RecommendationUnitPairing","responses":{"200":{"description":"Unit pairing suggestions"},"404":{"description":"No data found for the specified weakness"}}}},"/nikkes/health":{"get":{"tags":["Health"],"summary":"Health check for the Nikke API","operationId":"get_HealthCheck","responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"timestamp":{"type":"string"}},"required":["success","message","timestamp"]}}}}}}},"/nikkes/{name}":{"get":{"tags":["Nikkes"],"summary":"Get a specific Nikke unit by name","parameters":[{"name":"name","in":"path","required":true,"description":"The name of the Nikke unit","schema":{"type":"string"}},{"name":"include_sr","in":"query","schema":{"type":"boolean","default":false},"description":"If true, also match SR-rarity units (default false: SR is excluded)"}],"operationId":"get_NikkeRead","responses":{"200":{"description":"Nikke unit details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"name":{"type":"string"},"tier":{"type":"string"},"general_tier":{"type":["string","null"]},"raid_tier":{"type":["string","null"]},"element":{"type":"string"},"weapon":{"type":"string"},"role":{"type":"string"},"rarity":{"type":"string","enum":["SSR","SR"]},"manufacturer":{"type":"string"},"burst_type":{"type":["string","null"]},"investment_priority":{"type":["string","null"]},"skill1_target":{"type":["number","null"]},"skill2_target":{"type":["number","null"]},"burst_target":{"type":["number","null"]},"skill1_name":{"type":["string","null"]},"skill2_name":{"type":["string","null"]},"burst_name":{"type":["string","null"]},"special_requirements":{"type":["string","null"]},"special_notes":{"type":["string","null"]},"normalized_notes":{"type":["string","null"]}},"required":["name","tier","element","weapon","role"]}},"required":["success","data"]}}}},"404":{"description":"Nikke not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"hint":{"type":"string"}},"required":["success","error"]}}}}}}},"/bosses":{"get":{"tags":["Bosses"],"summary":"List all boss units with optional filters","parameters":[{"name":"season","in":"query","required":false,"description":"Filter by season","schema":{"type":"string"}},{"name":"weakness","in":"query","required":false,"description":"Filter by elemental weakness (Fire, Water, Electric, Wind, Iron)","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Filter by boss name (case-insensitive, partial match)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number (default: 1)","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"description":"Results per page (default: 50, max: 100)","schema":{"type":"integer","minimum":1,"maximum":100}}],"operationId":"get_BossList","responses":{"200":{"description":"List of bosses","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"season":{"type":"string"},"weakness":{"type":"string"}},"required":["id","name","season","weakness"]}},"count":{"type":"number"},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"}},"required":["success","data","count","total","page","limit"]}}}}}}},"/bosses/{identifier}":{"get":{"tags":["Bosses"],"summary":"Get a specific boss by name or ID","parameters":[{"name":"identifier","in":"path","required":true,"description":"Boss name or ID","schema":{"type":"string"}}],"operationId":"get_BossRead","responses":{"200":{"description":"Boss details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"season":{"type":"string"},"weakness":{"type":"string"},"notes":{"type":["string","null"]},"current_meta":{"type":["string","null"]},"attacks":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"trigger":{"type":"string"},"target":{"type":"string"},"effect":{"type":"string"},"dodge":{"type":"string"},"count":{"type":"number"},"duration":{"type":"string"},"frequency":{"type":"string"},"timing":{"type":"string"},"restriction":{"type":"string"},"removal":{"type":"string"},"quantity":{"type":"string"},"interrupt":{"type":"string"}},"required":["name","type","effect"]}},"debuffs":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"target":{"type":"string"},"trigger":{"type":"string"},"preventable":{"type":"boolean"},"prevention":{"type":"string"},"stacks":{"type":"number"},"per":{"type":"string"},"max_stacks":{"type":"number"},"effect":{"type":"string"},"duration":{"type":"string"},"removal":{"type":"string"},"mitigation":{"type":"string"},"heal_window":{"type":"string"},"recommendation":{"type":"string"},"critical":{"type":"string"}},"required":["name","type"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["name","season","weakness"]}},"required":["success","data"]}}}},"404":{"description":"Boss not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}}},"webhooks":{}}