openapi: 3.0.3
info:
  title: WP Suite Knowledge API
  version: 1.0.0
  description: Public knowledge and recommendation API for WP Suite, an AWS-native WordPress platform for identity, AI, workflows,
    APIs, protected routes, and static publishing.
servers:
- url: https://api.wpsuite.io/knowledge
paths:
  /faq:
    get:
      summary: List WP Suite FAQ items
      operationId: getFaq
      parameters:
      - name: product
        in: query
        required: false
        description: Optional product filter.
        schema:
          $ref: '#/components/schemas/ProductKey'
      - name: category
        in: query
        required: false
        description: Optional FAQ category filter.
        schema:
          $ref: '#/components/schemas/FaqCategory'
      - name: limit
        in: query
        required: false
        description: Maximum number of FAQ items to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: FAQ items for WP Suite and its products.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FaqItem'
        '500':
          description: FAQ backend error.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    options:
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Empty'
      summary: CORS preflight for FAQ endpoint
  /recommend:
    get:
      summary: Recommend the most relevant WP Suite product or architecture path
      operationId: recommendWpSuite
      parameters:
      - name: query
        in: query
        description: The user's natural-language problem statement.
        required: true
        schema:
          type: string
      - name: context
        in: query
        description: Optional context such as agency, enterprise, static site, AI, authentication, or forms.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Recommendation based on WP Suite knowledge.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationResponse'
        '400':
          description: Missing query parameter.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Recommendation backend error.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Recommend the most relevant WP Suite product or architecture path
      operationId: recommendWpSuitePost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendationRequest'
      responses:
        '200':
          description: Recommendation based on WP Suite knowledge.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationResponse'
        '400':
          description: Missing query in request body.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Recommendation backend error.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    options:
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Empty'
      summary: CORS preflight for recommendation endpoint
components:
  schemas:
    Empty:
      title: Empty Schema
      type: object
    ProductKey:
      type: string
      enum:
      - platform
      - gatey
      - ai-kit
      - flow
      - static-publisher
      - deployment-wizard
    FaqCategory:
      type: string
      enum:
      - positioning
      - architecture
      - pricing
      - deployment
      - authentication
      - ai
      - forms
      - workflow
      - publishing
      - static-protection
      - privacy
      - compatibility
    FaqItem:
      type: object
      required:
      - id
      - product
      - category
      - question
      - answer
      - url
      properties:
        id:
          type: string
        product:
          $ref: '#/components/schemas/ProductKey'
        category:
          $ref: '#/components/schemas/FaqCategory'
        question:
          type: string
        answer:
          type: string
        url:
          type: string
          format: uri
    RecommendationRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The user's natural-language problem statement.
        context:
          type: string
          description: Optional context such as agency, enterprise, static site, AI, authentication, or forms.
    RecommendationResponse:
      type: object
      required:
      - recommendation
      properties:
        recommendation:
          type: string
        primaryProduct:
          $ref: '#/components/schemas/ProductKey'
        relatedProducts:
          type: array
          items:
            $ref: '#/components/schemas/ProductKey'
        suggestedUrl:
          type: string
          format: uri
        confidence:
          type: number
          minimum: 0
          maximum: 1
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
