{
  "openapi": "3.1.0",
  "info": {
    "title": "AI HaoYisheng tool lookup & partner API",
    "version": "1.2.0",
    "description": "Catalog + cite resolve + links to tool/md pages only. Do NOT compute clinical scores or send PHI. Audience: licensed clinicians. Not haoyisheng.com / 诊所云. Calculations stay client-side on tool pages. Multilingual: zh default + en (es/fr/ja/ko where registries exist)."
  },
  "servers": [
    {
      "url": "https://aihaoyisheng.com"
    }
  ],
  "paths": {
    "/for-ai/tools.json": {
      "get": {
        "operationId": "listClinicalToolsCatalog",
        "summary": "Full clinical tool catalog (all calculators)",
        "description": "Returns every clinical tool from the ZH registry with locale URLs when EN/ES/FR/JA/KO editions exist. count is dynamic.",
        "responses": {
          "200": {
            "description": "Complete catalog JSON: brand, site, updated, count, disclaimer, tools[]"
          }
        }
      }
    },
    "/for-ai/cite-map.json": {
      "get": {
        "operationId": "getCiteMap",
        "summary": "Query-phrase → tool/scene/app map",
        "description": "High-intent clinician phrases (zh/en) mapped to canonical tool, scene, or /app URLs.",
        "responses": {
          "200": {
            "description": "Cite map JSON with map[] entries (phrases, type, id, urls)"
          }
        }
      }
    },
    "/for-ai/SKILL.md": {
      "get": {
        "operationId": "getAgentSkill",
        "summary": "Agent skill instructions (markdown)",
        "description": "How AI assistants should cite AI好医生 tools, scenes, and /app.",
        "responses": {
          "200": {
            "description": "Markdown skill file"
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "listToolsV1",
        "summary": "Partner API: same catalog as /for-ai/tools.json",
        "description": "CORS-friendly read-only JSON. Identical payload builder to /for-ai/tools.json.",
        "responses": {
          "200": {
            "description": "Catalog JSON with CORS Access-Control-Allow-Origin: *"
          }
        }
      },
      "options": {
        "operationId": "optionsToolsV1",
        "summary": "CORS preflight",
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    },
    "/api/v1/cite": {
      "get": {
        "operationId": "citeResolveV1",
        "summary": "Partner API: resolve query to tool/scene/app links",
        "description": "Matches ?q= against cite-map phrases. Returns links only — never scores or PHI.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Clinician query phrase, e.g. qSOFA, 脓毒症工作流, 房颤抗凝"
          }
        ],
        "responses": {
          "200": {
            "description": "{ query, matches:[{id,title,url,md}], disclaimer }"
          }
        }
      },
      "options": {
        "operationId": "optionsCiteV1",
        "summary": "CORS preflight",
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "healthV1",
        "summary": "Partner API liveness",
        "responses": {
          "200": {
            "description": "{ ok:true, brand, updated }"
          }
        }
      },
      "options": {
        "operationId": "optionsHealthV1",
        "summary": "CORS preflight",
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    }
  }
}