{"openapi":"3.1.0","info":{"title":"Aheliotech Skills Library API","version":"1.3.0","description":"Access publicly shared skills and knowledge. API keys carry a scope (skills, knowledge, or both) and access level (read or readwrite). Generate keys from the API Keys dialog in the app UI."},"servers":[{"url":"https://skills.aheliotech.app"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Skill":{"type":"object","properties":{"id":{"type":"string","description":"Unique slug identifier"},"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"intent":{"type":"string","description":"When / how to invoke this skill"},"instructions":{"type":"string","description":"Full markdown instructions"},"examples":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time"}}},"KnowledgeEntry":{"type":"object","properties":{"id":{"type":"string","description":"Unique slug identifier"},"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"content":{"type":"string","description":"Full markdown content"},"tags":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time"}}}}},"security":[{"bearerAuth":[]}],"paths":{"/library/skills":{"get":{"summary":"List public skills","operationId":"listSkills","description":"Requires an API key with `skills` scope and `read` access.","parameters":[{"name":"q","in":"query","description":"Full-text search","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated tags to filter by","schema":{"type":"string"}}],"responses":{"200":{"description":"Skills list","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"}}},"post":{"summary":"Create a skill via API","operationId":"createSkill","description":"Requires an API key with `skills` scope and `readwrite` access. The skill is automatically shared with everyone.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"intent":{"type":"string"},"instructions":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"400":{"description":"Validation error"},"403":{"description":"API key does not have readwrite access"}}}},"/library/skills/{id}":{"get":{"summary":"Get a skill by ID","operationId":"getSkill","description":"Requires an API key with `skills` scope and `read` access.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Skill is not publicly shared"},"404":{"description":"Skill not found"}}},"put":{"summary":"Update a skill via API","operationId":"updateSkill","description":"Requires an API key with `skills` scope and `readwrite` access. Only publicly shared skills can be updated.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"intent":{"type":"string"},"instructions":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"403":{"description":"API key lacks readwrite access or skill is not public"},"404":{"description":"Skill not found"}}}},"/library/categories":{"get":{"summary":"List categories that have public skills","operationId":"listSkillCategories","description":"Requires an API key with `skills` scope and `read` access.","responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing or invalid API key"}}}},"/library/knowledge":{"get":{"summary":"List public knowledge entries","operationId":"listKnowledge","description":"Requires an API key with `knowledge` scope and `read` access.","parameters":[{"name":"q","in":"query","description":"Full-text search","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated tags to filter by","schema":{"type":"string"}}],"responses":{"200":{"description":"Knowledge list","content":{"application/json":{"schema":{"type":"object","properties":{"knowledge":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeEntry"}},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"}}},"post":{"summary":"Create a knowledge entry via API","operationId":"createKnowledge","description":"Requires an API key with `knowledge` scope and `readwrite` access. The entry is automatically shared with everyone.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeEntry"}}}},"400":{"description":"Validation error"},"403":{"description":"API key does not have readwrite access"}}}},"/library/knowledge/{id}":{"get":{"summary":"Get a knowledge entry by ID","operationId":"getKnowledge","description":"Requires an API key with `knowledge` scope and `read` access.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Knowledge entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeEntry"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Entry is not publicly shared"},"404":{"description":"Entry not found"}}},"put":{"summary":"Update a knowledge entry via API","operationId":"updateKnowledge","description":"Requires an API key with `knowledge` scope and `readwrite` access. Only publicly shared entries can be updated.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeEntry"}}}},"403":{"description":"API key lacks readwrite access or entry is not public"},"404":{"description":"Entry not found"}}}},"/library/knowledge-categories":{"get":{"summary":"List categories that have public knowledge entries","operationId":"listKnowledgeCategories","description":"Requires an API key with `knowledge` scope and `read` access.","responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing or invalid API key"}}}}}}