{"openapi":"3.1.0","info":{"title":"Nia Skills API","version":"1.0.0","description":"Public, read-mostly API over the Nia Skills registry. Anonymous requests are limited to 60 per minute; an API key raises that to 1000. Every GET is cacheable and returns an ETag.","license":{"name":"MIT"}},"servers":[{"url":"https://niaskills.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An `nsk_live_…` API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Skill":{"type":"object","properties":{"slug":{"type":"string","example":"nia/html-to-figma"},"owner":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"summary":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"agents":{"type":"array","items":{"type":"string"}},"license":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"install":{"type":"string","example":"npx niaskills add nia/html-to-figma"},"html_url":{"type":"string","format":"uri"},"repo_url":{"type":"string","format":"uri"},"preview":{"type":"object","properties":{"image":{"type":["string","null"],"format":"uri"},"video":{"type":["string","null"],"format":"uri"}}},"stats":{"type":"object","properties":{"installs":{"type":"integer"},"installs_7d":{"type":"integer"},"views_7d":{"type":"integer"},"likes":{"type":"integer"},"dislikes":{"type":"integer"},"comments":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}},"paths":{"/skills":{"get":{"summary":"List skills","description":"Ranked by the selected sort. `hot` is the default and matches the home page.","parameters":[{"name":"sort","in":"query","schema":{"type":"string","enum":["hot","trending","top","new"],"default":"hot"}},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"agent","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"A page of skills","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/skills/{owner}/{name}":{"get":{"summary":"Get one skill","description":"Full metadata including README, SKILL.md body, file list and requirements.","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The skill","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Skill"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/skills/{owner}/{name}/manifest":{"get":{"summary":"Install manifest","description":"What the CLI resolves before downloading: version, commit, file list with hashes, tarball URL and the target install path.","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The manifest"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/skills/{owner}/{name}/download":{"get":{"summary":"Download the skill tarball","description":"302 redirect to the pinned tarball on codeload.github.com.","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the tarball"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/skills/{owner}/{name}/comments":{"get":{"summary":"List comments","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Visible comments"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/topics":{"get":{"summary":"Topic facets with counts","responses":{"200":{"description":"Topics"}}}},"/agents":{"get":{"summary":"Agent facets with counts","responses":{"200":{"description":"Agents"}}}},"/search":{"get":{"summary":"Search skills","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Matching skills"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/stats/{owner}/{name}":{"get":{"summary":"Counters only","description":"Cheap and cacheable — intended for badges and dashboards that poll.","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Counters"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/installs":{"post":{"summary":"Report an install","description":"Sent by the CLI. The server increments by one after deduplicating per skill, IP and day; the body carries no counter.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["skill"],"properties":{"skill":{"type":"string","example":"nia/html-to-figma"},"version":{"type":"string"},"agent":{"type":"string","example":"claude-code"},"cli_version":{"type":"string"}}}}}},"responses":{"202":{"description":"Accepted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/votes":{"post":{"summary":"Like, dislike, or clear a vote","description":"Browser-only. Requires the anonymous `nsk_vid` session cookie, which is what lets a vote be changed or withdrawn later; an API key is not a substitute and does not authorise this endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["skill","value"],"properties":{"skill":{"type":"string"},"value":{"type":"integer","enum":[1,-1,0]}}}}}},"responses":{"200":{"description":"Fresh totals"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/comments":{"post":{"summary":"Post a comment","description":"Browser-only, like `/votes`. Comments are anonymous: `name` is an unverified label, not an identity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["skill","body"],"properties":{"skill":{"type":"string"},"body":{"type":"string","maxLength":4000},"name":{"type":"string","maxLength":40},"parent_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Created"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"Rate limited — 60 req/min anonymous, 1000 req/min with an API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}}}}