openapi: 3.2.0
info:
  title: Kann KI das? Search API
  version: 1.1.0
  description: Faceted product search plus machine-readable availability and buyer-confirmed Stripe Checkout for fixed sponsor placements.
servers:
- url: https://kannkidas.de/api
tags:
- name: Search
paths:
  /search:
    get:
      operationId: searchProductsAndCategories
      summary: Search and facet products and categories
      parameters:
      - name: q
        in: query
        schema:
          type: string
          maxLength: 160
      - name: type
        in: query
        schema:
          enum:
          - product
          - category
      - name: category
        in: query
        schema:
          type: string
      - name: verdict
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
      - name: perPage
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 60
      responses:
        '200':
          description: Ranked results and facet counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid search parameters
      tags:
      - Search
  /search/suggestions:
    get:
      operationId: suggestSearchTerms
      summary: Suggest products, categories and repeated successful queries
      parameters:
      - name: q
        in: query
        schema:
          type: string
          maxLength: 160
        required: true
      responses:
        '200':
          description: At most eight suggestions
          content:
            application/json:
              schema:
                type: object
                required:
                - suggestions
                properties:
                  suggestions:
                    type: array
                    maxItems: 8
                    items:
                      $ref: '#/components/schemas/Suggestion'
      tags:
      - Search
  /search/similar:
    get:
      operationId: getSimilarProducts
      summary: Return three nearest-neighbor products
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]*$
      responses:
        '200':
          description: Nearest products excluding the source product
          content:
            application/json:
              schema:
                type: object
                required:
                - hits
                properties:
                  hits:
                    type: array
                    maxItems: 3
                    items:
                      $ref: '#/components/schemas/SearchHit'
      tags:
      - Search
components:
  schemas:
    SearchHit:
      type: object
      additionalProperties: false
      required:
      - id
      - type
      - name
      - url
      - summary
      - highlights
      properties:
        id:
          type: string
        type:
          enum:
          - product
          - category
        name:
          type: string
        company:
          type: string
        url:
          type: string
        category:
          type: string
        summary:
          type: string
        verdict:
          type: string
        verdictLabel:
          type: string
        score:
          type: integer
        highlights:
          type: object
          additionalProperties:
            type: string
    Suggestion:
      type: object
      required:
      - kind
      - label
      properties:
        kind:
          enum:
          - product
          - category
          - query
        label:
          type: string
        url:
          type: string
        category:
          type: string
    SearchResponse:
      type: object
      required:
      - found
      - page
      - perPage
      - mode
      - tookMs
      - hits
      - facets
      properties:
        found:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        perPage:
          type: integer
          minimum: 1
          maximum: 60
        mode:
          enum:
          - hybrid
          - lexical
          - lexical-fallback
        tookMs:
          type: integer
          minimum: 0
        hits:
          type: array
          items:
            $ref: '#/components/schemas/SearchHit'
        facets:
          type: object
  securitySchemes:
    clientBasic:
      type: http
      scheme: basic
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://kannkidas.de/api/oauth/token
          scopes:
            sponsorship:read: Read own purchase status
            sponsorship:write: Create a confirmed checkout