{"openapi":"3.1.0","info":{"title":"Agent Plugin Marketplace API","version":"1.0.0","description":"Read-only REST API for the Agent Plugin Marketplace, a community index of open-source Agent Plugins (skills and MCP servers) packaged per the Agent Plugins specification: https://agent-plugins.org/specification. All endpoints are GET-only, return JSON, require no authentication, and send permissive CORS headers (Access-Control-Allow-Origin: *). Responses are cacheable for 60 seconds. Errors use the shape { \"error\": { \"code\", \"message\" } }."},"servers":[{"url":"/"}],"paths":{"/api/v1/plugins":{"get":{"operationId":"listPlugins","summary":"List and search plugins","description":"Paginated plugin summaries. Filters combine with AND. Invalid enum values (type, transport, sort) are rejected with 400 bad_request.","parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query over name, description, keywords, and author (max 200 chars).","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"description":"Exact keyword match. Categories are manifest keywords; see /api/v1/categories.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Only plugins containing this component type.","schema":{"type":"string","enum":["skills","mcp"]}},{"name":"transport","in":"query","required":false,"description":"Only plugins with at least one MCP server using this transport.","schema":{"type":"string","enum":["stdio","streamable-http","sse"]}},{"name":"sort","in":"query","required":false,"description":"Sort order: stars (repo stars, default), updated (repo push date), recent (first indexed).","schema":{"type":"string","enum":["stars","updated","recent"],"default":"stars"}},{"name":"page","in":"query","required":false,"description":"Page number, 1-based. Values below 1 are clamped to 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page, clamped to 1..50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":24}}],"responses":{"200":{"description":"A page of plugin summaries.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PluginSummary"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"data":[{"slug":"acme-github-tools","name":"github-tools","version":"1.2.0","description":"Skills and an MCP server for triaging GitHub issues.","authorName":"Acme Labs","license":"MIT","keywords":["github","issues","automation"],"repoUrl":"https://github.com/acme/github-tools","repoStars":412,"skillCount":3,"mcpCount":1,"transports":["stdio"],"indexedAt":"2026-08-07T09:14:00.000Z"}],"meta":{"page":1,"per_page":24,"total":137,"total_pages":6}}}}},"400":{"description":"Invalid enum value for type, transport, or sort.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"Invalid type \"foo\". Valid values: skills, mcp."}}}}}}}},"/api/v1/plugins/{slug}":{"get":{"operationId":"getPlugin","summary":"Get one plugin","description":"Full detail for a single plugin: summary fields plus links, raw manifest, skills, and MCP server configs.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug, as returned by the list endpoint.","schema":{"type":"string"}}],"responses":{"200":{"description":"The plugin.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PluginDetail"}}}}}},"404":{"description":"No plugin with that slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No plugin with slug \"nope\"."}}}}}}}},"/api/v1/stats":{"get":{"operationId":"getStats","summary":"Registry totals","description":"Counts of indexed plugins, skills, MCP servers, and categories.","responses":{"200":{"description":"Registry totals.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Stats"}}}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List categories","description":"Categories derived from manifest keywords, ranked by plugin count (top 100).","responses":{"200":{"description":"Categories with plugin counts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}}},"components":{"schemas":{"PluginSummary":{"type":"object","description":"A plugin as it appears in list results.","required":["slug","name","version","description","authorName","license","keywords","repoUrl","repoStars","skillCount","mcpCount","transports","indexedAt"],"properties":{"slug":{"type":"string","description":"Unique registry slug; use with /api/v1/plugins/{slug}."},"name":{"type":"string","description":"Plugin name from plugin.json."},"version":{"type":["string","null"]},"description":{"type":["string","null"]},"authorName":{"type":["string","null"]},"license":{"type":["string","null"],"description":"SPDX identifier, when declared."},"keywords":{"type":"array","items":{"type":"string"}},"repoUrl":{"type":"string","description":"GitHub repository the plugin was indexed from."},"repoStars":{"type":"integer"},"skillCount":{"type":"integer"},"mcpCount":{"type":"integer","description":"Number of MCP servers declared in mcp.json."},"transports":{"type":"array","description":"Distinct transports across the plugin's MCP servers.","items":{"type":"string","enum":["stdio","streamable-http","sse"]}},"indexedAt":{"type":"string","format":"date-time","description":"When the plugin was last indexed."}}},"PluginDetail":{"description":"Full plugin record: everything in PluginSummary plus links, manifest, and components.","allOf":[{"$ref":"#/components/schemas/PluginSummary"},{"type":"object","required":["homepage","repository","pluginPath","repoPushedAt","manifest","skills","mcpServers"],"properties":{"homepage":{"type":["string","null"]},"repository":{"type":["string","null"],"description":"Repository URL as declared in the manifest."},"pluginPath":{"type":"string","description":"Path of the plugin directory inside its repository."},"repoPushedAt":{"type":["string","null"],"format":"date-time"},"manifest":{"type":"string","description":"Raw plugin.json body as indexed (untrusted text)."},"skills":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/McpServerEntry"}}}}]},"Skill":{"type":"object","required":["dirName","name","description"],"properties":{"dirName":{"type":"string","description":"Directory name under skills/."},"name":{"type":"string","description":"Name from the SKILL.md frontmatter."},"description":{"type":["string","null"]}}},"McpServerEntry":{"type":"object","required":["serverId","transport","config"],"properties":{"serverId":{"type":"string","description":"Key under mcpServers in the plugin's mcp.json."},"transport":{"type":"string","enum":["stdio","streamable-http","sse"]},"config":{"type":"object","description":"Server config as declared in mcp.json (untrusted; shape varies by transport).","additionalProperties":true}}},"Stats":{"type":"object","required":["plugins","skills","mcpServers","categories"],"properties":{"plugins":{"type":"integer"},"skills":{"type":"integer"},"mcpServers":{"type":"integer"},"categories":{"type":"integer"}}},"Category":{"type":"object","required":["name","count"],"properties":{"name":{"type":"string","description":"Lowercased manifest keyword."},"count":{"type":"integer","description":"Number of plugins carrying the keyword."}}},"Meta":{"type":"object","description":"Pagination metadata for list responses.","required":["page","per_page","total","total_pages"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":50},"total":{"type":"integer","description":"Total matching plugins across all pages."},"total_pages":{"type":"integer","minimum":1}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable code: bad_request or not_found."},"message":{"type":"string","description":"Human-readable explanation."}}}}}}}}