openapi: 3.1.0
info:
  title: AustinEco Trade Knowledge API
  description: >
    Public API for accessing AustinEco's cross-border trade knowledge base,
    FAQs, and product standards data. Covers 22 trade pipeline nodes
    across 192 countries.
  version: "1.0.0"
  contact:
    name: AustinEco API Support
    email: api@austin-eco.com
    url: https://austin-eco.com
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://austin-eco.com
    description: Production

paths:
  /api/public/knowledge:
    get:
      operationId: searchKnowledge
      summary: Search trade knowledge terms
      description: >
        Query the AustinEco trade knowledge base. Returns structured
        DefinedTerm items with definitions, categories, and keywords.
        Supports full-text search across English and Chinese terms.
      parameters:
        - name: q
          in: query
          required: false
          description: Search query (matches slug, term_en, term_zh, definition_en, keywords)
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Number of results to return (max 100, default 20)
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: List of matching knowledge terms
          content:
            application/json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                  "@type":
                    type: string
                  name:
                    type: string
                  numberOfItems:
                    type: integer
                  itemListElement:
                    type: array
                    items:
                      type: object
                      properties:
                        "@type":
                          type: string
                        position:
                          type: integer
                        item:
                          type: object
                          properties:
                            name:
                              type: string
                            alternateName:
                              type: string
                            description:
                              type: string
                            url:
                              type: string
                            slug:
                              type: string
                            category:
                              type: string
                            keywords:
                              type: array
                              items:
                                type: string

  /api/public/knowledge/{slug}:
    get:
      operationId: getKnowledgeTerm
      summary: Get a specific knowledge term by slug
      description: >
        Retrieve detailed information about a single trade knowledge term
        including definition, FAQ pairs, practical guide, and data evidence.
      parameters:
        - name: slug
          in: path
          required: true
          description: The URL slug of the knowledge term
          schema:
            type: string
      responses:
        "200":
          description: Knowledge term details
          content:
            application/json:
              schema:
                type: object
                properties:
                  "@type":
                    type: string
                  name:
                    type: string
                  description:
                    type: string
                  url:
                    type: string
        "404":
          description: Term not found

  /api/public/faq:
    get:
      operationId: getFAQs
      summary: Get frequently asked questions about cross-border trade
      description: >
        Returns common cross-border trade FAQs in structured format.
      responses:
        "200":
          description: FAQ list
          content:
            application/json:
              schema:
                type: object

  /api/public/standards:
    get:
      operationId: getStandards
      summary: Get product standards and compliance requirements
      description: >
        Returns product standards, certification requirements, and
        compliance information for various target markets.
      parameters:
        - name: country
          in: query
          required: false
          description: Target country code (ISO 3166-1 alpha-2)
          schema:
            type: string
        - name: category
          in: query
          required: false
          description: Product category
          schema:
            type: string
      responses:
        "200":
          description: Standards list
          content:
            application/json:
              schema:
                type: object