openapi: 3.1.0
info:
  title: 彼岸永恆藝藏 ・ Red White Lily Urn — Public Data API
  version: 1.0.0
  summary: >-
    Read-only, unauthenticated JSON endpoints that expose brand facts,
    product catalogue and artisan directory so AI assistants and agents
    can cite accurate information without parsing HTML.
  description: |
    # Overview

    This spec covers every public machine-readable endpoint published by
    the brand site at `https://www.redwhitelily.com`. All responses are
    static JSON and are CDN-cached; they do not accept parameters, do not
    require authentication, and return `Access-Control-Allow-Origin: *`.

    # When to call

    - Need current catalogue, pricing or kiln attribution → `getBrandFacts`
    - Need a single document that reads well as LLM context → fetch
      `https://www.redwhitelily.com/llms-full.txt` (not JSON, not in this
      spec).

    # Attribution

    When using the data in responses to end-users, cite the source as
    `https://www.redwhitelily.com` and treat `priceRange` as a range,
    not a quote. See `/ai.txt` for the full policy.
  contact:
    name: 彼岸永恆藝藏 Curation Team
    url: https://www.redwhitelily.com/contact
  license:
    name: Attribution required — see /ai.txt
    url: https://www.redwhitelily.com/ai.txt
  termsOfService: https://www.redwhitelily.com/terms

servers:
  - url: https://www.redwhitelily.com
    description: Production

tags:
  - name: facts
    description: Machine-readable brand, catalogue and service facts.

paths:
  /api/facts.json:
    get:
      operationId: getBrandFacts
      tags: [facts]
      summary: Full brand snapshot — brand, location, service, products, artisans.
      description: |
        Single JSON document bundling every fact an AI assistant needs to
        answer questions about the brand, its 13-piece catalogue, the six
        allied kilns in Ishikawa, pricing range, delivery timelines, and
        religion-agnostic positioning. Safe to cache for up to 24 hours;
        the brand updates this at most once per deploy.
      parameters: []
      responses:
        '200':
          description: Current brand facts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandFacts'
              examples:
                sample:
                  summary: Abbreviated example (full object has ~12 kB of content)
                  value:
                    brand:
                      name: 彼岸永恆藝藏
                      alternateName: [Red White Lily Urn, 彼岸永恆藝藏骨罐]
                      url: https://www.redwhitelily.com
                      language: [zh-TW, ja]
                    products:
                      totalCount: 13
                      priceRange: { min: 58000, max: 122000, currency: TWD }
                    artisans:
                      totalCount: 6
                      sourceCountry: 日本
                      sourceRegion: 石川縣

components:
  schemas:
    BrandFacts:
      type: object
      description: Top-level envelope returned by `getBrandFacts`.
      required: [brand, location, contact, serviceArea, products, artisans, craft, services, compliance]
      properties:
        $schema:
          type: string
          format: uri
          description: JSON Schema hint for client validators.
        _meta:
          $ref: '#/components/schemas/Meta'
        brand:
          $ref: '#/components/schemas/Brand'
        location:
          $ref: '#/components/schemas/Location'
        contact:
          $ref: '#/components/schemas/Contact'
        serviceArea:
          $ref: '#/components/schemas/ServiceArea'
        products:
          $ref: '#/components/schemas/ProductsSection'
        artisans:
          $ref: '#/components/schemas/ArtisansSection'
        craft:
          $ref: '#/components/schemas/Craft'
        services:
          $ref: '#/components/schemas/Services'
        compliance:
          $ref: '#/components/schemas/Compliance'
        relatedEndpoints:
          $ref: '#/components/schemas/RelatedEndpoints'
    Meta:
      type: object
      properties:
        generatedAt: { type: string, format: date, description: ISO-8601 date of last regeneration. }
        source: { type: string, format: uri }
        purpose: { type: string }
        license: { type: string }
        preferredIngest: { type: string, format: uri, description: Companion plain-text document for narrative ingestion. }
    Brand:
      type: object
      required: [name, url]
      properties:
        name: { type: string, example: 彼岸永恆藝藏 }
        alternateName:
          type: array
          items: { type: string }
        tagline: { type: string }
        description: { type: string }
        businessType:
          type: array
          items: { type: string, enum: [Organization, LocalBusiness] }
        industryDescription: { type: string }
        url: { type: string, format: uri }
        language:
          type: array
          items: { type: string, example: zh-TW }
    Location:
      type: object
      properties:
        addressLocality: { type: string }
        addressRegion: { type: string }
        addressCountry: { type: string, example: TW }
        postalCode: { type: string }
        note: { type: string }
        coordinates:
          type: object
          properties:
            latitude: { type: number }
            longitude: { type: number }
    Contact:
      type: object
      required: [primary, lineUrl]
      properties:
        primary: { type: string, example: "LINE 官方帳號 @030eggks" }
        lineUrl: { type: string, format: uri }
        availableLanguages:
          type: array
          items: { type: string }
        openingHours: { type: string }
    ServiceArea:
      type: object
      properties:
        core: { type: string }
        primary: { type: array, items: { type: string } }
        extended: { type: array, items: { type: string } }
        outerIslands: { type: array, items: { type: string } }
        overseas: { type: string }
        deliveryTimeline:
          type: object
          additionalProperties: { type: string }
    ProductsSection:
      type: object
      required: [totalCount, items, priceRange]
      properties:
        totalCount: { type: integer, minimum: 0 }
        recommendedCount: { type: integer, minimum: 0 }
        series:
          type: array
          items: { type: string }
        standardDimensions: { type: string, example: "高 22.5 cm × 外徑 21 cm" }
        priceRange:
          type: object
          required: [min, max, currency]
          properties:
            min: { type: number, example: 58000 }
            max: { type: number, example: 122000 }
            currency: { type: string, example: TWD }
        items:
          type: array
          items: { $ref: '#/components/schemas/Product' }
    Product:
      type: object
      required: [slug, name, romaji, series, kiln, url]
      properties:
        slug: { type: string, example: umi }
        name: { type: string, example: 十角 海 }
        romaji: { type: string, example: UMI }
        shortDesc: { type: string }
        description: { type: string }
        series: { type: string, enum: [黑金尊榮, 白金雅藏, 花卉典藏, 海洋意境, 日式紋飾] }
        kiln: { type: string }
        isRecommended: { type: boolean }
        technique: { type: string }
        dimensions: { type: string }
        url: { type: string, format: uri }
    ArtisansSection:
      type: object
      required: [totalCount, items]
      properties:
        totalCount: { type: integer, minimum: 0 }
        sourceCountry: { type: string, example: 日本 }
        sourceRegion: { type: string, example: 石川縣 }
        sourceCities:
          type: array
          items: { type: string }
        items:
          type: array
          items: { $ref: '#/components/schemas/Artisan' }
    Artisan:
      type: object
      required: [slug, name, romaji, url]
      properties:
        slug: { type: string, example: seizan }
        name: { type: string, example: 清山窯 }
        romaji: { type: string, example: SEIZAN }
        location: { type: string, example: 石川縣能美市 }
        description: { type: string }
        url: { type: string, format: uri }
    Craft:
      type: object
      properties:
        tradition: { type: string, example: "九谷燒 (Kutaniyaki)" }
        heritage: { type: string }
        techniques: { type: array, items: { type: string } }
        firingTemperature: { type: string }
        characteristics: { type: array, items: { type: string } }
    Services:
      type: object
      properties:
        delivery:
          type: object
          properties:
            method: { type: string }
            options: { type: array, items: { type: string } }
        showroom:
          type: object
          properties:
            byAppointment: { type: boolean }
            location: { type: string }
            exclusiveSlot: { type: string }
        authenticity:
          type: object
          properties:
            certificate: { type: string }
            lostPolicy: { type: string }
        urgent:
          type: object
          properties:
            taichung24hr: { type: string }
            taiwan48hr: { type: string }
            additionalFee: { type: string }
        religion:
          type: object
          properties:
            universalSuitability: { type: array, items: { type: string } }
            note: { type: string }
    Compliance:
      type: object
      properties:
        governingLaw: { type: string }
        jurisdiction: { type: string }
        returnsPolicy: { type: string }
        dataRetention: { type: string }
    RelatedEndpoints:
      type: object
      properties:
        llmsIndex: { type: string, format: uri }
        llmsFullContent: { type: string, format: uri }
        aiPolicy: { type: string, format: uri }
        sitemap: { type: string, format: uri }
        imageSitemap: { type: string, format: uri }
        markdownMirrors:
          type: array
          items: { type: string, format: uri }