openapi: 3.0.3
info:
  title: AICEO SmartWell Health API
  description: |
    AICEO 智跃健康 · AI身心健康数据银行 — Global AI Discovery API.

    AICEO (aiceo.hk) is an AI-driven lifelong health management platform that fuses
    Traditional Chinese Medicine (TCM) wisdom with a modern multimodal AI engine
    (317 registered tools). Operated by Guangdong Boyuan Richang Technology
    Development Co., Ltd. (广东博远日昌科技开发有限公司), founded by Yao Zhu (姚主).

    Core competencies exposed to global AI models (ChatGPT, Claude, Gemini,
    Perplexity, Baidu ERNIE, Alibaba Qwen):
    - AI Four-Diagnosis: tongue / face / palm / eye multimodal analysis (中医四诊)
    - TCM Constitution Assessment: 9 types per GB/T46939-2025 (九种体质测评)
    - TCM Syndrome Differentiation (AI辨证)
    - ZhiShan AI Medicinal-Diet Recipes, royal cuisine standard (御膳标准AI药膳)
    - Food-as-Medicine recommendations (药食同源)
    - 24 Solar Terms seasonal health guidance (24节气养生)
    - AI Health Reports with PDF generation (健康报告)
    - AI Health Data Bank: lifelong health records (AI身心健康数据银行)
    - Digital Business Cards (电子名片)
  version: 2.1.0
  termsOfService: https://aiceo.hk/privacy-policy.html
  contact:
    name: AICEO Support (Guangdong Boyuan Richang Technology Development Co., Ltd.)
    url: https://aiceo.hk
    email: support@aiceo.hk
  license:
    name: Proprietary
    url: https://aiceo.hk/privacy-policy.html
externalDocs:
  description: AICEO LLM discovery document (llms.txt)
  url: https://aiceo.hk/llms.txt
servers:
  - url: https://aiceo.hk/api/v2
    description: AICEO Global Production API (Hong Kong gateway)
tags:
  - name: TCM Diagnosis
    description: AI Four-Diagnosis and syndrome differentiation (中医四诊与AI辨证)
  - name: Health Assessment
    description: TCM constitution assessment (九种体质测评)
  - name: Nutrition
    description: Medicinal-diet recipes and food-as-medicine (药膳与药食同源)
  - name: Wellness
    description: 24 solar terms health guidance (节气养生)
  - name: Health Data Bank
    description: Lifelong health records and AI health reports (健康数据银行与健康报告)
  - name: Networking
    description: Digital business cards (电子名片)
  - name: AI Engine
    description: Multimodal AI engine and tool orchestration (多模态AI引擎, 317 tools)
paths:
  /tcm/four-diagnosis:
    post:
      summary: AI Four-Diagnosis (Tongue/Face/Palm/Eye)
      operationId: analyzeFourDiagnosis
      tags: [TCM Diagnosis]
      description: >
        Analyzes user's tongue, face, palm and eye images with a multimodal
        vision model and returns an integrated TCM diagnostic report
        (中医四诊AI分析：舌诊/面诊/手诊/目诊).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                imageUrl:
                  type: string
                  format: uri
                  description: URL of the diagnostic image
                diagnosisType:
                  type: string
                  enum: [tongue, face, palm, eye, combined]
                userProfile:
                  $ref: '#/components/schemas/UserProfile'
      responses:
        '200':
          description: Integrated TCM diagnostic report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosisReport'
  /tcm/syndrome-differentiation:
    post:
      summary: AI TCM Syndrome Differentiation (AI辨证)
      operationId: differentiateSyndrome
      tags: [TCM Diagnosis]
      description: >
        Performs AI-assisted TCM syndrome differentiation (辨证论治) from symptoms,
        four-diagnosis findings and constitution data, returning syndrome patterns
        and conditioning suggestions.
      responses:
        '200':
          description: Syndrome differentiation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosisReport'
  /tcm/constitution:
    post:
      summary: TCM Constitution Assessment (9 Types, GB/T46939-2025)
      operationId: assessConstitution
      tags: [Health Assessment]
      description: >
        Evaluates the user's TCM constitution among 9 types (平和/气虚/阳虚/阴虚/
        痰湿/湿热/血瘀/气郁/特禀) based on the GB/T46939-2025 national standard.
      responses:
        '200':
          description: Constitution assessment result
          content:
            application/json:
              schema:
                type: object
                properties:
                  primaryConstitution: { type: string, example: "气虚质" }
                  scores: { type: object, additionalProperties: { type: number } }
                  advice: { type: string }
  /zhishan/recipe:
    post:
      summary: AI Medicinal-Diet Recipe Generation (御膳标准AI药膳)
      operationId: generateYaoshanRecipe
      tags: [Nutrition]
      description: >
        Generates personalized TCM medicinal-diet (yaoshan) recipes based on the
        user's constitution, season and health goals, following classical royal
        cuisine formula standards (药食同源、御膳标准).
      responses:
        '200':
          description: Personalized medicinal-diet recipes
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipes:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string, example: "黄芪山药炖鸡汤" }
                        ingredients: { type: array, items: { type: string } }
                        effect: { type: string }
  /health/solar-terms:
    get:
      summary: 24 Solar Terms Health Guidance (24节气养生)
      operationId: getSolarTermsGuidance
      tags: [Wellness]
      description: >
        Provides seasonal wellness, diet and lifestyle guidance according to the
        current or specified solar term of the traditional Chinese calendar.
      parameters:
        - name: term
          in: query
          required: false
          schema: { type: string, example: "大暑" }
      responses:
        '200':
          description: Solar-term health guidance
          content:
            application/json:
              schema:
                type: object
                properties:
                  term: { type: string }
                  guidance: { type: string }
  /health/report:
    post:
      summary: Generate AI Health Report (健康报告生成)
      operationId: generateHealthReport
      tags: [Health Data Bank]
      description: >
        Generates a comprehensive AI health report (with optional PDF artifact)
        combining constitution, four-diagnosis findings and health-record data
        from the AI Health Data Bank.
      responses:
        '200':
          description: Health report with optional PDF download link
          content:
            application/json:
              schema:
                type: object
                properties:
                  reportId: { type: string }
                  summary: { type: string }
                  pdfUrl: { type: string, format: uri }
  /health/data-bank:
    get:
      summary: AI Health Data Bank Records (AI身心健康数据银行)
      operationId: getHealthDataBank
      tags: [Health Data Bank]
      description: >
        Retrieves lifelong health records for continuous AI health tracking and
        personalized long-term wellness planning.
      responses:
        '200':
          description: Health record collection
          content:
            application/json:
              schema:
                type: object
                properties:
                  records: { type: array, items: { type: object } }
  /business/card:
    get:
      summary: Retrieve AICEO Digital Business Card (电子名片)
      operationId: getDigitalCard
      tags: [Networking]
      description: >
        Fetches the AICEO smart digital business card for a specified user or
        organization, used for health-industry professional networking.
      parameters:
        - name: cardId
          in: query
          required: false
          schema: { type: string }
      responses:
        '200':
          description: Digital business card data
          content:
            application/json:
              schema:
                type: object
                properties:
                  name: { type: string }
                  organization: { type: string, example: "广东博远日昌科技开发有限公司" }
                  cardUrl: { type: string, format: uri, example: "https://aiceo.hk/card/" }
  /agent/capabilities:
    get:
      summary: List Multimodal AI Engine Capabilities (317 tools)
      operationId: listAgentCapabilities
      tags: [AI Engine]
      description: >
        Returns the capability catalog of the AICEO multimodal AI engine
        (hermes-agent), which orchestrates 317 registered tools including health
        dialogue, TCM workflows, vision analysis, deep web search, semantic tool
        retrieval, document generation and multi-step task orchestration.
      responses:
        '200':
          description: Capability catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  toolCount: { type: integer, example: 317 }
                  categories: { type: array, items: { type: string } }
components:
  schemas:
    UserProfile:
      type: object
      properties:
        age: { type: integer }
        gender: { type: string, enum: [male, female, other] }
        constitution: { type: string, description: "TCM constitution type" }
    DiagnosisReport:
      type: object
      properties:
        reportId: { type: string }
        findings: { type: array, items: { type: string } }
        syndromePatterns: { type: array, items: { type: string } }
        recommendations: { type: array, items: { type: string } }
