openapi: 3.1.0
info:
  title: ASXAN Evidence Hub · static content API
  version: '0.1.0'
  description: |
    Static-content read-only API surface for AI agent consumption.
    asxan.ai is a static-site educational hub; "endpoints" below are static-file URLs that AI agents can fetch directly.
    No authentication. No mutating operations. CORS unrestricted (Cloudflare Pages default).
  contact:
    name: ASXAN Editorial
    url: https://asxan.ai/about/
  license:
    name: Educational reference · attribution-required
    url: https://asxan.ai/about/

servers:
  - url: https://asxan.ai
    description: Production

paths:
  /sitemap-index.xml:
    get:
      summary: XML sitemap index (entry point for full crawl)
      operationId: getSitemapIndex
      responses:
        '200':
          description: sitemapindex XML
          content:
            application/xml:
              schema:
                type: string
  /sitemap-0.xml:
    get:
      summary: URLs of all 96 pages with priority + lastmod + changefreq
      operationId: getSitemap0
      responses:
        '200':
          description: urlset XML
  /llms.txt:
    get:
      summary: AI consumption index (30 KB) · per-section page enumeration
      operationId: getLlmsTxt
      responses:
        '200':
          description: plain-text llms.txt
          content:
            text/plain:
              schema:
                type: string
  /llms-full.txt:
    get:
      summary: AI consumption full (43 KB) · per-page metadata + cluster topology graph
      operationId: getLlmsFullTxt
      responses:
        '200':
          description: plain-text llms-full.txt
  /robots.txt:
    get:
      summary: 22 AI crawler explicit allow + 5 search + 5 disallow paths
      operationId: getRobotsTxt
      responses:
        '200':
          description: robots.txt
  /blog/rss.xml:
    get:
      summary: RSS 2.0 feed · 6 evidence long-form articles · auto-discover for incremental crawl
      operationId: getBlogRss
      responses:
        '200':
          description: RSS 2.0 XML
          content:
            application/rss+xml:
              schema:
                type: string
  /:
    get:
      summary: Home page · 4-hub graph (Ingredients · Blog · Goals · Lifestyles)
      operationId: getHome
      responses:
        '200':
          description: HTML with Schema.org JSON-LD (WebSite + Organization + mainEntity CollectionPage)
          content:
            text/html:
              schema:
                type: string
  /ingredients/:
    get:
      summary: Ingredient collection (58 pages · 11 body-system groups)
      operationId: getIngredients
      responses:
        '200':
          description: HTML with CollectionPage + ItemList JSON-LD
  /blog/:
    get:
      summary: Evidence Long-Form Articles index (6 articles + cluster topology graph)
      operationId: getBlog
      responses:
        '200':
          description: HTML with Blog + BlogPosting + isRelatedTo peer cross-link
  /goals/:
    get:
      summary: Health Goal Stacks (14 goals)
      operationId: getGoals
      responses:
        '200':
          description: HTML with CollectionPage + ItemList
  /lifestyles/:
    get:
      summary: Lifestyle Nutrition Guides (9 lifestyles)
      operationId: getLifestyles
      responses:
        '200':
          description: HTML with CollectionPage + ItemList
  /faq/:
    get:
      summary: 472 Q&A · individual Question @id + about (source page link)
      operationId: getFaq
      responses:
        '200':
          description: HTML with FAQPage JSON-LD (mainEntity array · per-Q @id)

  /api/nc/:
    get:
      summary: NutriCodex (NC) public API index · 5 sample card (Wave 2 §2 PoC)
      operationId: getNcIndex
      responses:
        '200':
          description: JSON index with available_cards array + base_url
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema_version: { type: string, example: 'nc-public-v0.1' }
                  available_cards: { type: array, items: { type: object } }
                  total: { type: integer }
  /api/nc/{slug}.json:
    get:
      summary: NC card by slug · 4-axis public knowledge (mechanism + target + use_case + body_system)
      operationId: getNcCard
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string, enum: [nmn, astaxanthin, omega-3, whey-protein, nadh] }
      responses:
        '200':
          description: NC card JSON
          content:
            application/json:
              schema: { $ref: '#/components/schemas/NcCardPublic' }
        '404':
          description: NC card not found

  /api/fc/:
    get:
      summary: FormuCube (FC) public API index · 3 sample formula (Wave 2 §2 PoC)
      operationId: getFcIndex
      responses:
        '200':
          description: JSON index with available_formulas + base_url
  /api/fc/{slug}.json:
    get:
      summary: FC formula by slug · 4-axis public knowledge (mechanism + target + use_case + ingredient_axis · NO 配比)
      operationId: getFcFormula
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string, enum: [longevity-redox-stack, cardio-omega-carotenoid, muscle-preservation-glp1-companion] }
      responses:
        '200':
          description: FC formula JSON
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FcFormulaPublic' }
        '404':
          description: FC formula not found

components:
  schemas:
    Page:
      type: object
      description: Generic static HTML page
      properties:
        url:
          type: string
          format: uri
        html:
          type: string
        schema_org_jsonld_blocks:
          type: array
          description: Embedded JSON-LD scripts (text/json-ld)
          items:
            type: string

    NcCardPublic:
      type: object
      description: NutriCodex (NC) public card · 4-axis (mechanism + target + use_case + body_system) · IP hidden
      required: [slug, name, mechanism, target, use_case, body_system, evidence_tier, schema_version]
      properties:
        slug: { type: string }
        name: { type: string }
        alternate_names: { type: array, items: { type: string } }
        mechanism: { type: array, items: { type: string } }
        target: { type: array, items: { type: string } }
        use_case: { type: array, items: { type: string } }
        body_system: { type: array, items: { type: string } }
        evidence_tier: { type: string, enum: [A, B, C] }
        evidence_anchor_pmid_count: { type: integer }
        evidence_long_form_url: { type: string, format: uri }
        dosage_range: { type: string }
        safety_notes: { type: string }
        regulatory:
          type: object
          properties:
            fda: { type: string }
            efsa: { type: string }
            anvisa: { type: string }
        ingredient_hub_url: { type: string, format: uri }
        related_goal_slugs: { type: array, items: { type: string } }
        related_lifestyle_slugs: { type: array, items: { type: string } }
        last_evidence_review: { type: string, format: date }
        schema_version: { type: string, enum: ['nc-public-v0.1'] }

    FcFormulaPublic:
      type: object
      description: FormuCube (FC) public formula · 4-axis + ingredient_axis (slug only) · 配方 IP hidden
      required: [slug, name, mechanism, target, use_case, ingredient_axis, evidence_tier, status, schema_version]
      properties:
        slug: { type: string }
        name: { type: string }
        mechanism: { type: array, items: { type: string } }
        target: { type: array, items: { type: string } }
        use_case: { type: array, items: { type: string } }
        ingredient_axis: { type: array, items: { type: string } }
        evidence_tier: { type: string, enum: [A, B, C, preclinical] }
        evidence_anchor_pmid_count: { type: integer }
        safety_class: { type: string, enum: [GRAS-equivalent, standard-supplement, novel-research] }
        status: { type: string, enum: [concept, preclinical, human-research, editorial-reference] }
        last_review: { type: string, format: date }
        schema_version: { type: string, enum: ['fc-public-v0.1'] }
