openapi: 3.1.0
info:
  title: THE TEA — Content API
  version: "2.0"
  description: >
    Free, open, read-only REST API for a granular encyclopedia of Chinese tea:
    482 teas described across 72 languages, decomposed into queryable fields
    (taste, brewing, terroir, chemistry, sensory profiles, recipes, harvest, coordinates).
    See API_REFERENCE.md for the full guide.
  license:
    name: CC BY-NC-SA (content, preview) — see /api/v2 docs
    url: https://thetea.app
  contact:
    name: THE TEA
    url: https://thetea.app
servers:
  - url: https://api.thetea.app
tags:
  - name: teas
  - name: discovery
  - name: reference
paths:
  /api/v2/tea/{slug}:
    get:
      tags: [teas]
      summary: Full tea card (meta + fields + sensory + recipe + harvest + names + tags)
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string }, example: biluochun }
        - { name: lang, in: query, schema: { type: string, default: en }, example: ru }
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/TeaCard" } } } }
        "404": { description: Not found }
  /api/v2/tea/{slug}.md:
    get:
      tags: [teas]
      summary: Full tea card rendered as Markdown
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
        - { name: lang, in: query, schema: { type: string, default: en } }
      responses:
        "200": { description: Markdown, content: { text/markdown: { schema: { type: string } } } }
  /api/v2/tea/{slug}/{lang}/field/{code}:
    get:
      tags: [teas]
      summary: A single field value
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
        - { name: lang, in: path, required: true, schema: { type: string } }
        - { name: code, in: path, required: true, schema: { type: string }, example: water_temp }
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/Field" } } } }
        "404": { description: Not found }
  /api/v2/teas:
    get:
      tags: [discovery]
      summary: Filtered list of teas
      parameters:
        - { name: tea_type, in: query, schema: { type: string, enum: [green, white, yellow, oolong, red, dark, puer] } }
        - { name: country, in: query, schema: { type: string }, example: CN }
        - { name: province, in: query, schema: { type: string }, example: Fujian }
        - { name: brew_temp_max, in: query, schema: { type: integer }, example: 80 }
        - { name: altitude_min, in: query, schema: { type: integer }, example: 1500 }
        - { name: hasCoords, in: query, schema: { type: string, enum: ["1"] } }
        - { name: tag, in: query, schema: { type: string }, example: ten-famous-teas }
        - { name: q, in: query, schema: { type: string } }
        - { name: lang, in: query, schema: { type: string, default: en } }
        - { name: limit, in: query, schema: { type: integer, default: 100, maximum: 500 } }
        - { name: offset, in: query, schema: { type: integer, default: 0 } }
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/TeaList" } } } }
  /api/v2/search:
    get:
      tags: [discovery]
      summary: Multilingual search (Cyrillic / Hanzi / pinyin / Latin)
      parameters:
        - { name: q, in: query, required: true, schema: { type: string }, example: билочунь }
        - { name: lang, in: query, schema: { type: string, default: en } }
        - { name: limit, in: query, schema: { type: integer, default: 30, maximum: 200 } }
      responses:
        "200": { description: OK }
        "400": { description: q required }
  /api/v2/map:
    get:
      tags: [discovery]
      summary: All teas with coordinates (map layer)
      parameters: [ { name: lang, in: query, schema: { type: string, default: en } } ]
      responses: { "200": { description: OK } }
  /api/v2/random:
    get:
      tags: [discovery]
      summary: A random tea card (tea of the moment)
      parameters: [ { name: lang, in: query, schema: { type: string, default: en } } ]
      responses: { "200": { description: OK } }
  /api/v2/compare:
    get:
      tags: [discovery]
      summary: Compare 2–5 teas side by side on key fields
      parameters:
        - { name: slugs, in: query, required: true, schema: { type: string }, example: "biluochun,xihu-longjing" }
        - { name: lang, in: query, schema: { type: string, default: en } }
      responses: { "200": { description: OK }, "400": { description: slugs required } }
  /api/v2/glossary:
    get:
      tags: [reference]
      summary: Multilingual tea terminology (2623 terms)
      parameters:
        - { name: lang, in: query, schema: { type: string, default: en } }
        - { name: category, in: query, schema: { type: string }, example: tasting }
        - { name: q, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 100, maximum: 500 } }
      responses: { "200": { description: OK } }
  /api/v2/family:
    get: { tags: [reference], summary: Named tea families (taxonomy), responses: { "200": { description: OK } } }
  /api/v2/meta:
    get: { tags: [reference], summary: Locale (72) and country (25) registries, responses: { "200": { description: OK } } }
components:
  schemas:
    Field:
      type: object
      properties:
        value_md: { type: string }
        value_num: { type: [number, "null"] }
        unit: { type: [string, "null"] }
        section_code: { type: string }
    TeaList:
      type: object
      properties:
        count: { type: integer }
        offset: { type: integer }
        items:
          type: array
          items:
            type: object
            properties:
              slug: { type: string }
              tea_type: { type: string }
              origin_country: { type: string }
              province: { type: [string, "null"] }
              lat: { type: [number, "null"] }
              lng: { type: [number, "null"] }
              brew_temp_min: { type: [integer, "null"] }
              brew_temp_max: { type: [integer, "null"] }
              name: { type: [string, "null"] }
    TeaCard:
      type: object
      properties:
        slug: { type: string }
        kind: { type: string, enum: [tea, category] }
        lang: { type: string }
        name: { type: string }
        meta: { type: object, description: language-neutral facts (tea_type, oxidation, shape, coords, brew_temp, gi_status, province…) }
        names: { type: object, additionalProperties: { type: string }, description: name in each of 72 languages }
        sections:
          type: object
          description: "section_code -> { field_code -> { value, num?, unit?, source?, review? } }"
        sensory:
          type: array
          items: { type: object, properties: { descriptor_id: {type: string}, descriptor: {type: string}, intensity: {type: integer} } }
        recipe:
          type: array
          items: { type: object, properties: { style: {type: string}, water_temp: {type: integer}, tea_grams: {type: number}, water_ml: {type: integer}, steep_sec: {type: integer}, max_steeps: {type: integer}, rinse: {type: integer} } }
        harvest:
          type: array
          items: { type: object, properties: { phase: {type: string}, months: {type: string} } }
        tags: { type: array, items: { type: string } }
        comparison:
          type: array
          items: { type: object, properties: { other_slug: {type: string}, other_name: {type: string}, differences_md: {type: string} } }
