{"openapi":"3.1.0","info":{"title":"SkillMarket API","version":"1.0.0","summary":"Agent Skills marketplace HTTP API","description":"Public API for integrating SkillMarket with other systems.\n\nCapabilities:\n- Search and list skills\n- Upload / publish a skill package\n- Fetch skill detail\n- Resolve a download URL for the latest skill package\n\nAuthentication is **not required** in this phase.\n","contact":{"name":"SkillMarket"}},"license":{"name":"Proprietary"},"servers":[{"url":"http://localhost:3000","description":"Local development"},{"url":"/","description":"Current host"}],"tags":[{"name":"Skills","description":"Discover and download Agent Skills"}],"paths":{"/api/skills":{"get":{"tags":["Skills"],"operationId":"listSkills","summary":"List or search skills","description":"Returns a paginated skill list for table/list UIs.\nUse `q` for keyword search across slug, display name, summary, and category.\nUse `tab` to switch discovery views (trending / featured / official / new).\n","parameters":[{"$ref":"#/components/parameters/Tab"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Sort"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Skill list page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillListResult"},"examples":{"trending":{"summary":"Trending skills","value":{"items":[{"slug":"code-reviewer","displayName":"code-reviewer","summary":"Review pull requests for bugs and maintainability.","category":"engineering","topics":["review","quality"],"isFeatured":true,"isOfficial":true,"stats":{"downloads":12840,"installs":3200,"stars":890,"versions":1},"latestVersion":"1.2.0","publisher":{"handle":"skills-lab","name":"Skills Lab"},"createdAt":"2025-11-02T08:00:00.000Z","updatedAt":"2026-07-18T10:00:00.000Z"}],"total":1,"page":1,"pageSize":50}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"post":{"tags":["Skills"],"operationId":"uploadSkill","summary":"Upload / publish a skill","description":"Upload a new skill or a new version of an existing skill.\n\nMultipart fields:\n- `name` (required): skill display name (also used to derive slug)\n- `description` (required): short skill description / summary\n- `package` (required): zip file that includes `SKILL.md`\n- `version` (optional): semver, default `1.0.0`\n- `category`, `license`, `changelog` (optional)\n\nNo authentication is required in this phase.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SkillUploadRequest"},"encoding":{"package":{"contentType":"application/zip"}}}}},"responses":{"200":{"description":"New version added to an existing skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillUploadResponse"}}}},"201":{"description":"Skill created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillUploadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"Skill version already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Skill \"code-reviewer\" version 1.0.0 already exists"}}}}}}},"/api/skills/{slug}":{"get":{"tags":["Skills"],"operationId":"getSkillBySlug","summary":"Get skill detail","description":"Returns full skill metadata, SKILL.md content, and version history.","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"Skill detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillDetailResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/skills/{slug}/download-url":{"get":{"tags":["Skills"],"operationId":"getSkillDownloadUrl","summary":"Get skill package download URL","description":"Resolves the latest package download link for other systems.\nThe returned `downloadUrl` points to `/api/skills/{slug}/download`,\nwhich streams the zip package (`SKILL.md` required inside).\nThis endpoint does **not** increment download counters; counting happens\nwhen the download endpoint is actually fetched.\n","parameters":[{"$ref":"#/components/parameters/Slug"},{"name":"version","in":"query","required":false,"description":"Optional semver. Defaults to the latest version.","schema":{"type":"string","example":"1.2.0"}}],"responses":{"200":{"description":"Download URL payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillDownloadUrlResponse"},"examples":{"latest":{"value":{"slug":"code-reviewer","version":"1.2.0","filename":"code-reviewer-1.2.0.zip","contentType":"application/zip","fileSize":770,"sha256":"ab12...","license":"MIT","downloadUrl":"http://localhost:3000/api/skills/code-reviewer/download","downloadPath":"/api/skills/code-reviewer/download"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/skills/{slug}/download":{"get":{"tags":["Skills"],"operationId":"downloadSkillPackage","summary":"Download skill package zip","description":"Streams the skill zip package as an attachment and increments the\nskill download counter. Prefer resolving the URL via\n`/download-url` first when integrating from other systems.\n","parameters":[{"$ref":"#/components/parameters/Slug"},{"name":"version","in":"query","required":false,"description":"Optional semver. Defaults to the latest version.","schema":{"type":"string","example":"1.2.0"}}],"responses":{"200":{"description":"Zip package binary","headers":{"Content-Disposition":{"schema":{"type":"string"},"example":"attachment; filename=\"code-reviewer-1.2.0.zip\""}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"502":{"description":"Upstream object storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/openapi":{"get":{"tags":["Skills"],"operationId":"getOpenApiDocument","summary":"Fetch OpenAPI document","description":"Returns this OpenAPI specification as JSON (default) or YAML.","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","yaml"],"default":"json"}}],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"application/yaml":{"schema":{"type":"string"}}}}}}}},"components":{"parameters":{"Slug":{"name":"slug","in":"path","required":true,"description":"Skill slug identifier","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"code-reviewer"}},"Tab":{"name":"tab","in":"query","required":false,"description":"Discovery tab / collection","schema":{"$ref":"#/components/schemas/SkillTab","default":"trending"}},"Query":{"name":"q","in":"query","required":false,"description":"Keyword search","schema":{"type":"string","example":"sql"}},"Sort":{"name":"sort","in":"query","required":false,"description":"Sort field for list views","schema":{"$ref":"#/components/schemas/SkillSort","default":"popularity"}},"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"SkillTab":{"type":"string","enum":["trending","featured","official","new"]},"SkillSort":{"type":"string","enum":["name","category","popularity"]},"SkillStats":{"type":"object","additionalProperties":false,"required":["downloads","installs","stars","versions"],"properties":{"downloads":{"type":"integer","minimum":0},"installs":{"type":"integer","minimum":0},"stars":{"type":"integer","minimum":0},"versions":{"type":"integer","minimum":0},"comments":{"type":"integer","minimum":0}}},"Publisher":{"type":"object","additionalProperties":false,"required":["handle","name"],"properties":{"handle":{"type":"string"},"name":{"type":"string"}}},"SkillListItem":{"type":"object","additionalProperties":false,"required":["slug","displayName","summary","category","topics","isFeatured","isOfficial","stats","latestVersion","publisher","createdAt","updatedAt"],"properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"summary":{"type":"string"},"category":{"type":["string","null"]},"topics":{"type":"array","items":{"type":"string"}},"isFeatured":{"type":"boolean"},"isOfficial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/SkillStats"},"latestVersion":{"type":["string","null"]},"publisher":{"$ref":"#/components/schemas/Publisher"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SkillVersion":{"type":"object","additionalProperties":false,"required":["version","changelog","license","fileSize","sha256","createdAt"],"properties":{"version":{"type":"string"},"changelog":{"type":["string","null"]},"license":{"type":["string","null"]},"fileSize":{"type":"integer","minimum":0},"sha256":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"SkillDetail":{"allOf":[{"$ref":"#/components/schemas/SkillListItem"},{"type":"object","additionalProperties":false,"required":["description","versions"],"properties":{"description":{"type":"string","description":"Full SKILL.md content (including frontmatter)"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/SkillVersion"}}}}]},"SkillListResult":{"type":"object","additionalProperties":false,"required":["items","total","page","pageSize"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SkillListItem"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1}}},"SkillDetailResponse":{"type":"object","additionalProperties":false,"required":["skill"],"properties":{"skill":{"$ref":"#/components/schemas/SkillDetail"}}},"SkillUploadRequest":{"type":"object","additionalProperties":false,"required":["name","description","package"],"properties":{"name":{"type":"string","description":"Skill display name","example":"code-reviewer"},"description":{"type":"string","description":"Short skill description / summary","example":"Review pull requests for bugs and maintainability."},"package":{"type":"string","format":"binary","description":"Zip package containing SKILL.md"},"version":{"type":"string","description":"Semver version (default 1.0.0)","example":"1.0.0"},"category":{"type":"string","example":"engineering"},"license":{"type":"string","example":"MIT"},"changelog":{"type":"string","example":"Initial public release."}}},"SkillUploadResponse":{"type":"object","additionalProperties":false,"required":["skill","created","version","downloadPath"],"properties":{"skill":{"$ref":"#/components/schemas/SkillDetail"},"created":{"type":"boolean","description":"true when a new skill slug was created"},"version":{"type":"string"},"downloadPath":{"type":"string","example":"/api/skills/code-reviewer/download"}}},"SkillDownloadUrlResponse":{"type":"object","additionalProperties":false,"required":["slug","version","filename","contentType","fileSize","sha256","license","downloadUrl","downloadPath"],"properties":{"slug":{"type":"string"},"version":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string","example":"application/zip"},"fileSize":{"type":"integer","minimum":0},"sha256":{"type":["string","null"]},"license":{"type":["string","null"]},"downloadUrl":{"type":"string","format":"uri","description":"Absolute URL other systems can fetch"},"downloadPath":{"type":"string","description":"Path-only download endpoint"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Skill not found"}}}}}},"security":[]}