{
  "openapi": "3.1.0",
  "info": {
    "title": "Hover website content API",
    "version": "1.0.0",
    "summary": "Read-only, unauthenticated endpoints for Hover and Tag documentation content.",
    "description": "Hover (https://www.hover.team) publishes its website and Tag documentation as static files. These endpoints let agents discover pages, read documentation as Markdown, and search the docs index. There is no write API and no authentication. Unknown paths return HTTP 404; clients that send `Accept: text/markdown` receive a Markdown error body, and paths under `/api/` return a JSON `Error` body.",
    "contact": { "name": "Klovr Sdn. Bhd.", "email": "team@klovr.co", "url": "https://www.hover.team/" }
  },
  "servers": [{ "url": "https://www.hover.team" }],
  "externalDocs": { "description": "Tag documentation", "url": "https://www.hover.team/tag/" },
  "paths": {
    "/": {
      "get": {
        "operationId": "getHomepage",
        "summary": "Get the Hover homepage",
        "description": "Returns the homepage as HTML by default, or as Markdown when the request prefers `text/markdown` in its Accept header. Responses vary on Accept.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Send `text/markdown` to receive Markdown.",
            "schema": { "type": "string", "examples": ["text/markdown", "text/html"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Homepage content.",
            "headers": { "Vary": { "description": "Always includes Accept.", "schema": { "type": "string" } } },
            "content": {
              "text/markdown": { "schema": { "type": "string" } },
              "text/html": { "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsIndex",
        "summary": "Get the site-wide LLM index",
        "description": "Returns an llms.txt index (https://llmstxt.org) listing site pages, Tag documentation pages, versions, and when-to-use guidance for agents.",
        "responses": {
          "200": { "description": "The llms.txt index.", "content": { "text/plain": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getLlmsFullText",
        "summary": "Get the complete stable Tag documentation",
        "description": "Returns every page of the latest stable Tag documentation concatenated as Markdown.",
        "responses": {
          "200": { "description": "Complete documentation text.", "content": { "text/plain": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/tag/{page}.md": {
      "get": {
        "operationId": "getStableTagDocPage",
        "summary": "Get one current stable Tag documentation page as Markdown",
        "description": "Returns a page from the latest stable Tag guide as Markdown with absolute links. Use `/llms.txt` to discover valid page values.",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "Page slug, such as `getting-started`, `capabilities`, or `troubleshooting`.",
            "schema": { "type": "string", "examples": ["getting-started"] }
          }
        ],
        "responses": {
          "200": { "description": "Markdown page.", "content": { "text/markdown": { "schema": { "type": "string" } } } },
          "404": { "description": "Unknown page.", "content": { "text/markdown": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/tag/{version}/{page}.md": {
      "get": {
        "operationId": "getVersionedTagDocPage",
        "summary": "Get a numbered release or development Tag documentation page as Markdown",
        "description": "Returns a page from a named guide as Markdown with absolute links. The latest stable guide uses `/tag/{page}.md` instead.",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "description": "Documentation version slug, such as `development` for unreleased docs or a numbered older release.",
            "schema": { "type": "string", "examples": ["development"] }
          },
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "Page slug, such as `getting-started`, `capabilities`, or `troubleshooting`.",
            "schema": { "type": "string", "examples": ["getting-started"] }
          }
        ],
        "responses": {
          "200": { "description": "Markdown page.", "content": { "text/markdown": { "schema": { "type": "string" } } } },
          "404": { "description": "Unknown version or page.", "content": { "text/markdown": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/tag/api/search": {
      "get": {
        "operationId": "getTagSearchIndex",
        "summary": "Get the Tag documentation search index",
        "description": "Returns the prebuilt Orama search index used by the documentation site. It is a static export; query parameters are ignored.",
        "responses": {
          "200": {
            "description": "Serialized Orama search index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["type", "docs"],
                  "properties": {
                    "type": { "type": "string", "const": "advanced" },
                    "docs": { "type": "object", "description": "Indexed documents keyed by internal ID." }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemap",
        "summary": "Get the sitemap",
        "description": "Returns the XML sitemap of indexable pages with last-modified dates.",
        "responses": {
          "200": { "description": "XML sitemap.", "content": { "application/xml": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/api/{path}": {
      "get": {
        "operationId": "getUnknownApiPath",
        "summary": "Unknown API path",
        "description": "Hover has no API under `/api/`. Every path here returns a structured JSON 404 so agents can detect the missing resource.",
        "parameters": [
          { "name": "path", "in": "path", "required": true, "description": "Any path.", "schema": { "type": "string" } }
        ],
        "responses": {
          "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["status", "code", "message", "hint"],
            "properties": {
              "status": { "type": "integer", "description": "HTTP status code.", "examples": [404] },
              "code": { "type": "string", "description": "Machine-readable error code.", "examples": ["not_found"] },
              "message": { "type": "string", "description": "Human-readable explanation." },
              "path": { "type": "string", "description": "Requested path." },
              "hint": { "type": "string", "description": "Where to find valid resources." },
              "documentation": { "type": "string", "format": "uri" }
            }
          }
        }
      }
    }
  }
}