{"openapi":"3.0.3","info":{"title":"SkillsMP API","description":"Public API for discovering Claude Code skills from the SkillsMP marketplace. Search 1.2M+ skills by keyword or semantic query, filter by category and occupation.","version":"1.0.0","contact":{"name":"SkillsMP Support","url":"https://skillsmp.com/about"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://skillsmp.com","description":"Production server"}],"paths":{"/api/v1/skills/search":{"get":{"operationId":"searchSkills","summary":"Keyword search skills","description":"Search skills by keyword with optional filtering by category and occupation. Supports anonymous access with lower rate limits.","tags":["Skills"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200},"description":"Search query (keyword)"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1,"maximum":50},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":50},"description":"Items per page"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["stars","recent"],"default":"recent"},"description":"Sort order"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug (e.g. data-ai, devops)"},{"name":"occupation","in":"query","schema":{"type":"string"},"description":"Filter by SOC occupation slug (e.g. software-developers-151252)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"},"description":"Bearer API key (optional for anonymous access)"}],"responses":{"200":{"description":"Successful search response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"responseTimeMs":{"type":"integer"}}}}}}},"headers":{"X-RateLimit-Daily-Limit":{"schema":{"type":"integer"},"description":"Daily request limit"},"X-RateLimit-Daily-Remaining":{"schema":{"type":"integer"},"description":"Remaining daily requests"}}},"400":{"description":"Bad request - missing or invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/ai-search":{"get":{"operationId":"aiSearchSkills","summary":"AI semantic search skills","description":"Semantic search using vector embeddings. Returns skills most relevant to the natural language query. Requires API key authentication.","tags":["Skills"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Natural language search query"},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer API key"}],"responses":{"200":{"description":"Successful AI search response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string"},"filename":{"type":"string"},"score":{"type":"number"},"skill":{"$ref":"#/components/schemas/Skill"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"responseTimeMs":{"type":"integer"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/health":{"get":{"operationId":"healthCheck","summary":"Health check","description":"Check API and database availability","tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}},"503":{"description":"Service degraded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"degraded"}}}}}}}}}},"components":{"schemas":{"Skill":{"type":"object","properties":{"id":{"type":"string","description":"Unique skill identifier"},"name":{"type":"string","description":"Skill name"},"author":{"type":"string","description":"GitHub author username"},"description":{"type":"string","description":"Skill description"},"githubUrl":{"type":"string","format":"uri","description":"GitHub repository URL"},"skillUrl":{"type":"string","format":"uri","description":"SkillsMP detail page URL"},"stars":{"type":"integer","description":"GitHub star count"},"updatedAt":{"type":"integer","description":"Last update time (Unix timestamp)"}},"required":["id","name","author","description","githubUrl","skillUrl","stars","updatedAt"]},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key obtained from the developer portal"}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Skills","description":"Skill discovery and search"},{"name":"System","description":"System health and status"}],"externalDocs":{"description":"Developer Portal","url":"https://skillsmp.com/developers"}}