{ "openapi": "3.1.0", "info": { "title": "dify-helm-watchdog API", "version": "1.0.0", "description": "API documentation generated from Next.js route handlers using next-swagger-doc." }, "servers": [ { "url": "https://helm-watchdog.langgenius.app" } ], "components": { "schemas": {}, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "paths": { "/api/v1/analytics": { "get": { "summary": "Aggregate analytics for MCP / API / Web traffic", "description": "Returns aggregated counts and unique-visitor estimates for the public\ndashboard. Backed by Cloudflare Analytics Engine.\n", "tags": [ "Analytics" ], "parameters": [ { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] }, "description": "Time window. Defaults to 7d." } ], "responses": { "200": { "description": "Aggregated analytics for the requested window." }, "502": { "description": "Upstream Cloudflare Worker query failed." } } } }, "/api/v1/cache": { "get": { "summary": "Inspect cached Helm metadata", "description": "Returns the full cache payload, including update timestamp and all tracked versions.", "tags": [ "Cache" ], "responses": { "200": { "description": "Cache contents in JSON format." } } } }, "/api/v1/cron": { "post": { "summary": "Trigger Helm cache synchronization", "description": "Starts the cron sync pipeline and streams textual progress logs. Requires Bearer token authentication when invoked outside the hosting platform.", "tags": [ "Cron" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "version", "in": "query", "required": false, "description": "One or more specific chart versions (comma separated) to refresh.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "pause", "in": "query", "required": false, "description": "Number of seconds to wait before starting the sync. Maximum is configurable via MAX_PAUSE_SECONDS env var (default 300). Heartbeat messages are sent every 10 seconds to keep the connection alive.", "schema": { "type": "integer", "minimum": 0, "example": 60 } } ], "responses": { "200": { "description": "Stream containing sync logs." }, "401": { "description": "Missing or invalid authorization token." }, "500": { "description": "Internal server error." } } } }, "/api/v1/mcp": { "get": { "summary": "Get MCP server information", "description": "Returns MCP server capabilities and version information. This endpoint is for discovery purposes.", "tags": [ "MCP" ], "responses": { "200": { "description": "Server information and capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocolVersion": { "type": "string" }, "serverInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "capabilities": { "type": "object" } } } } } } } }, "post": { "summary": "Send MCP message via Streamable HTTP", "description": "Processes JSON-RPC 2.0 messages according to the MCP protocol\n(2026-07-28 specification). Each request is self-contained; the\nserver keeps no protocol state between requests.\n\nAvailable methods:\n- `server/discover` - Stateless 2026-07-28 handshake: returns the\n supported protocol versions and capabilities (DiscoverResult)\n- `initialize` - Legacy handshake for 2025-11-25 and earlier clients\n- `ping` - Health check\n- `tools/list` - List available tools (includes cache hints)\n- `tools/call` - Execute a tool\n- `prompts/list` - List available prompt templates (includes cache hints)\n- `prompts/get` - Get a prompt template with arguments\n", "parameters": [ { "in": "header", "name": "Mcp-Method", "required": false, "schema": { "type": "string" }, "description": "Optional JSON-RPC method name hint used for analytics." } ], "tags": [ "MCP" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 request", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "method": { "type": "string", "example": "tools/list" }, "params": { "type": "object" } } }, "examples": { "discover": { "summary": "Discover server (2026-07-28 handshake)", "value": { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } }, "initialize": { "summary": "Initialize session (legacy handshake)", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "example-client", "version": "1.0.0" } } } }, "listTools": { "summary": "List available tools", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } }, "callTool": { "summary": "Call a tool", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_versions", "arguments": { "includeValidation": true } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "result": { "type": "object" }, "error": { "type": "object" } } } } } }, "204": { "description": "Notification processed (no response body)." }, "400": { "description": "Invalid request body." }, "500": { "description": "Internal server error." } } } }, "/api/v1/releases/{version}": { "get": { "summary": "Proxy release notes HTML from ee.dify.ai", "description": "Fetches the release notes page for a given version from ee.dify.ai, extracts the main content div, and returns sanitised HTML. If the page cannot be scraped, returns the release feed summary as a fallback.\n", "tags": [ "Releases" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "example": "3.9.0" } ], "responses": { "200": { "description": "Extracted release notes HTML." }, "400": { "description": "Invalid version format." }, "502": { "description": "Failed to fetch from upstream." } } } }, "/api/v1/releases/feed": { "get": { "summary": "Proxy release metadata from ee.dify.ai feed.json", "description": "Fetches the ee.dify.ai JSON Feed and returns parsed release metadata for UI badges and release-note fallbacks.\n", "tags": [ "Releases" ], "responses": { "200": { "description": "Parsed release feed entries." }, "502": { "description": "Failed to fetch from upstream." } } } }, "/api/v1/upgrade-path/options": { "get": { "summary": "List Dify Enterprise versions available for upgrade planning", "tags": [ "Releases" ], "responses": { "200": { "description": "Versions from the EE release catalog, newest first." }, "502": { "description": "Failed to fetch the upstream catalog." } } } }, "/api/v1/upgrade-path": { "get": { "summary": "Compute the Dify Enterprise upgrade path between two versions", "description": "Returns the ordered list of unskippable versions between the current and target Enterprise versions, derived from the ee.dify.ai release catalog. Each hop carries stop kinds, a one-line summary, release notes URL, and the versions.lock.yaml snapshot URL.\n", "tags": [ "Releases" ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Current version (with or without leading v, e.g. 3.9.5)" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Target version (with or without leading v)" } ], "responses": { "200": { "description": "Upgrade path with hops and notes." }, "400": { "description": "Missing/invalid parameters or from >= to." }, "404": { "description": "Unknown version." }, "502": { "description": "Failed to fetch the upstream catalog." } } } }, "/api/v1/versions/{version}/images": { "get": { "summary": "List images declared by a chart version", "description": "Returns container image references extracted from the Helm chart values file, optionally enriched with validation results. For versions >= 3.9.0, images built from Dify source also include source refs (repo, ref, ref_type, commit) from the enterprise release lock.", "tags": [ "Images" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Selects the response format, JSON by default.", "schema": { "type": "string", "enum": [ "json", "yaml" ], "default": "json" } }, { "name": "includeValidation", "in": "query", "description": "Whether to include validation information alongside each image.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Image list in JSON or YAML." }, "404": { "description": "Version or cache not available." }, "500": { "description": "Internal server error." } } } }, "/api/v1/versions/{version}": { "get": { "summary": "Get version details", "description": "Returns metadata and asset locations for a specific cached chart version.", "tags": [ "Versions" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The chart version metadata." }, "404": { "description": "Version not found in cache." }, "500": { "description": "Internal server error." } } } }, "/api/v1/versions/{version}/validation": { "get": { "summary": "Get validation report for a chart version", "description": "Returns normalized validation results for images defined in the specified Helm chart version.", "tags": [ "Validation" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "isMissing", "in": "query", "description": "When true, only returns images with status \"MISSING\".", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Validation payload in JSON format." }, "404": { "description": "Validation data or version not found." }, "500": { "description": "Internal server error." } } } }, "/api/v1/versions/{version}/values": { "get": { "summary": "Download chart values file", "description": "Streams the cached values.yaml file for the requested chart version.", "tags": [ "Values" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "YAML document containing chart values." }, "404": { "description": "Version or cache not available." }, "500": { "description": "Internal server error." } } } }, "/api/v1/versions/latest": { "get": { "summary": "Resolve the most recent chart version", "description": "Returns convenience links to the most recent cached chart version and its related resources.", "tags": [ "Versions" ], "parameters": [ { "name": "versionOnly", "in": "query", "description": "When true, returns only the version string as plain text instead of the full JSON response.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Metadata about the latest chart version (JSON) or version string (plain text if versionOnly=true)." }, "404": { "description": "No cached versions available." }, "500": { "description": "Internal server error." } } } }, "/api/v1/versions": { "get": { "summary": "List available Helm chart versions", "description": "Returns a paginated collection of cached chart versions with optional aggregated validation statistics.", "tags": [ "Versions" ], "parameters": [ { "name": "includeValidation", "in": "query", "description": "Whether to include image validation summary in the response.", "schema": { "type": "boolean" } }, { "name": "include_validation", "in": "query", "description": "Deprecated alias of includeValidation.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A JSON payload containing chart versions." }, "500": { "description": "Internal server error." } } } } }, "tags": [] }