Cuvo Health Discovery API

openapi: 3.2.0
info:
  title: Cuvo Health public Discovery API
  version: '2026-08-23'
  summary: Read-only content, discovery, and $0 discovery-call booking endpoints for AI agents. No authentication, no API keys.
  description: 'The public machine interface of cuvo.co, the Cuvo Health white label telehealth platform. Every endpoint is unauthenticated and free; all content mirrors claims already published on the human-readable pages. Human documentation lives at https://cuvo.co/developers (developer portal) and https://cuvo.co/api-docs (endpoint reference).


    Versioning: date-based. This document describes version 2026-08-23, echoed on every response in the API-Version header; requests may pin a version by sending the API-Version request header. Breaking changes ship as a new version date, the prior version keeps working for at least 90 days, and responses on a deprecated version carry Deprecation and Sunset headers for that whole window.


    Errors: unless an operation says otherwise, errors are RFC 9457 application/problem+json with a machine-readable "code" and a "hint" describing the recovery step. The ACP endpoints return the Agentic Commerce Protocol''s own error body (a messages array); the A2A and MCP endpoints return JSON-RPC 2.0 error objects.


    Rate limits: 300 requests per 60 seconds per IP on dynamic endpoints, advertised live in the RateLimit response headers; a 429 carries Retry-After. Statically cached endpoints advertise the policy in RateLimit-Policy.


    Related non-API resources: the sitemap at /sitemap.xml, the RSS feed at /feed.xml, the Schema Feeds map at /schemamap.xml (schemamap directive in robots.txt), scoped llms.txt files (/developers/llms.txt, /blog/llms.txt, /compare/llms.txt, /pricing/llms.txt, /api/llms.txt, /docs/llms.txt), and plain-markdown mirrors of the content pages: /index.md for the homepage, and .md appended to /pricing, /developers, /about, /booking, /terms, /privacy, /security, any /blog/, or any /compare/ URL. Every mirror opens with YAML frontmatter (title, description, canonical, last-updated).'
  contact:
    name: Cuvo Health team
    url: https://cuvo.co/booking
  termsOfService: https://cuvo.co/terms
  license:
    name: Proprietary (free to call; content mirrors the published site)
    url: https://cuvo.co/terms
servers:
- url: https://cuvo.co
security: []
tags:
- name: Discovery
  description: Agent discovery documents
paths:
  /auth.md:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getAuthDiscovery
      tags:
      - Discovery
      summary: Agent auth discovery
      description: 'Authentication and registration discovery for agents (auth.md convention): access is anonymous and no credentials are issued.'
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            text/markdown:
              schema:
                type: string
                description: Markdown document
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/agent-card.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getAgentCard
      tags:
      - Discovery
      summary: A2A Agent Card
      description: Agent2Agent card for the deterministic Cuvo agent (JSON-RPC endpoint at /api/a2a), including the AP2 merchant extension declaration. Legacy mirror at /.well-known/agent.json.
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCard'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/agent.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getAgentCardLegacy
      tags:
      - Discovery
      summary: A2A Agent Card (legacy location)
      description: Same document as /.well-known/agent-card.json, at the pre-1.0 well-known path some clients still probe.
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCard'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/acp.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getAcpDiscovery
      tags:
      - Discovery
      summary: ACP discovery document
      description: 'Agentic Commerce Protocol discovery (agenticcommerce.dev): protocol version, API base URL, and the checkout service for the free discovery call.'
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcpDiscovery'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/mcp.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getMcpManifest
      tags:
      - Discovery
      summary: MCP server manifest
      description: Model Context Protocol server manifest (MCP registry server.json format) describing the streamable-HTTP server at /mcp and its tool surface.
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpManifest'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/mcp-docs.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getDocsMcpManifest
      tags:
      - Discovery
      summary: Documentation MCP server manifest
      description: MCP registry server.json manifest for the read-only documentation server at /docs/mcp.
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpManifest'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/mcp/server-card.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getMcpServerCard
      tags:
      - Discovery
      summary: MCP server card
      description: 'Preview of the product MCP server: name, description, version, serverUrl, and the full tool list with input schemas and behavioral annotations, so agents can inspect the surface before opening a transport connection.'
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerCard'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/agent-skills/index.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getAgentSkillsIndex
      tags:
      - Discovery
      summary: Agent Skills index
      description: 'Flat list of every capability this site offers an agent: each skill carries a name, description, protocol, and endpoint.'
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSkillsIndex'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
  /.well-known/ai-catalog.json:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getAiCatalog
      tags:
      - Discovery
      summary: ARD AI catalog
      description: 'Agentic Resource Discovery catalog (agenticresourcediscovery.org): the MCP servers, agents, skills, and APIs this domain publishes, as one machine-readable index.'
      responses:
        '200':
          description: OK
          headers:
            API-Version:
              $ref: '#/components/headers/ApiVersion'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiCatalog'
        4XX:
          $ref: '#/components/responses/FallbackNotFound'
components:
  schemas:
    AgentCard:
      type: object
      description: A2A Agent Card (a2a-protocol.org). Declares the JSON-RPC endpoint, skills, and the AP2 merchant extension.
      properties:
        name:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        capabilities:
          type: object
        skills:
          type: array
          items:
            type: object
      required:
      - name
      - url
      additionalProperties: true
    McpManifest:
      type: object
      description: MCP registry server.json manifest for the /mcp endpoint.
      properties:
        $schema:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        version:
          type: string
        websiteUrl:
          type: string
          format: uri
        remotes:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - streamable-http
              url:
                type: string
                format: uri
            required:
            - type
            - url
      required:
      - name
      - description
      - version
      - remotes
    McpServerCard:
      type: object
      description: 'MCP server card: a connection-free preview of the server.'
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: string
        serverUrl:
          type: string
          format: uri
        transport:
          type: string
        authentication:
          type: string
        tools:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              title:
                type: string
              description:
                type: string
              inputSchema:
                type: object
              annotations:
                type: object
            required:
            - name
            - description
            - inputSchema
      required:
      - name
      - description
      - version
      - serverUrl
      - tools
    AgentSkillsIndex:
      type: object
      description: 'Agent Skills index: the site''s capabilities as name+description entries with protocol and endpoint.'
      properties:
        version:
          type: string
        provider:
          type: object
          properties:
            name:
              type: string
            url:
              type: string
              format: uri
          required:
          - name
          - url
        skills:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              protocol:
                type: string
              endpoint:
                type: string
                format: uri
              readOnly:
                type: boolean
            required:
            - name
            - description
            - protocol
            - endpoint
      required:
      - version
      - provider
      - skills
    AiCatalog:
      type: object
      description: Agentic Resource Discovery AI catalog (specVersion, host, entries, collections).
      properties:
        specVersion:
          type: string
        host:
          type: object
          properties:
            displayName:
              type: string
            identifier:
              type: string
          required:
          - displayName
          - identifier
        entries:
          type: array
          items:
            type: object
            properties:
              identifier:
                type: string
              displayName:
                type: string
              type:
                type: string
              url:
                type: string
                format: uri
              description:
                type: string
            required:
            - identifier
            - displayName
            - type
            - url
        collections:
          type: array
          items:
            type: object
      required:
      - specVersion
      - host
      - entries
    AcpDiscovery:
      type: object
      description: 'ACP discovery document: protocol version, REST base URL, and capabilities.'
      properties:
        protocol:
          type: object
          properties:
            name:
              type: string
              const: acp
            version:
              type: string
            supported_versions:
              type: array
              items:
                type: string
            documentation_url:
              type: string
              format: uri
          required:
          - name
          - version
        api_base_url:
          type: string
          format: uri
        transports:
          type: array
          items:
            type: string
        capabilities:
          type: object
      required:
      - protocol
      - api_base_url
  headers:
    RateLimitPolicy:
      description: Rate-limit policy (draft-ietf-httpapi-ratelimit-headers structured field), e.g. "default";q=60;w=60.
      schema:
        type: string
    ApiVersion:
      description: The API version that served this response.
      schema:
        type: string
        enum:
        - '2026-08-23'
  responses:
    FallbackNotFound:
      description: 'Any client error at a statically served URL falls through to the site-wide fallback: a real 4xx status whose body is short markdown with recovery links (sitemap, llms.txt, developer portal) for clients that do not ask for HTML.'
      content:
        text/markdown:
          schema:
            type: string
            description: Markdown document
  parameters:
    ApiVersion:
      name: API-Version
      in: header
      required: false
      description: Pin a specific API version (date-based). Omitting it selects the current version; every response echoes the version served.
      schema:
        type: string
        enum:
        - '2026-08-23'