{
  "openapi": "3.1.0",
  "info": {
    "title": "Vascue public content API",
    "version": "1.0.0",
    "summary": "Read-only, unauthenticated index of the public documents on www.vascue.io for search engines, AI assistants, and agents.",
    "description": "Every endpoint in this document is a public, GET-only, unauthenticated resource served by the Vascue marketing site. It exists so agents can discover Vascue's public product documentation without scraping HTML.\n\nUsage notice: this host contains public product and educational content only. Never send patient information, claim documents, clinic credentials, practice-management API keys, or booking requests to any endpoint on www.vascue.io. None of these endpoints accept a request body.\n\nAgent-based clinic booking is a research pilot, not a live public API; there is no booking endpoint here. Public knowledge search over this content is available through the Model Context Protocol endpoint described in `externalDocs` (the MCP server card), not through REST.\n\nMarkdown for agents: every HTML page on the site has a Markdown twin. Request any page path with `Accept: text/markdown` (at a q-value at least equal to text/html) or append `.md` to the path (`/` becomes `/index.md`). HTML responses carry `Vary: Accept` and a `Link: <...md>; rel=\"alternate\"; type=\"text/markdown\"` header; Markdown responses carry `Content-Location`, `X-Markdown-Tokens` (approximate token count), and a `Link` back to the HTML.",
    "termsOfService": "https://www.vascue.io/terms-of-service",
    "contact": {
      "name": "Vascue",
      "url": "https://www.vascue.io/contact-us",
      "email": "hello@vascue.io"
    },
    "x-data-classification": "public",
    "x-contains-patient-data": false,
    "x-llms-txt": "https://www.vascue.io/llms.txt"
  },
  "externalDocs": {
    "description": "Vascue public knowledge search (MCP server card, streamable HTTP at https://www.vascue.io/mcp/search). Public content only.",
    "url": "https://www.vascue.io/.well-known/mcp/server-card.json"
  },
  "servers": [
    {
      "url": "https://www.vascue.io",
      "description": "Canonical host. The apex https://vascue.io 301-redirects here."
    }
  ],
  "tags": [
    { "name": "agent-documents", "description": "Authored Markdown written for AI assistants and agents." },
    { "name": "discovery", "description": "Well-known descriptors for search, MCP, and agent skills." },
    { "name": "pages", "description": "Site pages with HTML and Markdown representations." },
    { "name": "crawl", "description": "Sitemap and robots directives for crawlers." }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "tags": ["agent-documents"],
        "operationId": "getLlmsTxt",
        "summary": "llms.txt: company, product, and page index for language models",
        "description": "Authored overview of Vascue (positioning, products, current commercial focus, who it is for) followed by a curated link list of every public page with a one-line description.",
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": { "text/markdown": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } } }
          }
        }
      }
    },
    "/claims-automation.md": {
      "get": {
        "tags": ["agent-documents"],
        "operationId": "getClaimsAutomationDoc",
        "summary": "Vascue Claims product document for agents",
        "description": "Current product focus for provider-side insurance claims automation: suitable workflows, inputs, deterministic checks, the human-review boundary, payer routing, reconciliation, and design-partner evaluation information.",
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": { "text/markdown": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } } }
          }
        }
      }
    },
    "/ai-agents.md": {
      "get": {
        "tags": ["agent-documents"],
        "operationId": "getAiAgentsDoc",
        "summary": "Agent-based clinic booking research note",
        "description": "Describes Vascue's research into assistant-driven clinic booking and its guardrails. This is a research pilot; it is not a live public booking API and accepts no patient data.",
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": { "text/markdown": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } } }
          }
        }
      }
    },
    "/.well-known/ai-search.json": {
      "get": {
        "tags": ["discovery"],
        "operationId": "getAiSearchDescriptor",
        "summary": "Descriptor for the public knowledge-search MCP endpoint",
        "responses": {
          "200": {
            "description": "AI Search descriptor",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSearchDescriptor" } } }
          }
        }
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "tags": ["discovery"],
        "operationId": "getMcpServerCard",
        "summary": "MCP server card for Vascue public knowledge search",
        "description": "Model Context Protocol server card (schema: https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json). Transport is streamable HTTP at https://www.vascue.io/mcp/search. The index holds public content only.",
        "responses": {
          "200": {
            "description": "MCP server card",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          }
        }
      }
    },
    "/.well-known/agent-skills/index.json": {
      "get": {
        "tags": ["discovery"],
        "operationId": "getAgentSkillsIndex",
        "summary": "Agent Skills discovery index",
        "description": "Lists the SKILL.md documents Vascue publishes (site navigation and claims-automation evaluation) with content digests. Schema: https://schemas.agentskills.io/discovery/0.2.0/schema.json.",
        "responses": {
          "200": {
            "description": "Agent skills index",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillsIndex" } } }
          }
        }
      }
    },
    "/.well-known/security.txt": {
      "get": {
        "tags": ["discovery"],
        "operationId": "getSecurityTxt",
        "summary": "security.txt (RFC 9116) vulnerability-disclosure contact",
        "responses": {
          "200": {
            "description": "security.txt",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["crawl"],
        "operationId": "getSitemap",
        "summary": "XML sitemap of every indexable page",
        "responses": {
          "200": {
            "description": "Sitemap",
            "content": { "application/xml": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "tags": ["crawl"],
        "operationId": "getRobotsTxt",
        "summary": "robots.txt with Content Signals",
        "description": "Allows all crawlers and declares Content-Signal: search=yes, ai-input=yes, ai-train=yes.",
        "responses": {
          "200": {
            "description": "robots.txt",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["discovery"],
        "operationId": "getOpenApi",
        "summary": "This document",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          }
        }
      }
    },
    "/{page}": {
      "get": {
        "tags": ["pages"],
        "operationId": "getPage",
        "summary": "Any site page as HTML or Markdown",
        "description": "Content negotiation for every HTML page on the site. Send `Accept: text/markdown` to receive the Markdown twin, or append `.md` to the path (for the homepage use `/index.md`). Paths are the ones listed in `/sitemap.xml` and `/llms.txt`, for example `/claims`, `/ai-front-desk`, `/pricing`, `/claims/faq`, `/blog/{slug}`. Product pages ship an authored Markdown twin; the rest are generated from the page's main content at build time. Unknown paths return 404.",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "Site path without a leading slash, e.g. `claims`, `claims/faq`, `blog/why-health-insurance-claims-get-rejected`. Append `.md` to force Markdown.",
            "schema": { "type": "string", "examples": ["claims", "claims/faq", "pricing", "blog/insurance-claim-automation-clinics-hospitals"] }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "`text/markdown` selects the Markdown twin; anything else (or omitted) returns HTML.",
            "schema": { "type": "string", "examples": ["text/markdown", "text/html"] }
          }
        ],
        "responses": {
          "200": {
            "description": "The page. HTML responses include `Vary: Accept` and a `Link` header pointing at the Markdown alternate.",
            "headers": {
              "Vary": { "schema": { "type": "string" }, "description": "Always includes `Accept`." },
              "Link": { "schema": { "type": "string" }, "description": "`rel=\"alternate\"` to the other representation; the homepage also lists the discovery documents above." },
              "Content-Location": { "schema": { "type": "string" }, "description": "Markdown responses only: the `.md` path that was served." },
              "X-Markdown-Tokens": { "schema": { "type": "integer" }, "description": "Markdown responses only: approximate token count (bytes / 4)." }
            },
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } }
            }
          },
          "404": { "description": "No such page." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MarkdownDocument": {
        "type": "string",
        "description": "UTF-8 Markdown. Generated page twins start with YAML front matter (title, description, image, canonical); authored documents may not."
      },
      "AiSearchDescriptor": {
        "type": "object",
        "required": ["name", "mcp", "server_card", "data_scope", "contains_patient_data"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "mcp": { "type": "string", "format": "uri", "const": "https://www.vascue.io/mcp/search" },
          "server_card": { "type": "string", "format": "uri" },
          "data_scope": { "type": "string", "const": "public-content-only" },
          "contains_patient_data": { "type": "boolean", "const": false },
          "usage_notice": { "type": "string" }
        }
      },
      "AgentSkillsIndex": {
        "type": "object",
        "required": ["skills"],
        "properties": {
          "$schema": { "type": "string", "format": "uri" },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "type", "url"],
              "properties": {
                "name": { "type": "string" },
                "type": { "type": "string", "const": "skill-md" },
                "description": { "type": "string" },
                "url": { "type": "string", "format": "uri" },
                "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
              }
            }
          }
        }
      }
    }
  }
}