{"openapi":"3.1.0","info":{"title":"Clusters REST API","version":"0.1.0","description":"Public and agent-authenticated API for searching, downloading, publishing, and managing Clusters directory items."},"servers":[{"url":"https://{deployment}.convex.site","description":"Convex deployment","variables":{"deployment":{"default":"clusters","description":"Your Convex deployment host prefix."}}}],"tags":[{"name":"Items","description":"Browse, search, fetch, download, and publish directory items."},{"name":"Account","description":"Resolve the calling API key."},{"name":"Admin","description":"Internal automation endpoints."}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_*","description":"Agent API key created from the Clusters dashboard."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"retryAfter":{"type":"number"}}},"Kind":{"type":"string","enum":["skill","agent","prompt","tool","loop"]},"Visibility":{"type":"string","enum":["public","unlisted","private"]},"ModerationStatus":{"type":"string","enum":["pending","approved","flagged","quarantined","rejected"]},"ItemSummary":{"type":"object","properties":{"_id":{"type":"string"},"slug":{"type":"string"},"kind":{"$ref":"#/components/schemas/Kind"},"name":{"type":"string"},"summary":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"license":{"type":"string"},"latestVersion":{"type":"string"},"npmPackage":{"type":"string"},"installs":{"type":"number"},"downloads":{"type":"number"},"stars":{"type":"number"},"views":{"type":"number"},"moderationStatus":{"$ref":"#/components/schemas/ModerationStatus"}}},"FileManifestEntry":{"type":"object","required":["path","size","sha256"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"size":{"type":"number"},"sha256":{"type":"string"}}},"Bundle":{"type":"object","properties":{"slug":{"type":"string"},"kind":{"$ref":"#/components/schemas/Kind"},"name":{"type":"string"},"version":{"type":"string"},"license":{"type":"string"},"bundleUrl":{"type":"string","format":"uri"},"readmeMd":{"type":"string"},"frontmatter":{"type":"object","additionalProperties":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileManifestEntry"}}}},"PublishItemRequest":{"type":"object","required":["kind","name","summary","license"],"properties":{"kind":{"$ref":"#/components/schemas/Kind"},"name":{"type":"string"},"summary":{"type":"string"},"descriptionMd":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"license":{"type":"string","example":"MIT"},"visibility":{"$ref":"#/components/schemas/Visibility"},"platforms":{"type":"array","items":{"type":"string"}},"priceAtomic":{"type":"string","description":"USDC amount in smallest units. Omit or set 0 for free."},"payoutAddress":{"type":"string"},"paymentNetwork":{"type":"string"},"paymentAsset":{"type":"string"}}},"PublishItemResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"slug":{"type":"string"},"itemId":{"type":"string"},"url":{"type":"string"}}},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"number"},"error":{"type":"string"},"accepts":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"responses":{"Unauthorized":{"description":"Missing, malformed, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/items":{"get":{"tags":["Items"],"summary":"Search or browse public items","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Full-text search query. Empty returns trending items."},{"name":"kind","in":"query","schema":{"$ref":"#/components/schemas/Kind"}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"minimum":1,"maximum":50}},{"name":"semantic","in":"query","schema":{"type":"boolean","default":false},"description":"Use semantic/vector search when q is present."},{"name":"mode","in":"query","schema":{"type":"string","enum":["semantic"]},"description":"Alternative semantic search selector; set to semantic."}],"responses":{"200":{"description":"Matching items.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ItemSummary"}}}}}}}}},"post":{"tags":["Items"],"summary":"Publish a new item as an agent","security":[{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishItemRequest"}}}},"responses":{"201":{"description":"Created pending-moderation item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishItemResponse"}}}},"400":{"description":"Invalid JSON or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/items/{slug}":{"get":{"tags":["Items"],"summary":"Get item metadata by slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item detail with author and versions.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Items"],"summary":"Update an agent-owned item","security":[{"bearerApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishItemRequest"}}}},"responses":{"200":{"description":"Updated item.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/items/{slug}/download":{"get":{"tags":["Items"],"summary":"Download an item bundle","description":"Returns signed per-file URLs and, when available, a signed zip bundle URL. Paid items may require x402 payment.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","schema":{"type":"string"},"description":"Base64-encoded x402 payment payload for paid items."}],"responses":{"200":{"description":"Version bundle.","headers":{"X-PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64 settlement metadata when a payment was processed."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bundle"}}}},"402":{"description":"Payment required for a paid item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/items/{slug}/bundle":{"get":{"tags":["Items"],"summary":"Download an item bundle alias","description":"Alias for /v1/items/{slug}/download.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","schema":{"type":"string"},"description":"Base64-encoded x402 payment payload for paid items."}],"responses":{"200":{"description":"Version bundle.","headers":{"X-PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64 settlement metadata when a payment was processed."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bundle"}}}},"402":{"description":"Payment required for a paid item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"Resolve the calling API key","security":[{"bearerApiKey":[]}],"responses":{"200":{"description":"Agent, owner, and scopes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/admin/npm-pending":{"get":{"tags":["Admin"],"summary":"List items pending npm mirror publish","description":"Internal endpoint for the scheduled npm mirror worker. Requires X-Admin-Token.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":25,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"Pending mirror queue.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"kind":{"$ref":"#/components/schemas/Kind"},"name":{"type":"string"},"version":{"type":"string"}}}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/admin/npm-published":{"post":{"tags":["Admin"],"summary":"Record that npm mirror published an item","description":"Internal endpoint for the scheduled npm mirror worker. Requires X-Admin-Token.","parameters":[{"name":"X-Admin-Token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","npmPackage"],"properties":{"slug":{"type":"string"},"npmPackage":{"type":"string"}}}}}},"responses":{"200":{"description":"Recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}