{
  "openapi": "3.1.0",
  "info": {
    "title": "Watermelon UI Public API",
    "version": "1.0.0",
    "description": "Public machine-readable endpoints exposed by Watermelon UI for discovery and catalog lookup. Canonical endpoints are versioned under /api/v1/. Unversioned /api/* routes are compatibility aliases and will emit Deprecation and Sunset headers before retirement."
  },
  "servers": [
    {
      "url": "https://ui.watermelon.sh"
    },
    {
      "url": "https://ui.watermelon.sh/api/v1",
      "description": "Canonical versioned API base"
    }
  ],
  "paths": {
    "/api/v1/catalog/summary": {
      "get": {
        "operationId": "getCatalogSummaryV1",
        "summary": "Get Watermelon catalog summary",
        "description": "Canonical v1 endpoint. Returns top-level counts for animated components, blocks, dashboards, templates, and showcases.",
        "responses": {
          "200": {
            "description": "Catalog summary returned successfully.",
            "headers": {
              "RateLimit-Limit": {
                "schema": { "type": "string" },
                "description": "Request quota for the current window."
              },
              "RateLimit-Remaining": {
                "schema": { "type": "string" },
                "description": "Remaining requests in the current window."
              },
              "RateLimit-Reset": {
                "schema": { "type": "string" },
                "description": "Seconds until the current quota window resets."
              },
              "RateLimit-Policy": {
                "schema": { "type": "string" },
                "description": "Applied rate-limit policy, for example 120;w=60."
              },
              "X-API-Version": {
                "schema": { "type": "string" },
                "description": "Resolved API version."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog/summary": {
      "get": {
        "operationId": "getCatalogSummary",
        "summary": "Get Watermelon catalog summary",
        "description": "Compatibility alias for /api/v1/catalog/summary. Returns top-level counts for animated components, blocks, dashboards, templates, and showcases.",
        "responses": {
          "200": {
            "description": "Catalog summary returned successfully.",
            "headers": {
              "Deprecation": {
                "schema": { "type": "string" },
                "description": "Present on compatibility aliases before retirement."
              },
              "Sunset": {
                "schema": { "type": "string" },
                "description": "RFC 7231 HTTP-date indicating the planned retirement date for the compatibility alias."
              },
              "RateLimit-Limit": {
                "schema": { "type": "string" }
              },
              "RateLimit-Remaining": {
                "schema": { "type": "string" }
              },
              "RateLimit-Reset": {
                "schema": { "type": "string" }
              },
              "RateLimit-Policy": {
                "schema": { "type": "string" }
              },
              "X-API-Version": {
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/catalog/entries": {
      "get": {
        "operationId": "listCatalogEntriesV1",
        "summary": "List Watermelon catalog entries",
        "description": "Canonical v1 endpoint. Lists public Watermelon catalog entries for one content kind, with optional category and query filtering.",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": true,
            "description": "The catalog kind to query.",
            "schema": {
              "$ref": "#/components/schemas/CatalogKind"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional category filter for matching entries.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Optional free-text query matched against title, slug, description, and category.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog entries returned successfully.",
            "headers": {
              "RateLimit-Limit": {
                "schema": { "type": "string" }
              },
              "RateLimit-Remaining": {
                "schema": { "type": "string" }
              },
              "RateLimit-Reset": {
                "schema": { "type": "string" }
              },
              "RateLimit-Policy": {
                "schema": { "type": "string" }
              },
              "X-API-Version": {
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogEntriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog/entries": {
      "get": {
        "operationId": "listCatalogEntries",
        "summary": "List Watermelon catalog entries",
        "description": "Compatibility alias for /api/v1/catalog/entries. Lists public Watermelon catalog entries for one content kind, with optional category and query filtering.",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": true,
            "description": "The catalog kind to query.",
            "schema": {
              "$ref": "#/components/schemas/CatalogKind"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional category filter for matching entries.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Optional free-text query matched against title, slug, description, and category.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog entries returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogEntriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/catalog/entries/{kind}/{slug}": {
      "get": {
        "operationId": "getCatalogEntryV1",
        "summary": "Get one Watermelon catalog entry",
        "description": "Canonical v1 endpoint. Returns one catalog entry by kind and slug.",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "description": "The catalog kind.",
            "schema": {
              "$ref": "#/components/schemas/CatalogKind"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The entry slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog entry returned successfully.",
            "headers": {
              "RateLimit-Limit": {
                "schema": { "type": "string" }
              },
              "RateLimit-Remaining": {
                "schema": { "type": "string" }
              },
              "RateLimit-Reset": {
                "schema": { "type": "string" }
              },
              "RateLimit-Policy": {
                "schema": { "type": "string" }
              },
              "X-API-Version": {
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogEntryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid kind or missing slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Entry not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog/entries/{kind}/{slug}": {
      "get": {
        "operationId": "getCatalogEntry",
        "summary": "Get one Watermelon catalog entry",
        "description": "Compatibility alias for /api/v1/catalog/entries/{kind}/{slug}. Returns one catalog entry by kind and slug.",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "description": "The catalog kind.",
            "schema": {
              "$ref": "#/components/schemas/CatalogKind"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The entry slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog entry returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogEntryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid kind or missing slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Entry not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "operationId": "getApiDocsIndex",
        "summary": "Get API docs index",
        "description": "Returns a small discovery document with the main Watermelon public API endpoints, canonical versioning path, and compatibility policy.",
        "responses": {
          "200": {
            "description": "API docs index returned successfully.",
            "headers": {
              "Deprecation": {
                "schema": { "type": "string" },
                "description": "Present on compatibility aliases before retirement."
              },
              "Sunset": {
                "schema": { "type": "string" },
                "description": "RFC 7231 HTTP-date indicating the planned retirement date for the compatibility alias."
              },
              "RateLimit-Limit": {
                "schema": { "type": "string" }
              },
              "RateLimit-Remaining": {
                "schema": { "type": "string" }
              },
              "RateLimit-Reset": {
                "schema": { "type": "string" }
              },
              "RateLimit-Policy": {
                "schema": { "type": "string" }
              },
              "X-API-Version": {
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiDocsIndexResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CatalogKind": {
        "type": "string",
        "enum": [
          "animated-components",
          "blocks",
          "dashboards",
          "templates",
          "showcases"
        ]
      },
      "CatalogEntry": {
        "type": "object",
        "properties": {
          "kind": {
            "$ref": "#/components/schemas/CatalogKind"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "image": {
            "type": "string",
            "format": "uri"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "kind",
          "title",
          "slug",
          "description",
          "path"
        ]
      },
      "CatalogSummaryResponse": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string"
          },
          "totalEntries": {
            "type": "integer"
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          }
        },
        "required": [
          "product",
          "totalEntries",
          "counts"
        ]
      },
      "CatalogEntriesResponse": {
        "type": "object",
        "properties": {
          "kind": {
            "$ref": "#/components/schemas/CatalogKind"
          },
          "category": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            }
          }
        },
        "required": [
          "kind",
          "limit",
          "count",
          "entries"
        ]
      },
      "CatalogEntryResponse": {
        "type": "object",
        "properties": {
          "found": {
            "type": "boolean"
          },
          "entry": {
            "$ref": "#/components/schemas/CatalogEntry"
          }
        },
        "required": [
          "found",
          "entry"
        ]
      },
      "ApiDocsIndexResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "canonicalBase": {
            "type": "string",
            "format": "uri"
          },
          "compatibilityAliases": {
            "type": "boolean"
          },
          "deprecationPolicy": {
            "type": "string"
          },
          "auth": {
            "$ref": "#/components/schemas/PublicAuthSummary"
          },
          "resources": {
            "$ref": "#/components/schemas/ApiDocsResources"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "version",
          "canonicalBase",
          "compatibilityAliases",
          "deprecationPolicy",
          "auth",
          "resources",
          "openapi",
          "endpoints"
        ]
      },
      "PublicAuthSummary": {
        "type": "object",
        "properties": {
          "required": {
            "type": "boolean"
          },
          "mode": {
            "type": "string",
            "enum": ["none"]
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "required",
          "mode",
          "docs"
        ]
      },
      "ApiDocsResources": {
        "type": "object",
        "properties": {
          "developers": {
            "type": "string",
            "format": "uri"
          },
          "authDocs": {
            "type": "string",
            "format": "uri"
          },
          "mcpDocs": {
            "type": "string",
            "format": "uri"
          },
          "mcpServer": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "developers",
          "authDocs",
          "mcpDocs",
          "mcpServer"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          }
        },
        "required": [
          "error",
          "message",
          "hint",
          "status"
        ]
      }
    }
  }
}