{"openapi":"3.1.0","info":{"title":"Sports Knowledge API","version":"1.0.0","description":"A specification for serving SocialSportHub’s deterministic sports knowledge graph. SPECIFICATION ONLY — there is no live endpoint. Generated from the platform registries.","x-status":"specification-only","x-generated-from":"knowledge-graph + tools + comparisons + academy registries","x-entity-count":1492},"servers":[{"url":"https://socialsporthub.com/v1","description":"Planned base path — specification only, not a live server."}],"tags":[{"name":"Entities"},{"name":"Search"},{"name":"Compare"},{"name":"Calculators"},{"name":"Learning"},{"name":"Atlas"},{"name":"Recommendations"}],"x-entity-types":["sport","category","knowledge","glossary","physical-quality","equipment","rule","scoring","skill","technique","tactic","position","facility","strategy","role","surface","officiating","exercise","training-method","muscle-group","recovery-method","training-plan","training-guide","goal","persona","lifestyle","barrier","motivation","experience-level","comparison","discipline","movement-pattern","coaching","healthy-lifestyle","sports-science","adaptive-sports","curriculum","decision-making","skill-collection","sports-communication","session-type","beginners","atlas","movement-comparison","recommendation"],"x-resource-counts":{"entities":1492,"calculators":42,"comparisons":244,"courses":23},"paths":{"/v1/entities":{"get":{"summary":"List all entity types and their counts","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TypeList"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/entities/{type}":{"get":{"summary":"List entities of a type","tags":["Entities"],"parameters":[{"name":"type","in":"path","required":true,"description":"Entity type","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Items per page","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Locale (currently en)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/entities/{type}/{slug}":{"get":{"summary":"Get one entity as a resource","tags":["Entities"],"parameters":[{"name":"type","in":"path","required":true,"description":"Entity type","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"description":"Entity slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resource"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"get":{"summary":"Search across the knowledge graph","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"description":"Query text","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Filter by entity type","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/compare/{slug}":{"get":{"summary":"Get a head-to-head comparison","tags":["Compare"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Comparison slug (a-vs-b)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calculators":{"get":{"summary":"List calculators","tags":["Calculators"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatorList"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calculators/{slug}":{"get":{"summary":"Get a calculator specification (inputs + formula)","tags":["Calculators"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Calculator slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculator"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/learning/courses":{"get":{"summary":"List interactive courses","tags":["Learning"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseList"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/learning/courses/{sport}":{"get":{"summary":"Get a course with its modules","tags":["Learning"],"parameters":[{"name":"sport","in":"path","required":true,"description":"Sport slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Course"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/atlas":{"get":{"summary":"List knowledge-atlas dimensions","tags":["Atlas"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasList"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/recommendations/{goal}":{"get":{"summary":"Get explainable recommendations for a goal","tags":["Recommendations"],"parameters":[{"name":"goal","in":"path","required":true,"description":"Goal slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationList"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Relationship":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["type","id","name","url"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","pageSize","total","totalPages"]},"Resource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"apiUrl":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/Relationship"}},"jsonLd":{"type":"object","description":"Schema.org JSON-LD (Tier-A-safe)"},"meta":{"type":"object","properties":{"version":{"type":"string"},"generatedFrom":{"type":"string"}}}},"required":["id","type","slug","name","url","relationships","jsonLd"]},"ResourceList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"type":"object"}},"required":["data","pagination"]},"TypeList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"count":{"type":"integer"},"routeBase":{"type":"string"}}}}}},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Comparison":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"a":{"type":"object"},"b":{"type":"object"},"differences":{"type":"array","items":{"type":"string"}},"similarities":{"type":"array","items":{"type":"string"}}}},"Calculator":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"inputs":{"type":"array","items":{"type":"object"}},"formula":{"type":"object","properties":{"name":{"type":"string"},"expression":{"type":"string"},"source":{"type":"string"}}}}},"CalculatorList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Calculator"}}}},"Course":{"type":"object","properties":{"sportSlug":{"type":"string"},"sportName":{"type":"string"},"modules":{"type":"array","items":{"type":"object"}}}},"CourseList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Course"}}}},"AtlasList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}},"RecommendationList":{"type":"object","properties":{"goal":{"type":"string"},"data":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"status":{"type":"integer"}},"required":["error","status"]}}}}