{"openapi":"3.1.0","info":{"title":"skillxone API","version":"1.0.0","description":"Read the catalog, security reports and install instructions; suggest repositories and report problems. No authentication is needed. Reads are rate limited per client; writes are limited to 10 an hour. The server never runs install commands; it only returns text.","license":{"name":"Apache-2.0","identifier":"Apache-2.0"}},"servers":[{"url":"/"}],"paths":{"/api/health":{"get":{"summary":"Liveness and database check","operationId":"health","responses":{"200":{"description":"Healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok"},"database":{"const":"ok"}}}}}},"503":{"description":"Database unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"error"}}}}}}}}},"/api/v1/openapi.json":{"get":{"summary":"This document","operationId":"openapi","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/skills":{"get":{"summary":"List and filter skills","operationId":"listSkills","parameters":[{"name":"q","in":"query","required":false,"description":"Optional search text.","schema":{"type":"string"}},{"name":"agent","in":"query","required":false,"description":"Agent id, for example claude-code or codex.","schema":{"type":"string"}},{"name":"verification","in":"query","required":false,"description":"verified, unverified or flagged.","schema":{"type":"string","enum":["verified","unverified","flagged"]}},{"name":"category","in":"query","required":false,"description":"Category slug.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort order.","schema":{"type":"string","enum":["recommended","relevance","popular","trending","rising","maintained","updated","newest","name"]}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"integer","minimum":1,"maximum":100000}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"A page of skills.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillPage"}}}},"400":{"description":"Invalid paging.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"summary":"Ranked search","operationId":"search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"}},{"name":"agent","in":"query","required":false,"description":"Agent id, for example claude-code or codex.","schema":{"type":"string"}},{"name":"verification","in":"query","required":false,"description":"verified, unverified or flagged.","schema":{"type":"string","enum":["verified","unverified","flagged"]}},{"name":"category","in":"query","required":false,"description":"Category slug.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort order.","schema":{"type":"string","enum":["recommended","relevance","popular","trending","rising","maintained","updated","newest","name"]}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"integer","minimum":1,"maximum":100000}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Matching skills, best first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillPage"}}}},"400":{"description":"Missing q or invalid paging.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suggest":{"get":{"summary":"Skill-name completions","operationId":"suggest","parameters":[{"name":"q","in":"query","required":false,"description":"Partly typed name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Up to eight completions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}}}}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/categories":{"get":{"summary":"Categories with counts","operationId":"listCategories","responses":{"200":{"description":"Categories.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/trending":{"get":{"summary":"Trending skills","operationId":"trending","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"integer","minimum":1,"maximum":100000}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Trending skills and the basis used.","content":{"application/json":{"schema":{"type":"object","properties":{"basis":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}}}}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{id}":{"get":{"summary":"One skill","operationId":"getSkill","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"}}],"responses":{"200":{"description":"The skill with files, compatibility and ranking signals.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Skill"}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{id}/versions":{"get":{"summary":"Indexed versions","operationId":"listVersions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"}}],"responses":{"200":{"description":"Versions, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{id}/security":{"get":{"summary":"Security report for the current version","operationId":"getSecurity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SecurityReport"}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{id}/install":{"get":{"summary":"Install, update and uninstall instructions","operationId":"getInstall","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"}},{"name":"agent","in":"query","required":false,"description":"Agent id.","schema":{"type":"string","enum":["claude-code","codex"]}},{"name":"scope","in":"query","required":false,"description":"Install scope.","schema":{"type":"string","enum":["project","global"],"default":"project"}},{"name":"method","in":"query","required":false,"description":"Install method.","schema":{"type":"string","enum":["symlink","copy","manual"],"default":"symlink"}},{"name":"pin","in":"query","required":false,"description":"Pin to the verified commit when there is one.","schema":{"type":"string","enum":["true","false"],"default":"true"}},{"name":"shell","in":"query","required":false,"description":"Shell to quote for.","schema":{"type":"string","enum":["posix","powershell"],"default":"posix"}}],"responses":{"200":{"description":"The plan, or the reason none could be built.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/repositories/{id}":{"get":{"summary":"One repository","operationId":"getRepository","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"}}],"responses":{"200":{"description":"The repository.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/submissions":{"post":{"summary":"Suggest a GitHub repository","operationId":"createSubmission","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["repository"],"properties":{"repository":{"type":"string","description":"owner/repo or https://github.com/owner/repo"},"note":{"type":"string","maxLength":1000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Already suggested or listed: the existing record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResult"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResult"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A session cookie was sent but is no longer valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cross-site request, or a session cookie without a valid X-CSRF-Token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Body is not application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Submissions are closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/reports":{"post":{"summary":"Report a problem","operationId":"createReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","body"],"properties":{"type":{"type":"string","enum":["security_concern","false_positive","inaccurate_metadata","duplicate","takedown","other"]},"skillId":{"type":"string","description":"Required except for other and takedown."},"findingId":{"type":"string","description":"Required for false_positive."},"body":{"type":"string","minLength":10,"maxLength":5000},"contact":{"type":"string","maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"You already have an open report of this kind: that report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResult"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResult"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A session cookie was sent but is no longer valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cross-site request, or a session cookie without a valid X-CSRF-Token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Body is not application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error. No details are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Skill":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"verification":{"type":"string","enum":["VERIFIED","UNVERIFIED","FLAGGED"]},"lifecycle":{"type":"string","enum":["PENDING","SCANNING","COMPLETE","EXPIRED","FAILED"]},"agents":{"type":"array","items":{"type":"string"}},"quality":{"type":["number","null"]},"url":{"type":"string"}}},"SkillPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"}}}}},"SecurityReport":{"type":"object","properties":{"verification":{"type":"string"},"lifecycle":{"type":"string"},"expiresAt":{"type":["string","null"]},"decision":{"type":["object","null"]},"report":{"type":["object","null"]}}},"SubmissionResult":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"repository":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"}}},"duplicate":{"type":"boolean"},"alreadyIndexed":{"type":"boolean"}}},"ReportResult":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"}}},"duplicate":{"type":"boolean"}}}}}}