{ "openapi": "3.0.3", "info": { "title": "OpenCoWork API", "version": "v1", "description": "REST API for the OpenCoWork hub — MCP servers, Skills, Agents and Souls.\n\n- Catalog reads are public; write endpoints need an API key sent as `Authorization: Bearer ock_...` (create one in Console → API Keys).\n- API-key requests share a per-account daily quota; responses carry `X-RateLimit-Limit` / `X-RateLimit-Remaining`, and 429 is returned once exhausted (resets 00:00 UTC).\n- Errors are RFC 7807 problem details; `title` holds a stable error code such as `Mcp.NotFound`.\n- JSON uses camelCase; null-valued properties are omitted." }, "servers": [ { "url": "/", "description": "Your OpenCoWork deployment origin" } ], "tags": [ { "name": "MCP" }, { "name": "Skills" }, { "name": "Agents" }, { "name": "Souls" }, { "name": "Telemetry" }, { "name": "Auth" }, { "name": "ApiKeys" }, { "name": "Publisher", "description": "Requires the Publisher role" }, { "name": "Meta" } ], "paths": { "/health": { "get": { "tags": [ "Meta" ], "summary": "Liveness probe", "responses": { "200": { "description": "ok", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/v1/github/stars": { "get": { "tags": [ "Meta" ], "summary": "Cached GitHub star count", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubStarsResponse" } } } } } } }, "/api/v1/telemetry": { "post": { "tags": [ "Telemetry" ], "summary": "Record a view / install / usage / favorite event", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAck" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Anonymous. clientId (or the caller IP when omitted) is stored only as a truncated SHA-256 hash for deduplication.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReportRequest" } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Password login (admin-provisioned accounts)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } } } }, "/api/v1/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Current principal — use to verify an API key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Auth" ], "summary": "Update display name", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/auth/me/password": { "post": { "tags": [ "Auth" ], "summary": "Change password for the current account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys": { "get": { "tags": [ "ApiKeys" ], "summary": "List keys of the current account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "ApiKeys" ], "summary": "Create a key (full token returned once)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys/usage": { "get": { "tags": [ "ApiKeys" ], "summary": "Daily usage vs. quota", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUsage" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer" }, "required": false } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys/quota-requests": { "post": { "tags": [ "ApiKeys" ], "summary": "Request a higher daily quota", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaRequest" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuotaRequestRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys/quota-requests/mine": { "get": { "tags": [ "ApiKeys" ], "summary": "Latest quota request of the current account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaRequest" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys/{keyId}/enable": { "post": { "tags": [ "ApiKeys" ], "summary": "Enable a key", "responses": { "200": { "description": "Enabled" }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "keyId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys/{keyId}/disable": { "post": { "tags": [ "ApiKeys" ], "summary": "Disable a key", "responses": { "200": { "description": "Disabled" }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "keyId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/api-keys/{keyId}": { "delete": { "tags": [ "ApiKeys" ], "summary": "Delete a key", "responses": { "200": { "description": "Deleted" }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "keyId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/mcp": { "get": { "tags": [ "MCP" ], "summary": "Search and list published MCP", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpSummaryPage" } } } } }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Full-text search" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Category slug" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Tag slug" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "official", "user" ] }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "popular", "mostusage", "rating", "featured", "latest" ] }, "required": false, "description": "Default: newest by publish date" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false } ] } }, "/api/v1/mcp/categories": { "get": { "tags": [ "MCP" ], "summary": "List MCP categories with published-item counts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpCategory" } } } } } } } }, "/api/v1/mcp/{slug}": { "get": { "tags": [ "MCP" ], "summary": "Get one Mcp by slug", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/mcp/{slug}/versions": { "get": { "tags": [ "MCP" ], "summary": "List version history", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpVersionSummary" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/mcp/{slug}/versions/{version}": { "get": { "tags": [ "MCP" ], "summary": "Get one version in full detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpVersionDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" }, { "name": "version", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Version string, e.g. 1.2.0" } ] } }, "/api/v1/mcp/{slug}/report": { "post": { "tags": [ "MCP" ], "summary": "Report a published item", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReportRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/mine": { "get": { "tags": [ "Publisher" ], "summary": "List your MCP", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/McpMineItem" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/{mcpId}": { "get": { "tags": [ "Publisher" ], "summary": "Get your Mcp draft detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDraftDetail" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "mcpId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/drafts": { "post": { "tags": [ "Publisher" ], "summary": "Create a Mcp draft with its first version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMcpDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/{mcpId}/draft": { "put": { "tags": [ "Publisher" ], "summary": "Update draft metadata", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "mcpId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/{mcpId}/versions": { "post": { "tags": [ "Publisher" ], "summary": "Add a new version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "mcpId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpVersionInput" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/{mcpId}/submit-review": { "post": { "tags": [ "Publisher" ], "summary": "Submit the draft for review", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "mcpId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/mcp/{mcpId}/withdraw": { "post": { "tags": [ "Publisher" ], "summary": "Withdraw a pending submission", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "mcpId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/skill": { "get": { "tags": [ "Skills" ], "summary": "Search and list published Skills", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillSummaryPage" } } } } }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Full-text search" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Category slug" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Tag slug" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "official", "user" ] }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "popular", "mostusage", "rating", "featured", "latest" ] }, "required": false, "description": "Default: newest by publish date" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false } ] } }, "/api/v1/skill/categories": { "get": { "tags": [ "Skills" ], "summary": "List Skills categories with published-item counts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillCategory" } } } } } } } }, "/api/v1/skill/{slug}": { "get": { "tags": [ "Skills" ], "summary": "Get one Skill by slug", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/skill/{slug}/versions": { "get": { "tags": [ "Skills" ], "summary": "List version history", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillVersionSummary" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/skill/{slug}/versions/{version}": { "get": { "tags": [ "Skills" ], "summary": "Get one version in full detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" }, { "name": "version", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Version string, e.g. 1.2.0" } ] } }, "/api/v1/skill/{slug}/report": { "post": { "tags": [ "Skills" ], "summary": "Report a published item", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReportRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/mine": { "get": { "tags": [ "Publisher" ], "summary": "List your Skills", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillMineItem" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/{skillId}": { "get": { "tags": [ "Publisher" ], "summary": "Get your Skill draft detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDraftDetail" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "skillId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/drafts": { "post": { "tags": [ "Publisher" ], "summary": "Create a Skill draft with its first version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/{skillId}/draft": { "put": { "tags": [ "Publisher" ], "summary": "Update draft metadata", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "skillId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/{skillId}/versions": { "post": { "tags": [ "Publisher" ], "summary": "Add a new version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "skillId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionInput" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/{skillId}/submit-review": { "post": { "tags": [ "Publisher" ], "summary": "Submit the draft for review", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "skillId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/{skillId}/withdraw": { "post": { "tags": [ "Publisher" ], "summary": "Withdraw a pending submission", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "skillId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/agent": { "get": { "tags": [ "Agents" ], "summary": "Search and list published Agents", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSummaryPage" } } } } }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Full-text search" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Category slug" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Tag slug" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "official", "user" ] }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "popular", "mostusage", "rating", "featured", "latest" ] }, "required": false, "description": "Default: newest by publish date" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false } ] } }, "/api/v1/agent/categories": { "get": { "tags": [ "Agents" ], "summary": "List Agents categories with published-item counts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCategory" } } } } } } } }, "/api/v1/agent/{slug}": { "get": { "tags": [ "Agents" ], "summary": "Get one Agent by slug", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/agent/{slug}/versions": { "get": { "tags": [ "Agents" ], "summary": "List version history", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersionSummary" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/agent/{slug}/versions/{version}": { "get": { "tags": [ "Agents" ], "summary": "Get one version in full detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersionDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" }, { "name": "version", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Version string, e.g. 1.2.0" } ] } }, "/api/v1/agent/{slug}/report": { "post": { "tags": [ "Agents" ], "summary": "Report a published item", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReportRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/mine": { "get": { "tags": [ "Publisher" ], "summary": "List your Agents", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMineItem" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/{agentId}": { "get": { "tags": [ "Publisher" ], "summary": "Get your Agent draft detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDraftDetail" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/drafts": { "post": { "tags": [ "Publisher" ], "summary": "Create a Agent draft with its first version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/{agentId}/draft": { "put": { "tags": [ "Publisher" ], "summary": "Update draft metadata", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/{agentId}/versions": { "post": { "tags": [ "Publisher" ], "summary": "Add a new version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersionInput" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/{agentId}/submit-review": { "post": { "tags": [ "Publisher" ], "summary": "Submit the draft for review", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/agent/{agentId}/withdraw": { "post": { "tags": [ "Publisher" ], "summary": "Withdraw a pending submission", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/soul": { "get": { "tags": [ "Souls" ], "summary": "Search and list published Souls", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulSummaryPage" } } } } }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Full-text search" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Category slug" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Tag slug" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "official", "user" ] }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "popular", "mostusage", "rating", "featured", "latest" ] }, "required": false, "description": "Default: newest by publish date" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false } ] } }, "/api/v1/soul/categories": { "get": { "tags": [ "Souls" ], "summary": "List Souls categories with published-item counts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SoulCategory" } } } } } } } }, "/api/v1/soul/{slug}": { "get": { "tags": [ "Souls" ], "summary": "Get one Soul by slug", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/soul/{slug}/prompt.txt": { "get": { "tags": [ "Souls" ], "summary": "Persona prompt as plain text (AI-consumable)", "responses": { "200": { "description": "The persona system prompt", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "One-request persona adoption for AI agents: returns the published version's SOUL.md document (falls back to the description). Also served by the web app at /soul/{slug}/prompt.txt.", "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/soul/{slug}/versions": { "get": { "tags": [ "Souls" ], "summary": "List version history", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SoulVersionSummary" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ] } }, "/api/v1/soul/{slug}/versions/{version}": { "get": { "tags": [ "Souls" ], "summary": "Get one version in full detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulVersionDetail" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" }, { "name": "version", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Version string, e.g. 1.2.0" } ] } }, "/api/v1/soul/{slug}/report": { "post": { "tags": [ "Souls" ], "summary": "Report a published item", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "slug", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Item slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReportRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/mine": { "get": { "tags": [ "Publisher" ], "summary": "List your Souls", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SoulMineItem" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/{soulId}": { "get": { "tags": [ "Publisher" ], "summary": "Get your Soul draft detail", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulDraftDetail" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "soulId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/drafts": { "post": { "tags": [ "Publisher" ], "summary": "Create a Soul draft with its first version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSoulDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/{soulId}/draft": { "put": { "tags": [ "Publisher" ], "summary": "Update draft metadata", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "soulId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSoulDraftRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/{soulId}/versions": { "post": { "tags": [ "Publisher" ], "summary": "Add a new version", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "soulId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulVersionInput" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/{soulId}/submit-review": { "post": { "tags": [ "Publisher" ], "summary": "Submit the draft for review", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulMutationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "soulId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewRequest" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/soul/{soulId}/withdraw": { "post": { "tags": [ "Publisher" ], "summary": "Withdraw a pending submission", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulMutationResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "parameters": [ { "name": "soulId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/publisher/skill/{skillId}/versions/{versionId}/package": { "post": { "tags": [ "Publisher" ], "summary": "Upload a Skill package (.zip)", "description": "Skill only. multipart/form-data with a single `file` field. SKILL.md inside the bundle is parsed at submit time.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "skillId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "versionId", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Package accepted" }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Daily API-key quota exhausted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string", "description": "Stable dot-separated error code, e.g. Mcp.NotFound" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "description": "RFC 7807 problem details. Match on `title` (the error code)." }, "McpConnection": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string", "nullable": true }, "isPrimary": { "type": "boolean" }, "runtime": { "type": "string", "nullable": true }, "command": { "type": "string", "nullable": true }, "args": { "type": "array", "items": { "type": "string" } }, "packageName": { "type": "string", "nullable": true }, "packageVersion": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "authType": { "type": "string" } } }, "McpTool": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "inputSchemaJson": { "type": "string", "description": "Raw JSON Schema string" }, "isReadOnly": { "type": "boolean" }, "isDestructive": { "type": "boolean" } } }, "McpResource": { "type": "object", "properties": { "uriTemplate": { "type": "string" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true } } }, "McpPrompt": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "argumentsJson": { "type": "string", "nullable": true } } }, "McpConfigField": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "isSecret": { "type": "boolean" }, "valueType": { "type": "string" }, "enumValues": { "type": "array", "items": { "type": "string" } }, "defaultValue": { "type": "string", "nullable": true }, "example": { "type": "string", "nullable": true }, "docsUrl": { "type": "string", "nullable": true } } }, "McpPermission": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "fs", "network", "shell", "env" ] }, "note": { "type": "string", "nullable": true } } }, "SkillBundleFile": { "type": "object", "properties": { "path": { "type": "string" }, "kind": { "type": "string" }, "language": { "type": "string", "nullable": true }, "sizeBytes": { "type": "integer", "format": "int64" }, "isExecutable": { "type": "boolean" } } }, "SkillDependency": { "type": "object", "properties": { "depType": { "type": "string" }, "name": { "type": "string" }, "versionConstraint": { "type": "string", "nullable": true } } }, "SkillExample": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "prompt": { "type": "string", "nullable": true }, "expectedOutcome": { "type": "string", "nullable": true } } }, "SkillParameter": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "valueType": { "type": "string" } } }, "McpSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string", "enum": [ "official", "user" ] }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "installCount": { "type": "integer", "format": "int64" }, "viewCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category slugs" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "primaryTransport": { "type": "string", "nullable": true }, "toolCount": { "type": "integer" } } }, "McpSummaryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/McpSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer", "format": "int64" }, "hasNext": { "type": "boolean" } } }, "McpCategory": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer", "format": "int64" } } }, "McpStats": { "type": "object", "properties": { "viewCount": { "type": "integer", "format": "int64" }, "installCount": { "type": "integer", "format": "int64" }, "usageCount": { "type": "integer", "format": "int64" }, "favoriteCount": { "type": "integer", "format": "int64" }, "ratingCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true } } }, "McpVersionSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "McpVersionDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "primaryTransport": { "type": "string", "nullable": true }, "toolCount": { "type": "integer" }, "resourceCount": { "type": "integer" }, "promptCount": { "type": "integer" }, "supportsSampling": { "type": "boolean" }, "supportsRoots": { "type": "boolean" }, "requiresAuth": { "type": "boolean" }, "requiresSecrets": { "type": "boolean" }, "mcpScore": { "type": "integer", "nullable": true }, "repositoryUrl": { "type": "string", "nullable": true }, "supportedClients": { "type": "array", "items": { "type": "string" } }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/McpConnection" } }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpTool" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/McpResource" } }, "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/McpPrompt" } }, "configFields": { "type": "array", "items": { "$ref": "#/components/schemas/McpConfigField" } }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/McpPermission" } } } }, "McpDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string" }, "visibility": { "type": "string" }, "status": { "type": "string" }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/McpStats" }, "currentVersion": { "$ref": "#/components/schemas/McpVersionDetail", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "McpMineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "installCount": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "McpDraftDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" } } }, "McpMutationResponse": { "type": "object", "properties": { "mcpId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" } } }, "SkillSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string", "enum": [ "official", "user" ] }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "installCount": { "type": "integer", "format": "int64" }, "viewCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category slugs" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "executesCode": { "type": "boolean" } } }, "SkillSummaryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SkillSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer", "format": "int64" }, "hasNext": { "type": "boolean" } } }, "SkillCategory": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer", "format": "int64" } } }, "SkillStats": { "type": "object", "properties": { "viewCount": { "type": "integer", "format": "int64" }, "installCount": { "type": "integer", "format": "int64" }, "usageCount": { "type": "integer", "format": "int64" }, "favoriteCount": { "type": "integer", "format": "int64" }, "ratingCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true } } }, "SkillVersionSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SkillVersionDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "skillName": { "type": "string", "nullable": true }, "triggerSummary": { "type": "string", "nullable": true }, "allowedTools": { "type": "array", "items": { "type": "string" } }, "supportedClients": { "type": "array", "items": { "type": "string" } }, "executesCode": { "type": "boolean" }, "hasScripts": { "type": "boolean" }, "fileCount": { "type": "integer" }, "bundleFiles": { "type": "array", "items": { "$ref": "#/components/schemas/SkillBundleFile" } }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/SkillDependency" } }, "examples": { "type": "array", "items": { "$ref": "#/components/schemas/SkillExample" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/SkillParameter" } } } }, "SkillDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string" }, "visibility": { "type": "string" }, "status": { "type": "string" }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/SkillStats" }, "currentVersion": { "$ref": "#/components/schemas/SkillVersionDetail", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SkillMineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "installCount": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SkillDraftDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" } } }, "SkillMutationResponse": { "type": "object", "properties": { "skillId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" } } }, "AgentSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string", "enum": [ "official", "user" ] }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "installCount": { "type": "integer", "format": "int64" }, "viewCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category slugs" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "AgentSummaryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer", "format": "int64" }, "hasNext": { "type": "boolean" } } }, "AgentCategory": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer", "format": "int64" } } }, "AgentStats": { "type": "object", "properties": { "viewCount": { "type": "integer", "format": "int64" }, "installCount": { "type": "integer", "format": "int64" }, "usageCount": { "type": "integer", "format": "int64" }, "favoriteCount": { "type": "integer", "format": "int64" }, "ratingCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true } } }, "AgentVersionSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "AgentVersionDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "AgentDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string" }, "visibility": { "type": "string" }, "status": { "type": "string" }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/AgentStats" }, "currentVersion": { "$ref": "#/components/schemas/AgentVersionDetail", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "AgentMineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "installCount": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AgentDraftDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" } } }, "AgentMutationResponse": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" } } }, "SoulSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string", "enum": [ "official", "user" ] }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "installCount": { "type": "integer", "format": "int64" }, "viewCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category slugs" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SoulSummaryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SoulSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer", "format": "int64" }, "hasNext": { "type": "boolean" } } }, "SoulCategory": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer", "format": "int64" } } }, "SoulStats": { "type": "object", "properties": { "viewCount": { "type": "integer", "format": "int64" }, "installCount": { "type": "integer", "format": "int64" }, "usageCount": { "type": "integer", "format": "int64" }, "favoriteCount": { "type": "integer", "format": "int64" }, "ratingCount": { "type": "integer", "format": "int64" }, "ratingAverage": { "type": "number", "nullable": true } } }, "SoulVersionSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SoulVersionDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SoulDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherName": { "type": "string" }, "source": { "type": "string" }, "visibility": { "type": "string" }, "status": { "type": "string" }, "isOfficial": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/SoulStats" }, "currentVersion": { "$ref": "#/components/schemas/SoulVersionDetail", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SoulMineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "installCount": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SoulDraftDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" } } }, "SoulMutationResponse": { "type": "object", "properties": { "soulId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" } } }, "McpVersionInput": { "type": "object", "properties": { "version": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true }, "repositoryUrl": { "type": "string", "nullable": true }, "supportedClients": { "type": "array", "items": { "type": "string" } }, "supportsSampling": { "type": "boolean" }, "supportsRoots": { "type": "boolean" }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/McpConnection" } }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpTool" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/McpResource" } }, "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/McpPrompt" } }, "configFields": { "type": "array", "items": { "$ref": "#/components/schemas/McpConfigField" } }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/McpPermission" } } }, "required": [ "version" ] }, "CreateMcpDraftRequest": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherSlug": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "$ref": "#/components/schemas/McpVersionInput" } }, "required": [ "slug", "name", "summary", "description", "publisherSlug", "version" ] }, "UpdateMcpDraftRequest": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "summary", "description" ] }, "SkillVersionInput": { "type": "object", "properties": { "version": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/SkillDependency" } }, "examples": { "type": "array", "items": { "$ref": "#/components/schemas/SkillExample" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/SkillParameter" } } }, "required": [ "version" ] }, "CreateSkillDraftRequest": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherSlug": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "$ref": "#/components/schemas/SkillVersionInput" } }, "required": [ "slug", "name", "summary", "description", "publisherSlug", "version" ] }, "UpdateSkillDraftRequest": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "summary", "description" ] }, "AgentVersionInput": { "type": "object", "properties": { "version": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true } }, "required": [ "version" ] }, "CreateAgentDraftRequest": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherSlug": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "$ref": "#/components/schemas/AgentVersionInput" } }, "required": [ "slug", "name", "summary", "description", "publisherSlug", "version" ] }, "UpdateAgentDraftRequest": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "summary", "description" ] }, "SoulVersionInput": { "type": "object", "properties": { "version": { "type": "string" }, "changelog": { "type": "string", "nullable": true }, "readme": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "packageUrl": { "type": "string", "nullable": true }, "checksum": { "type": "string", "nullable": true } }, "required": [ "version" ] }, "CreateSoulDraftRequest": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "publisherSlug": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "version": { "$ref": "#/components/schemas/SoulVersionInput" } }, "required": [ "slug", "name", "summary", "description", "publisherSlug", "version" ] }, "UpdateSoulDraftRequest": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "summary", "description" ] }, "SubmitReportRequest": { "type": "object", "properties": { "reason": { "type": "string" }, "detail": { "type": "string", "nullable": true } }, "required": [ "reason" ] }, "ReportMutationResponse": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "caseId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" } } }, "SubmitReviewRequest": { "type": "object", "properties": { "comment": { "type": "string", "nullable": true } } }, "UsageReportRequest": { "type": "object", "properties": { "itemType": { "type": "string", "enum": [ "mcp", "skill", "agent", "soul" ] }, "slug": { "type": "string" }, "versionId": { "type": "string", "format": "uuid", "nullable": true }, "eventType": { "type": "string", "enum": [ "view", "install", "usage", "favorite" ], "description": "install = a download; usage = a real invocation" }, "toolName": { "type": "string", "nullable": true }, "clientId": { "type": "string", "nullable": true, "description": "Stable opaque device id; only a truncated SHA-256 is stored" } }, "required": [ "itemType", "slug", "eventType" ] }, "UsageAck": { "type": "object", "properties": { "recorded": { "type": "boolean" } } }, "LoginRequest": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "username", "password" ] }, "Me": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "avatarUrl": { "type": "string", "nullable": true }, "roles": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "isAdmin": { "type": "boolean" } } }, "AuthTokenResponse": { "type": "object", "properties": { "accessToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "user": { "$ref": "#/components/schemas/Me" } } }, "UpdateProfileRequest": { "type": "object", "properties": { "displayName": { "type": "string" } }, "required": [ "displayName" ] }, "ChangePasswordRequest": { "type": "object", "properties": { "currentPassword": { "type": "string" }, "newPassword": { "type": "string" } }, "required": [ "currentPassword", "newPassword" ] }, "ChangePasswordResponse": { "type": "object", "properties": { "changed": { "type": "boolean" } }, "required": [ "changed" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First 12 chars of the token, for display" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "usedToday": { "type": "integer", "format": "int64" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ApiKeyCreated": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "token": { "type": "string", "description": "Full ock_ token — shown only once" } } }, "DailyCount": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "count": { "type": "integer", "format": "int64" } } }, "ApiKeyUsage": { "type": "object", "properties": { "usedToday": { "type": "integer", "format": "int64" }, "dailyQuota": { "type": "integer" }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/DailyCount" } } } }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "CreateQuotaRequestRequest": { "type": "object", "properties": { "requestedQuota": { "type": "integer", "maximum": 1000000 }, "reason": { "type": "string", "nullable": true } }, "required": [ "requestedQuota" ] }, "QuotaRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "currentQuota": { "type": "integer" }, "requestedQuota": { "type": "integer" }, "reason": { "type": "string", "nullable": true }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "decidedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "GithubStarsResponse": { "type": "object", "properties": { "stars": { "type": "integer", "format": "int64" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key token (ock_...) or a console JWT" } } } }