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

    AICEO (aiceo.hk.cn) is an AI-driven lifelong health management platform that fuses
    Traditional Chinese Medicine (TCM) wisdom with a modern multimodal AI engine
    (317 registered tools across 57 categories). Operated by Guangdong Boyuan Richang
    Technology Development Co., Ltd. (广东博远日昌科技开发有限公司), founded by Yao Zhu (姚主).
    Strategic positioning: TCM-Western medicine integration + AI + Period 9
    Li-Fire strategy (中西医融合+AI+九紫离火运战略, 2024-2043).

    Core data assets: 9 TCM constitution types (GB/T46939-2025), 102 food-as-medicine
    ingredients (102种药食同源), 108 royal-cuisine medicinal-diet recipes (108道御膳配方).

    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药膳·108道)
    - Food-as-Medicine recommendations (药食同源·102种食材)
    - 24 Solar Terms seasonal health guidance (24节气养生)
    - AI Health Reports with PDF generation (健康报告)
    - AI Health Data Bank: lifelong health records (AI身心健康数据银行)
    - Digital Business Cards (电子名片)

    Live endpoints (Mainland gateway, https://aiceo.hk.cn): AI cluster deep search
    (/api/v1/search/*), agentic AI chat with tool calling (/api/v1/gw/chat) are
    publicly callable without authentication. Constitution / recipe / core AI chat
    endpoints require an API key (contact support@aiceo.hk.cn).
  version: 3.0.0
  termsOfService: https://aiceo.hk.cn/privacy-policy.html
  contact:
    name: AICEO Support (Guangdong Boyuan Richang Technology Development Co., Ltd.)
    url: https://aiceo.hk.cn
    email: support@aiceo.hk.cn
  license:
    name: Proprietary
    url: https://aiceo.hk.cn/privacy-policy.html
externalDocs:
  description: AICEO LLM discovery document (llms.txt)
  url: https://aiceo.hk.cn/llms.txt
servers:
  - url: https://aiceo.hk.cn
    description: AICEO Mainland China Production Gateway (live endpoints)
  - url: https://aiceo.hk/api/v2
    description: AICEO Global Gateway (Hong Kong, capability catalog)
tags:
  - name: Live Search
    description: AI cluster deep search, publicly callable (智能搜索·公开可调用)
  - name: Live AI Chat
    description: Agentic AI chat with autonomous tool calling, publicly callable (智能体对话·公开可调用)
  - 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 (药膳与药食同源, 102 ingredients / 108 recipes)
  - 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 / 57 categories)
paths:
  /api/v1/search/submit:
    post:
      summary: Submit AI Cluster Deep Search Task (提交智能搜索任务) — LIVE, no auth
      operationId: submitSearchTask
      tags: [Live Search]
      description: >
        Submits a deep search task to the AICEO AI cluster's distributed search
        workers. Returns a task_id for asynchronous result retrieval via
        /api/v1/search/result/{task_id}. Publicly callable on https://aiceo.hk.cn.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: Search query in Chinese or English
                  example: "中医九种体质与药膳调理"
      responses:
        '200':
          description: Task submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id: { type: string, format: uuid, example: "a3867e4f-3751-432c-9f79-860439184849" }
                  status: { type: string, example: "submitted" }
  /api/v1/search/result/{task_id}:
    get:
      summary: Get Search Task Result (获取搜索结果) — LIVE, no auth
      operationId: getSearchResult
      tags: [Live Search]
      parameters:
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Search result (status pending/running/completed)
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id: { type: string }
                  status: { type: string, enum: [pending, running, completed, failed] }
                  results: { type: array, items: { type: object } }
  /api/v1/search/status:
    get:
      summary: Search Cluster Status (搜索集群状态) — LIVE, no auth
      operationId: getSearchStatus
      tags: [Live Search]
      responses:
        '200':
          description: Cluster worker status
          content:
            application/json:
              schema:
                type: object
                properties:
                  workers: { type: integer, example: 4 }
                  status: { type: string, example: "online" }
  /api/v1/gw/chat:
    post:
      summary: Agentic AI Chat with Tool Calling (智能体对话·自主工具调用) — LIVE, no auth
      operationId: agentGatewayChat
      tags: [Live AI Chat]
      description: >
        Chat with the AICEO agent gateway. The agent autonomously decides whether
        to answer directly or call cluster tools (service status, command execution,
        log query, task list) via MCP before responding. Publicly callable on
        https://aiceo.hk.cn.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                  example: "AI集群当前各服务运行状态如何？"
      responses:
        '200':
          description: Agent reply with tool-call trace
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply: { type: string }
                  tool_calls: { type: array, items: { type: object } }
                  elapsed: { type: number }
  /api/v1/zhishan/constitutions:
    get:
      summary: List 9 TCM Constitution Types (九种体质数据) — requires API key
      operationId: listConstitutions
      tags: [Health Assessment]
      security:
        - ApiKeyAuth: []
      description: >
        Returns the 9 TCM constitution types (平和/气虚/阳虚/阴虚/痰湿/湿热/血瘀/气郁/特禀)
        per the GB/T46939-2025 national standard, with characteristics and
        conditioning guidance. Requires an API key (contact support@aiceo.hk.cn).
      responses:
        '200':
          description: Constitution catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  constitutions:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string, example: "气虚质" }
                        characteristics: { type: string }
                        advice: { type: string }
        '401': { description: Missing or invalid API key }
  /api/v1/zhishan/recipes:
    get:
      summary: List Medicinal-Diet Recipes, 108 Royal Formulas (药膳配方·御膳108道) — requires API key
      operationId: listRecipes
      tags: [Nutrition]
      security:
        - ApiKeyAuth: []
      description: >
        Returns medicinal-diet recipes from the 108 royal-cuisine-standard formula
        library, built on 102 food-as-medicine ingredients, filterable by
        constitution and solar term. Requires an API key (contact support@aiceo.hk.cn).
      parameters:
        - name: constitution
          in: query
          required: false
          schema: { type: string, example: "气虚质" }
        - name: solar_term
          in: query
          required: false
          schema: { type: string, example: "大暑" }
      responses:
        '200':
          description: Recipe list
          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 }
                        suitable_constitutions: { type: array, items: { type: string } }
        '401': { description: Missing or invalid API key }
  /api/v1/ai/chat:
    post:
      summary: Core AI Health Dialogue (核心健康对话·hermes引擎) — requires API key
      operationId: coreAiChat
      tags: [Live AI Chat]
      security:
        - ApiKeyAuth: []
      description: >
        Direct dialogue with the AICEO hermes multimodal AI engine (317 tools /
        57 categories) for TCM health consultation, syndrome differentiation and
        wellness guidance. Requires an API key (contact support@aiceo.hk.cn).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: { type: string, example: "我最近容易疲劳、舌淡有齿痕，是什么体质？" }
                session_id: { type: string }
      responses:
        '200':
          description: AI health reply
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply: { type: string }
                  session_id: { type: string }
        '401': { description: Missing or invalid API key }
  /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药膳·108道)
      operationId: generateYaoshanRecipe
      tags: [Nutrition]
      description: >
        Generates personalized TCM medicinal-diet (yaoshan) recipes based on the
        user's constitution, season and health goals, drawing on 102 food-as-medicine
        ingredients and 108 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.cn/card/" }
  /agent/capabilities:
    get:
      summary: List Multimodal AI Engine Capabilities (317 tools / 57 categories)
      operationId: listAgentCapabilities
      tags: [AI Engine]
      description: >
        Returns the capability catalog of the AICEO multimodal AI engine
        (hermes-agent), which orchestrates 317 registered tools across 57
        categories 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 }
                  categoryCount: { type: integer, example: 57 }
                  categories: { type: array, items: { type: string } }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Contact support@aiceo.hk.cn to obtain an API key for protected endpoints.
  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 } }
