{"openapi":"3.1.0","info":{"title":"SkillHub API","version":"0.12.0","description":"Anonymous agent-facing API. All responses use a { data, meta } envelope; errors use { error, meta }."},"servers":[{"url":"https://skillhub-api.fikahost.app"}],"components":{"schemas":{"Meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]},"PagedMeta":{"type":"object","properties":{"request_id":{"type":"string"},"page":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"search":{"type":"object","properties":{"match":{"type":"string","enum":["all","any"]},"terms":{"type":"array","items":{"type":"string"}}}}},"required":["request_id"]},"SkillSummary":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"name_i18n":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"description_i18n":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"thumbnail_url":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"status":{"type":"string"},"install_command":{"type":"string"},"risk_level":{"type":"string","enum":["low","medium","high","critical"]},"roles":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"array","items":{"type":"string"}},"target_agents":{"type":"array","items":{"type":"string"}}}},"InstallManifest":{"type":"object","description":"Coarse shape; the CLI is the source of truth for install semantics.","properties":{"provider":{"type":"string"},"slug":{"type":"string"},"version":{"type":"string"},"commit_sha":{"type":"string","nullable":true},"raw_base_url":{"type":"string"},"risk":{"type":"object","properties":{"level":{"type":"string"}}},"runtime":{"type":"object","properties":{"install_scope":{"type":"string"},"target_agents":{"type":"array","items":{"type":"string"}}}},"artifacts":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"sha256":{"type":"string"},"raw_url":{"type":"string"}}}}}},"SkillEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillSummary"},"meta":{"$ref":"#/components/schemas/Meta"}}},"SkillListEnvelope":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillSummary"}},"meta":{"$ref":"#/components/schemas/PagedMeta"}}},"InstallManifestEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InstallManifest"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code, e.g. not_found, invalid_request, rate_limited."},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"paths":{"/api/v1/agent/skills":{"get":{"summary":"List published skills","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"role","in":"query","schema":{"type":"string"}},{"name":"capability","in":"query","schema":{"type":"string"}},{"name":"target_agent","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lang","in":"query","description":"Display locale for name/description (e.g. zh-TW, en). Falls back to Accept-Language, then the platform default.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paged results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillListEnvelope"}}}}}}},"/api/v1/agent/search":{"get":{"summary":"Search published skills","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"role","in":"query","schema":{"type":"string"}},{"name":"capability","in":"query","schema":{"type":"string"}},{"name":"target_agent","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lang","in":"query","description":"Display locale for name/description (e.g. zh-TW, en). Falls back to Accept-Language, then the platform default.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paged results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillListEnvelope"}}}}}}},"/api/v1/agent/skills/{provider}/{slug}":{"get":{"summary":"Get skill details","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","description":"Display locale for name/description (e.g. zh-TW, en). Falls back to Accept-Language, then the platform default.","schema":{"type":"string"}}],"responses":{"200":{"description":"Skill details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/agent/skills/{provider}/{slug}/install-manifest":{"get":{"summary":"Get install manifest","description":"Anonymous. Counts one unit of the guest install quota per skill@version per guest per 24h when the platform has a quota configured; API-key callers are not metered.","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-SkillHub-Anon-Id","in":"header","required":false,"description":"Stable random per-machine id sent by the CLI for guests (no API key). Keys the guest install quota so people behind one shared IP are not lumped together; without it the quota falls back to the client IP. Ignored when an API key is presented (token holders are never metered).","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{7,127}$"}}],"responses":{"200":{"description":"Install manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallManifestEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Guest install quota exhausted (error.code = guest_quota_exceeded). details: { limit, remaining: 0, reset_at, window_hours, register_url | null, login_hint }. Register (or ask the admin for an account), copy the CLI Access Token from the console, then `skillhub login <token>` to lift it. Metered responses also carry X-Guest-Quota-Limit / X-Guest-Quota-Remaining / X-Guest-Quota-Reset (unix seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/hosted/skills/{provider}/{slug}/versions/{version}/files":{"get":{"summary":"Download one file of a hosted skill's live version","description":"Raw file body (text/markdown or text/plain) referenced by the install manifest's raw_base_url. Public skills: current version only. Shares the guest install quota grant with the manifest route, so the CLI's per-file downloads are free once the manifest was fetched; a direct fetch is metered the same way.","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"type":"string"},"description":"Artifact path inside the skill, e.g. SKILL.md"},{"name":"X-SkillHub-Anon-Id","in":"header","required":false,"description":"Stable random per-machine id sent by the CLI for guests (no API key). Keys the guest install quota so people behind one shared IP are not lumped together; without it the quota falls back to the client IP. Ignored when an API key is presented (token holders are never metered).","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{7,127}$"}}],"responses":{"200":{"description":"File contents"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Guest install quota exhausted (error.code = guest_quota_exceeded). details: { limit, remaining: 0, reset_at, window_hours, register_url | null, login_hint }. Register (or ask the admin for an account), copy the CLI Access Token from the console, then `skillhub login <token>` to lift it. Metered responses also carry X-Guest-Quota-Limit / X-Guest-Quota-Remaining / X-Guest-Quota-Reset (unix seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/agent/skills/{provider}/{slug}/install-stats":{"get":{"summary":"Get install stats for a skill","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Install stats"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/agent/role-packs":{"get":{"summary":"List published role packs","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lang","in":"query","description":"Display locale for name/description (e.g. zh-TW, en). Falls back to Accept-Language, then the platform default.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paged role packs"}}}},"/api/v1/agent/role-packs/{provider}/{slug}":{"get":{"summary":"Get role pack details","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","description":"Display locale for name/description (e.g. zh-TW, en). Falls back to Accept-Language, then the platform default.","schema":{"type":"string"}}],"responses":{"200":{"description":"Role pack details"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/agent/role-packs/{provider}/{slug}/install-manifest":{"get":{"summary":"Get role pack install manifest","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Role pack install manifest"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}