{"openapi":"3.1.0","info":{"title":"AgentMarket API","version":"1.0.0","summary":"Agents marketplace HTTP API","description":"Public API for integrating AgentMarket with other systems.\n\nCapabilities:\n- Search and list agents\n- Upload / publish an agent package (Bearer API token required)\n- Fetch agent detail\n- Resolve a download URL for the latest agent package\n\nRead endpoints are public. Upload (`POST /api/agents`) requires\n`Authorization: Bearer <token>`. Issue and revoke tokens after signing in\nat `/account/tokens`.\n","contact":{"name":"AgentMarket"}},"license":{"name":"Proprietary"},"servers":[{"url":"http://localhost:3000","description":"Local development"},{"url":"/","description":"Current host"}],"tags":[{"name":"Agents","description":"Discover and download Agents"}],"paths":{"/api/agents":{"get":{"tags":["Agents"],"operationId":"listAgents","summary":"List or search agents","description":"Returns a paginated agent 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":"Agent list page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResult"},"examples":{"trending":{"summary":"Trending agents","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":"agents-lab","name":"Agents 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":["Agents"],"operationId":"uploadAgent","summary":"Upload / publish an agent","description":"Upload a new agent or a new version of an existing agent.\n\nMultipart fields:\n- `name` (required): agent display name (also used to derive slug)\n- `description` (required): short agent description / summary\n- `package` (required): zip file that includes `AGENT.md`, `agent.yaml`, and `schemas/input.schema.json` + `schemas/output.schema.json`\n- `version` (optional): semver, default `1.0.0`\n- `category`, `license`, `changelog` (optional)\n\nRequires a Bearer API token. Create or revoke tokens at `/account/tokens`\nafter signing in. Revoked tokens receive `401`.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AgentUploadRequest"},"encoding":{"package":{"contentType":"application/zip"}}}}},"responses":{"200":{"description":"New version added to an existing agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUploadResponse"}}}},"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUploadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Agent version already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Agent \"code-reviewer-agent\" version 1.0.0 already exists"}}}}}}},"/api/agents/{slug}":{"get":{"tags":["Agents"],"operationId":"getAgentBySlug","summary":"Get agent detail","description":"Returns full agent metadata, AGENT.md content, and version history.","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"Agent detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDetailResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{slug}/download-url":{"get":{"tags":["Agents"],"operationId":"getAgentDownloadUrl","summary":"Get agent package download URL","description":"Resolves the latest package download link for other systems.\nThe returned `downloadUrl` points to `/api/agents/{slug}/download`,\nwhich streams the zip package (`AGENT.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/AgentDownloadUrlResponse"},"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/agents/code-reviewer/download","downloadPath":"/api/agents/code-reviewer/download"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{slug}/download":{"get":{"tags":["Agents"],"operationId":"downloadAgentPackage","summary":"Download agent package zip","description":"Streams the agent zip package as an attachment and increments the\nagent 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":["Agents"],"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":"Agent 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/AgentTab","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/AgentSort","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":{"AgentTab":{"type":"string","enum":["trending","featured","official","new"]},"AgentSort":{"type":"string","enum":["name","category","popularity"]},"AgentStats":{"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"}}},"AgentListItem":{"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/AgentStats"},"latestVersion":{"type":["string","null"]},"publisher":{"$ref":"#/components/schemas/Publisher"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AgentVersion":{"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"}}},"AgentDetail":{"allOf":[{"$ref":"#/components/schemas/AgentListItem"},{"type":"object","additionalProperties":false,"required":["description","versions"],"properties":{"description":{"type":"string","description":"Full AGENT.md content (including frontmatter)"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/AgentVersion"}}}}]},"AgentListResult":{"type":"object","additionalProperties":false,"required":["items","total","page","pageSize"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentListItem"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1}}},"AgentDetailResponse":{"type":"object","additionalProperties":false,"required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"}}},"AgentUploadRequest":{"type":"object","additionalProperties":false,"required":["name","description","package"],"properties":{"name":{"type":"string","description":"Agent display name","example":"code-reviewer"},"description":{"type":"string","description":"Short agent description / summary","example":"Review pull requests for bugs and maintainability."},"package":{"type":"string","format":"binary","description":"Zip package containing AGENT.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."}}},"AgentUploadResponse":{"type":"object","additionalProperties":false,"required":["agent","created","version","downloadPath"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"},"created":{"type":"boolean","description":"true when a new agent slug was created"},"version":{"type":"string"},"downloadPath":{"type":"string","example":"/api/agents/code-reviewer/download"}}},"AgentDownloadUrlResponse":{"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"}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API token","description":"API token issued at `/account/tokens` after login.\nExample: `Authorization: Bearer am_...`\n"}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing, invalid, or revoked API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid or revoked API token."}}}},"NotFound":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Agent not found"}}}}}},"security":[]}