llmo-api.yaml

llmo-sheet-data:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: dataSource
      in: path
      required: true
      description: The data source identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'questions'
  get:
    tags:
      - llmo
    summary: Get LLMO sheet data
    description: |
      Retrieves data from the external LLMO data endpoint for a specific site.
      This endpoint proxies data from the external HLX API based on the site's LLMO configuration.
    operationId: getLlmoSheetData
    responses:
      '200':
        description: LLMO sheet data retrieved successfully
        content:
          application/json:
            schema:
              type: object
              description: The data returned from the external LLMO endpoint
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  post:
    tags:
      - llmo
    summary: Query LLMO sheet data with filters, exclusions, and grouping
    description: |
      Retrieves and processes data from the external LLMO data endpoint for a specific site with advanced querying capabilities.
      This endpoint allows filtering data with case-insensitive exact matching, excluding specific fields from the response,
      and grouping data by specified attributes. The endpoint fetches all available data (up to 1M records) to apply
      the query operations effectively.
    operationId: queryLlmoSheetData
    requestBody:
      required: false
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoSheetDataQuery'
    responses:
      '200':
        description: LLMO sheet data queried and processed successfully
        content:
          application/json:
            schema:
              type: object
              description: The processed data returned from the external LLMO endpoint after applying filters, exclusions, and grouping
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-sheet-data-with-type:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: sheetType
      in: path
      required: true
      description: The sheet type identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'analytics'
    - name: dataSource
      in: path
      required: true
      description: The data source identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'questions'
  get:
    tags:
      - llmo
    summary: Get LLMO sheet data with sheet type
    description: |
      Retrieves data from the external LLMO data endpoint for a specific site with a specified sheet type.
      This endpoint proxies data from the external HLX API based on the site's LLMO configuration.
      The data is fetched from the path: {dataFolder}/{sheetType}/{dataSource}.json
    operationId: getLlmoSheetDataWithType
    responses:
      '200':
        description: LLMO sheet data retrieved successfully
        content:
          application/json:
            schema:
              type: object
              description: The data returned from the external LLMO endpoint
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  post:
    tags:
      - llmo
    summary: Query LLMO sheet data with sheet type using filters, exclusions, and grouping
    description: |
      Retrieves and processes data from the external LLMO data endpoint for a specific site with a specified sheet type
      and advanced querying capabilities. This endpoint allows filtering data with case-insensitive exact matching,
      excluding specific fields from the response, and grouping data by specified attributes.
      The data is fetched from the path: {dataFolder}/{sheetType}/{dataSource}.json
      The endpoint fetches all available data (up to 1M records) to apply the query operations effectively.
    operationId: queryLlmoSheetDataWithType
    requestBody:
      required: false
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoSheetDataQuery'
    responses:
      '200':
        description: LLMO sheet data queried and processed successfully
        content:
          application/json:
            schema:
              type: object
              description: The processed data returned from the external LLMO endpoint after applying filters, exclusions, and grouping
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-sheet-data-with-type-and-week:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: sheetType
      in: path
      required: true
      description: The sheet type identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'analytics'
    - name: week
      in: path
      required: true
      description: The week identifier (e.g., w01, w02) to fetch time-series data
      schema:
        type: string
        pattern: '^w\d{2}$'
        example: 'w01'
    - name: dataSource
      in: path
      required: true
      description: The data source identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'questions'
  get:
    tags:
      - llmo
    summary: Get LLMO sheet data with sheet type and week
    description: |
      Retrieves data from the external LLMO data endpoint for a specific site with a specified sheet type and week.
      This endpoint proxies data from the external HLX API based on the site's LLMO configuration.
      The data is fetched from the path: {dataFolder}/{sheetType}/{week}/{dataSource}.json
      This is useful for fetching time-series data organized by week.
    operationId: getLlmoSheetDataWithTypeAndWeek
    responses:
      '200':
        description: LLMO sheet data retrieved successfully
        content:
          application/json:
            schema:
              type: object
              description: The data returned from the external LLMO endpoint
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  post:
    tags:
      - llmo
    summary: Query LLMO sheet data with sheet type and week using filters, exclusions, and grouping
    description: |
      Retrieves and processes data from the external LLMO data endpoint for a specific site with a specified sheet type,
      week, and advanced querying capabilities. This endpoint allows filtering data with case-insensitive exact matching,
      excluding specific fields from the response, and grouping data by specified attributes.
      The data is fetched from the path: {dataFolder}/{sheetType}/{week}/{dataSource}.json
      The endpoint fetches all available data (up to 1M records) to apply the query operations effectively.
      This is useful for fetching and analyzing time-series data organized by week.
    operationId: queryLlmoSheetDataWithTypeAndWeek
    requestBody:
      required: false
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoSheetDataQuery'
    responses:
      '200':
        description: LLMO sheet data queried and processed successfully
        content:
          application/json:
            schema:
              type: object
              description: The processed data returned from the external LLMO endpoint after applying filters, exclusions, and grouping
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-data:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: file
      in: query
      required: false
      description: One or more file paths to fetch (comma-separated or multiple query params). Used for multi-file mode when no path parameters are provided.
      schema:
        type: string
        example: 'analytics/questions.json,analytics/answers.json'
    - name: filter.*
      in: query
      required: false
      description: Filter results by field values (e.g., filter.status=active, filter.category=cat1). Multiple filters are ANDed together with case-insensitive exact matching.
      schema:
        type: string
    - name: include
      in: query
      required: false
      description: Comma-separated list of fields to include in the response
      schema:
        type: string
        example: 'field1,field2,field3'
    - name: sort
      in: query
      required: false
      description: Sort results by field in ascending or descending order (format - field:asc or field:desc)
      schema:
        type: string
        example: 'date:desc'
    - name: sheets
      in: query
      required: false
      description: Comma-separated list of sheet names to include (for multi-sheet data)
      schema:
        type: string
        example: 'sheet1,sheet2'
    - name: limit
      in: query
      required: false
      description: Maximum number of records to return
      schema:
        type: integer
        default: 10000000
    - name: offset
      in: query
      required: false
      description: Number of records to skip
      schema:
        type: integer
        default: 0
    - name: sheet
      in: query
      required: false
      description: Specific sheet name to fetch from the data source
      schema:
        type: string
  get:
    tags:
      - llmo
    summary: Query LLMO data files with filters and sorting
    description: |
      Retrieves and processes data from the external LLMO data endpoint with advanced querying capabilities via URL parameters.
      This endpoint supports two modes:

      **Multi-file mode**: Use the `file` query parameter to fetch multiple files at once (up to 7 concurrent requests).
      Each file is processed independently and returned in a results array.

      **Single-file mode**: The endpoint will look for dataSource in the path and fetch that specific file.

      Query parameters allow filtering, field inclusion, sorting, and sheet selection. This is an optimized
      alternative to the POST endpoints that uses GET requests with URL parameters for caching and simplicity.
    operationId: queryLlmoData
    responses:
      '200':
        description: LLMO data queried and processed successfully
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  description: Single file response with processed data
                  properties:
                    data:
                      type: object
                      description: The processed data
                    headers:
                      type: object
                      description: Response headers from upstream
                - type: array
                  description: Multi-file response with array of results
                  items:
                    type: object
                    properties:
                      path:
                        type: string
                        description: The file path that was fetched
                      status:
                        type: string
                        enum: [success, error]
                        description: The status of the fetch operation
                      data:
                        type: object
                        description: The processed data (only present if status is success)
                      error:
                        type: string
                        description: Error message (only present if status is error)
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-data-with-datasource:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: dataSource
      in: path
      required: true
      description: The data source identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'questions.json'
    - name: filter.*
      in: query
      required: false
      description: Filter results by field values (e.g., filter.status=active)
      schema:
        type: string
    - name: include
      in: query
      required: false
      description: Comma-separated list of fields to include in the response
      schema:
        type: string
    - name: sort
      in: query
      required: false
      description: Sort results by field (format - field:asc or field:desc)
      schema:
        type: string
    - name: sheets
      in: query
      required: false
      description: Comma-separated list of sheet names to include
      schema:
        type: string
    - name: limit
      in: query
      required: false
      description: Maximum number of records to return
      schema:
        type: integer
    - name: offset
      in: query
      required: false
      description: Number of records to skip
      schema:
        type: integer
    - name: sheet
      in: query
      required: false
      description: Specific sheet name to fetch from the data source
      schema:
        type: string
  get:
    tags:
      - llmo
    summary: Query LLMO data for a specific data source
    description: |
      Retrieves and processes data from a specific data source file with query parameters for filtering,
      field inclusion, sorting, and sheet selection. The data is fetched from {dataFolder}/{dataSource}.
    operationId: queryLlmoDataWithSource
    responses:
      '200':
        description: LLMO data queried successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  description: The processed data
                headers:
                  type: object
                  description: Response headers
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-data-with-type:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: sheetType
      in: path
      required: true
      description: The sheet type identifier
      schema:
        type: string
        example: 'analytics'
    - name: dataSource
      in: path
      required: true
      description: The data source identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'questions.json'
    - name: filter.*
      in: query
      required: false
      description: Filter results by field values
      schema:
        type: string
    - name: include
      in: query
      required: false
      description: Comma-separated list of fields to include
      schema:
        type: string
    - name: sort
      in: query
      required: false
      description: Sort results by field
      schema:
        type: string
    - name: sheets
      in: query
      required: false
      description: Comma-separated list of sheet names to include
      schema:
        type: string
    - name: limit
      in: query
      required: false
      description: Maximum number of records to return
      schema:
        type: integer
    - name: offset
      in: query
      required: false
      description: Number of records to skip
      schema:
        type: integer
    - name: sheet
      in: query
      required: false
      description: Specific sheet name to fetch
      schema:
        type: string
  get:
    tags:
      - llmo
    summary: Query LLMO data with sheet type
    description: |
      Retrieves and processes data with a specified sheet type. The data is fetched from
      {dataFolder}/{sheetType}/{dataSource}. Supports query parameters for filtering, sorting, and field selection.
    operationId: queryLlmoDataWithType
    responses:
      '200':
        description: LLMO data queried successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                headers:
                  type: object
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-data-with-type-and-week:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: sheetType
      in: path
      required: true
      description: The sheet type identifier
      schema:
        type: string
        example: 'analytics'
    - name: week
      in: path
      required: true
      description: The week identifier (e.g., w01, w02)
      schema:
        type: string
        pattern: '^w\d{2}$'
        example: 'w01'
    - name: dataSource
      in: path
      required: true
      description: The data source identifier
      schema:
        type: string
        example: 'questions.json'
    - name: filter.*
      in: query
      required: false
      description: Filter results by field values
      schema:
        type: string
    - name: include
      in: query
      required: false
      description: Comma-separated list of fields to include
      schema:
        type: string
    - name: sort
      in: query
      required: false
      description: Sort results by field
      schema:
        type: string
    - name: sheets
      in: query
      required: false
      description: Comma-separated list of sheet names to include
      schema:
        type: string
    - name: limit
      in: query
      required: false
      description: Maximum number of records to return
      schema:
        type: integer
    - name: offset
      in: query
      required: false
      description: Number of records to skip
      schema:
        type: integer
    - name: sheet
      in: query
      required: false
      description: Specific sheet name to fetch
      schema:
        type: string
  get:
    tags:
      - llmo
    summary: Query LLMO data with sheet type and week
    description: |
      Retrieves and processes time-series data with a specified sheet type and week. The data is fetched from
      {dataFolder}/{sheetType}/{week}/{dataSource}. Supports query parameters for filtering, sorting, and field selection.
    operationId: queryLlmoDataWithTypeAndWeek
    responses:
      '200':
        description: LLMO data queried successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                headers:
                  type: object
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-global-sheet-data:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: configName
      in: path
      required: true
      description: The data source identifier to fetch from the external endpoint
      schema:
        type: string
        example: 'questions'
  get:
    tags:
      - llmo
    summary: Get LLMO global sheet data
    description: |
      Retrieves data from the external LLMO global data endpoint for a specific site.
      This endpoint proxies data from the external HLX API using the global 'llmo-global' folder,
      independent of the site's LLMO configuration dataFolder.
    operationId: getLlmoGlobalSheetData
    responses:
      '200':
        description: LLMO global sheet data retrieved successfully
        content:
          application/json:
            schema:
              type: object
              description: The data returned from the external LLMO endpoint
              additionalProperties: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-config:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - $ref: './parameters.yaml#/llmoConfigVersion'
  get:
    tags:
      - llmo
    summary: Get LLMO configuration
    description: |
      Retrieves the LLMO (Large Language Model Optimizer) configuration for a specific site.
      This endpoint retrieves the configuration directly from S3 storage. The configuration
      includes entities (categories, topics, aiTopics), brand aliases, and competitor information.
      Categories may include optional URLs for content matching.

      If a version parameter is provided, the specific version of the configuration will be
      retrieved. If the version does not exist, a 404 error will be returned. If no version
      is provided, the latest version will be returned, or a default configuration if none
      exists.
    operationId: getLlmoConfig
    responses:
      '200':
        description: LLMO configuration retrieved successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  $ref: './schemas.yaml#/LlmoConfig'
                version:
                  oneOf:
                    - type: string
                      example: "abc123def456"
                    - type: "null"
                  description: The S3 object version ID of the configuration, or null if default configuration is returned
              required:
                - config
                - version
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '404':
        $ref: './responses.yaml#/404-configuration-not-found-with-version'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  post:
    tags:
      - llmo
    summary: Update LLMO configuration
    description: |
      Updates the LLMO (Large Language Model Optimizer) configuration for a specific site.
      This operation completely overwrites the existing configuration with the provided payload.
      The payload is validated against the LLMO configuration schema before being stored in S3.
      The configuration must include entities, brands, and competitors sections.

      Categories can optionally include URLs that can be either exact URLs or URL prefixes
      (ending with /*) to match against specific content areas.
    operationId: postLlmoConfig
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoConfig'
    responses:
      '200':
        description: LLMO configuration updated successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  description: The S3 object version ID of the updated configuration
                  example: "abc123def456"
              required:
                - version
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-onboard:
  post:
    tags:
      - llmo
    summary: Onboard new customer to LLMO
    description: |
      Onboards a net new customer to LLMO (Large Language Model Optimizer).
      This endpoint handles the complete onboarding process including organization validation,
      site creation/validation, LLMO configuration setup, and initial analysis trigger.
      The IMS Organization ID is automatically extracted from the user's JWT token (sub property).
    operationId: onboardCustomer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              domain:
                type: string
                format: hostname
                description: The domain name to onboard (without protocol)
                example: "example.com"
              brandName:
                type: string
                description: The brand name for the site
                example: "Example Brand"
            required:
              - domain
              - brandName
    responses:
      '200':
        description: LLMO onboarding initiated successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: Success message
                  example: "LLMO onboarding initiated successfully"
                domain:
                  type: string
                  format: hostname
                  description: The domain name
                  example: "example.com"
                brandName:
                  type: string
                  description: The brand name
                  example: "Example Brand"
                imsOrgId:
                  type: string
                  description: The IMS Organization ID
                  example: "1234567890ABCDEF@AdobeOrg"
                organizationId:
                  type: string
                  format: uuid
                  description: The organization ID (created or existing)
                  example: "123e4567-e89b-12d3-a456-426614174000"
                siteId:
                  type: string
                  format: uuid
                  description: The created or existing site ID
                  example: "987fcdeb-51a2-43d1-9f12-345678901234"
                status:
                  type: string
                  enum: ["initiated", "in_progress", "completed", "failed"]
                  description: The onboarding status
                  example: "initiated"
                createdAt:
                  type: string
                  format: date-time
                  description: The timestamp when onboarding was initiated
                  example: "2025-01-15T10:30:00Z"
              required:
                - message
                - domain
                - brandName
                - imsOrgId
                - status
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '403':
        $ref: './responses.yaml#/403'
      '500':
        $ref: './responses.yaml#/500'
    security: []

llmo-offboard:
  parameters:
    - $ref: './parameters.yaml#/siteId'
  post:
    tags:
      - llmo
    summary: Offboard customer from LLMO
    description: |
      Offboards a customer from LLMO (Large Language Model Optimizer).
      This endpoint handles disabling audits and cleaning up LLMO configuration for a site.
      The site must have LLMO enabled and the user must have appropriate permissions.
    operationId: offboardCustomer
    responses:
      '200':
        description: LLMO offboarding completed successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: Success message
                  example: "LLMO offboarding completed successfully"
                siteId:
                  type: string
                  format: uuid
                  description: The site ID that was offboarded
                  example: "987fcdeb-51a2-43d1-9f12-345678901234"
                baseURL:
                  type: string
                  format: uri
                  description: The site's base URL
                  example: "https://example.com"
                status:
                  type: string
                  enum: ["completed", "failed"]
                  description: The offboarding status
                  example: "completed"
                completedAt:
                  type: string
                  format: date-time
                  description: The timestamp when offboarding was completed
                  example: "2025-01-15T10:30:00Z"
              required:
                - message
                - siteId
                - status
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '403':
        $ref: './responses.yaml#/403'
      '404':
        $ref: './responses.yaml#/404'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-questions:
  parameters:
    - $ref: './parameters.yaml#/siteId'
  get:
    tags:
      - llmo
    summary: Get LLMO questions
    description: |
      Retrieves all LLMO questions (both human and AI) for a specific site.
      Returns an object with Human and AI question arrays.
    operationId: getLlmoQuestions
    responses:
      '200':
        description: LLMO questions retrieved successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoQuestions'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  post:
    tags:
      - llmo
    summary: Add LLMO questions
    description: |
      Adds new questions to the LLMO configuration for a specific site.
      Questions can be added to both Human and AI categories.
    operationId: addLlmoQuestion
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoQuestionsInput'
    responses:
      '200':
        description: LLMO questions added successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoQuestions'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-question:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: questionKey
      in: path
      required: true
      description: The unique key of the question to modify
      schema:
        type: string
        format: uuid
        example: '123e4567-e89b-12d3-a456-426614174000'
  delete:
    tags:
      - llmo
    summary: Remove LLMO question
    description: |
      Removes a specific question from the LLMO configuration by its unique key.
      The question can be from either Human or AI categories.
    operationId: removeLlmoQuestion
    responses:
      '200':
        description: LLMO question removed successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoQuestions'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  patch:
    tags:
      - llmo
    summary: Update LLMO question
    description: |
      Updates a specific question in the LLMO configuration by its unique key.
      The question can be from either Human or AI categories.
    operationId: patchLlmoQuestion
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoQuestionUpdate'
    responses:
      '200':
        description: LLMO question updated successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoQuestions'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-customer-intent:
  parameters:
    - $ref: './parameters.yaml#/siteId'
  get:
    tags:
      - llmo
    summary: Get LLMO customer intent
    description: |
      Retrieves all LLMO customer intent key-value pairs for a specific site.
      Returns an array of customer intent items with key and value properties.
    operationId: getLlmoCustomerIntent
    responses:
      '200':
        description: LLMO customer intent retrieved successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoCustomerIntent'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  post:
    tags:
      - llmo
    summary: Add LLMO customer intent
    description: |
      Adds new customer intent items to the LLMO configuration for a specific site.
      Customer intent items are key-value pairs that define customer targeting and goals.
    operationId: addLlmoCustomerIntent
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoCustomerIntentInput'
    responses:
      '200':
        description: LLMO customer intent added successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoCustomerIntent'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-customer-intent-item:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: intentKey
      in: path
      required: true
      description: The unique key of the customer intent item to modify
      schema:
        type: string
        example: 'target_audience'
  delete:
    tags:
      - llmo
    summary: Remove LLMO customer intent item
    description: |
      Removes a specific customer intent item from the LLMO configuration by its key.
      The key should match an existing customer intent item.
    operationId: removeLlmoCustomerIntent
    responses:
      '200':
        description: LLMO customer intent item removed successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoCustomerIntent'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  patch:
    tags:
      - llmo
    summary: Update LLMO customer intent item
    description: |
      Updates a specific customer intent item in the LLMO configuration by its key.
      You can update either the key, value, or both properties.
    operationId: patchLlmoCustomerIntent
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: './schemas.yaml#/LlmoCustomerIntentUpdate'
    responses:
      '200':
        description: LLMO customer intent item updated successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoCustomerIntent'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-cdn-logs-filter:
  parameters:
    - $ref: './parameters.yaml#/siteId'
  patch:
    tags:
      - llmo
    summary: Update LLMO CDN logs filter configuration
    description: |
      Updates the CDN logs filter configuration for a specific site.
    operationId: patchLlmoCdnLogsFilter
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              cdnlogsFilter:
                $ref: './schemas.yaml#/LlmoCdnLogsFilter'
    responses:
      '200':
        description: LLMO CDN logs filter updated successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoCdnLogsFilter'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-cdn-logs-bucket-config:
  parameters:
    - $ref: './parameters.yaml#/siteId'
  patch:
    tags:
      - llmo
    summary: Update LLMO CDN bucket config configuration
    description: |
      Updates the CDN bucket config configuration for a specific site.
    operationId: patchLlmoCdnBucketConfig
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              cdnBucketConfig:
                $ref: './schemas.yaml#/LlmoCdnBucketConfig'
    responses:
      '200':
        description: LLMO CDN bucket config updated successfully
        content:
          application/json:
            schema:
              $ref: './schemas.yaml#/LlmoCdnBucketConfig'
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-rationale:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: topic
      in: query
      required: true
      description: The topic to filter by (case-insensitive partial match)
      schema:
        type: string
        example: 'Convert PDF_Informational'
    - name: category
      in: query
      required: false
      description: Optional category to filter topics by (case-insensitive partial match)
      schema:
        type: string
        example: 'Acrobat'
    - name: region
      in: query
      required: false
      description: Optional region to filter topics by (case-insensitive partial match)
      schema:
        type: string
        example: 'US'
    - name: origin
      in: query
      required: false
      description: Optional origin to filter topics by (case-insensitive partial match)
      schema:
        type: string
        example: 'HUMAN'
    - name: popularity
      in: query
      required: false
      description: Optional popularity level to filter topics by (case-insensitive partial match)
      schema:
        type: string
        example: 'High'
  get:
    tags:
      - llmo
    summary: Get LLMO rationale data
    description: |
      Retrieves filtered LLMO rationale data for a specific site. This endpoint fetches topics
      popularity reasoning data from the cached S3 file and applies filtering based on the provided query parameters.

      The endpoint requires mandatory 'topic' parameter for filtering, with optional
      'category', 'region', 'origin', and 'popularity' parameters for additional filtering. All text matching is case-insensitive
      and uses partial matching (contains).

      The data is sourced from the topics popularity reasoning cache file stored in S3 at:
      `llm_cache/{siteId}/topics_popularity_reasoning_cache.json`
    operationId: getLlmoRationale
    responses:
      '200':
        description: LLMO rationale data retrieved and filtered successfully
        content:
          application/json:
            schema:
              type: array
              description: Array of filtered topic objects matching the query criteria
              items:
                type: object
                properties:
                  topic:
                    type: string
                    description: The topic name
                    example: 'Convert PDF_Informational'
                  category:
                    type: string
                    description: The category of the topic
                    example: 'Acrobat'
                  region:
                    type: string
                    description: The region associated with the topic
                    example: 'BR'
                  origin:
                    type: string
                    description: The origin of the topic
                    example: 'HUMAN'
                  popularity:
                    type: string
                    description: The popularity level of the topic
                    example: 'Low'
                  volume:
                    type: number
                    description: The volume metric for the topic
                    example: -10
                  reasoning:
                    type: string
                    description: The reasoning for the topic's popularity classification
                    example: 'Specific informational query with minimal organic searches.'
                  added_date:
                    type: string
                    format: date-time
                    description: The date when the topic was added
                    example: '2025-12-03T09:21:31.673898'
                additionalProperties: true
      '400':
        description: Bad request - missing required parameters or invalid request
        content:
          application/json:
            schema:
              type: object
              properties:
                error:
                  type: string
                  examples:
                    missing_topic:
                      value: 'topic parameter is required'
                    s3_not_configured:
                      value: 'S3 storage is not configured for this environment'
                    invalid_json:
                      value: 'Invalid JSON format in rationale file'
                    bucket_not_found:
                      value: 'Storage bucket not found: spacecat-env-mystique-assets'
      '401':
        $ref: './responses.yaml#/401'
      '404':
        description: Rationale file not found for the specified site
        content:
          application/json:
            schema:
              type: object
              properties:
                error:
                  type: string
                  example: 'Rationale file not found for site 123e4567-e89b-12d3-a456-426614174000'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

site-llmo-edge-optimize-config:
  parameters:
    - $ref: './parameters.yaml#/siteId'
  post:
    operationId: createOrUpdateSiteLlmoEdgeConfig
    summary: |
      Create or update edge optimization configuration for an LLMO site
    description: |
      Creates or updates edge optimization configuration for the specified LLMO-enabled site.

      **Behavior:**
      - If metaconfig doesn't exist or has no API keys: Generates a unique API key and creates metaconfig in S3
      - If metaconfig exists with API keys: Updates the metaconfig in S3
      - Updates the site's edgeOptimizeConfig.enabled flag in the database

      The API key is generated using: SHA256(UUID + domain) encoded as base64url.

      **Note:** This endpoint requires LLMO access for the site.
    tags:
      - llmo
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    responses:
      '200':
        description: Edge config created/updated successfully. Returns the metaconfig object properties at root level.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: The metaconfig object stored in S3
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '403':
        $ref: './responses.yaml#/403'
      '404':
        $ref: './responses.yaml#/404'
      '429':
        $ref: './responses.yaml#/429'
      '500':
        $ref: './responses.yaml#/500'
      '503':
        $ref: './responses.yaml#/503'
    security:
      - ims_key: [ ]

  get:
    operationId: getSiteLlmoEdgeConfig
    summary: |
      Retrieve edge optimization configuration for an LLMO site
    description: |
      Fetches the existing edge optimization configuration for the specified LLMO-enabled site.
      Returns the metaconfig from S3.

      Returns an empty object if no edge config has been created for this site yet.

      **Note:** This endpoint requires LLMO access for the site.
    tags:
      - llmo
    responses:
      '200':
        description: Returns the metaconfig object
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: The metaconfig object stored in S3
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '403':
        $ref: './responses.yaml#/403'
      '404':
        $ref: './responses.yaml#/404'
      '429':
        $ref: './responses.yaml#/429'
      '500':
        $ref: './responses.yaml#/500'
      '503':
        $ref: './responses.yaml#/503'
    security:
      - ims_key: [ ]

site-llmo-edge-optimize-routing:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: x-promise-token
      in: header
      required: true
      description: Promise token exchanged for IMS user token to authorize the CDN API call.
      schema:
        type: string
  post:
    operationId: enableEdgeOptimize
    summary: Update edge optimize routing for a site
    description: |
      Updates edge optimize routing for the site via the internal CDN API. Only available when
      ENV is prod. The CDN API to call is selected by the required cdnType request body parameter.

      Flow:
      1. Validates request (x-promise-token header and cdnType required; enabled must be boolean if provided).
      2. Probes the site with User-Agent `AdobeEdgeOptimize-Test`. If 2xx, flow continues with probe URL domain.
         If 301, the Location header is checked: the probe URL hostname and the Location URL hostname are compared
         (lowercased, with leading www. stripped); subdomains are considered, so only the same host is allowed. If they
         match, the domain from the Location URL is used for the CDN API; otherwise the flow fails. Other non-2xx responses fail.
      3. Exchanges the promise token for IMS user token, then calls internal CDN API for the chosen cdnType to set routing for the domain.

    tags:
      - llmo
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [cdnType]
            properties:
              cdnType:
                type: string
                enum: [aem-cs-fastly]
                description: |
                  CDN / log source type (LOG_SOURCES). Determines which CDN API URL from
                  EDGE_OPTIMIZE_ROUTING_CONFIG is used. Currently supported for edge optimize: aem-cs-fastly.
              enabled:
                type: boolean
                default: true
                description: |
                  Whether to enable (true) or disable (false) edge optimize routing for the domain.
                  Omitted or true enables; false disables.
    responses:
      '200':
        description: Edge optimize routing updated successfully
        content:
          application/json:
            schema:
              type: object
              required: [enabled, domain, cdnType]
              properties:
                enabled:
                  type: boolean
                  description: The value that was set (true = enabled, false = disabled)
                  example: true
                domain:
                  type: string
                  example: www.example.com
                cdnType:
                  type: string
                  example: aem-cs-fastly
      '400':
        description: Bad request (e.g. non-prod ENV, missing/invalid x-promise-token or cdnType, invalid enabled, probe failed, non-2xx/301, or 301 Location domain mismatch)
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
      '401':
        description: Authentication failed with upstream IMS service (missing or invalid promise token)
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  example: Authentication failed with upstream IMS service
      '403':
        $ref: './responses.yaml#/403'
      '404':
        $ref: './responses.yaml#/404'
      '502':
        description: Upstream CDN API returned 5xx
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  example: Upstream call failed with status 503
      '503':
        description: API not available (EDGE_OPTIMIZE_ROUTING_CONFIG not set or invalid, or missing cdnRoutingUrl for cdnType)
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  example: API is missing mandatory environment variable
      '500':
        $ref: './responses.yaml#/500'
    security:
      - ims_key: [ ]

llmo-strategy:
  parameters:
    - $ref: './parameters.yaml#/siteId'
    - name: version
      in: query
      required: false
      description: Optional S3 version ID to retrieve a specific version of the strategy
      schema:
        type: string
        example: 'abc123def456'
  get:
    tags:
      - llmo
    summary: Get LLMO strategy
    description: |
      Retrieves the LLMO (Large Language Model Optimizer) strategy data for a specific site.
      The strategy is stored in S3 at `workspace/llmo/{siteId}/strategy.json` and can contain
      any valid JSON data without schema validation.

      If a version parameter is provided, the specific version of the strategy will be
      retrieved. If the strategy does not exist, a 404 error will be returned.
    operationId: getStrategy
    responses:
      '200':
        description: LLMO strategy retrieved successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  additionalProperties: true
                  description: The strategy data (any valid JSON object)
                version:
                  type: string
                  description: The S3 object version ID of the strategy
                  example: "abc123def456"
              required:
                - data
                - version
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '404':
        $ref: './responses.yaml#/404'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]
  put:
    tags:
      - llmo
    summary: Save LLMO strategy
    description: |
      Saves the LLMO (Large Language Model Optimizer) strategy data for a specific site.
      This operation completely overwrites the existing strategy with the provided payload.
      The payload can be any valid JSON object - no schema validation is performed.
      The strategy is stored in S3 at `workspace/llmo/{siteId}/strategy.json`.

      When status changes are detected (either at the strategy level or at the
      opportunity level), email notifications are sent to the relevant recipients.
      Initial strategy creation does not trigger strategy status emails. Assignment
      notifications go to the assignee only (not the strategy owner). Notification
      delivery is awaited, and a summary of sent/failed/skipped counts is included
      in the response. Notification failures do not cause the endpoint to return
      an error.
    operationId: saveStrategy
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
            description: Any valid JSON object to store as the strategy
    responses:
      '200':
        description: LLMO strategy saved successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  description: The S3 object version ID of the saved strategy
                  example: "abc123def456"
                notifications:
                  type: object
                  description: Summary of notification delivery
                  properties:
                    sent:
                      type: integer
                      description: Number of emails sent successfully
                    failed:
                      type: integer
                      description: Number of emails that failed to send
                    skipped:
                      type: integer
                      description: Number of changes skipped (e.g. no valid recipients)
                    changes:
                      type: integer
                      description: Number of status changes detected
              required:
                - version
                - notifications
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]

llmo-opportunities-reviewed:
  put:
    tags:
      - llmo
    summary: Mark opportunities as reviewed
    description: |
      Marks the LLMO opportunities for a site as reviewed by adding an
      `opportunitiesReviewed` tag to the site's LLMO configuration.
      The tag is idempotent — calling this endpoint multiple times will not
      create duplicate tags.
    operationId: markOpportunitiesReviewed
    parameters:
      - $ref: './parameters.yaml#/siteId'
    responses:
      '200':
        description: Opportunities marked as reviewed successfully
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              example:
                - opportunitiesReviewed
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '403':
        $ref: './responses.yaml#/403'
    security:
      - api_key: [ ]

llmo-edge-optimize-status:
  get:
    tags:
      - llmo
    summary: Check Edge Optimize status for a site path
    description: |
      Checks the edge optimization status for a specific path on a site.
      This endpoint queries the Edge Optimize service to determine whether edge optimization
      is active and configured for the given path.

      Returns information about:
      - Whether edge optimization is enabled for the site
      - Configuration status for the specific path
      - Any path-specific optimization settings
    operationId: checkEdgeOptimizeStatus
    parameters:
      - $ref: './parameters.yaml#/siteId'
      - name: path
        in: query
        description: The path to check optimization status for (defaults to '/')
        required: false
        schema:
          type: string
          default: '/'
          example: '/products/index.html'
    responses:
      '200':
        description: Edge optimize status retrieved successfully
        content:
          application/json:
            schema:
              type: object
              required:
                - edgeOptimizeEnabled
              properties:
                edgeOptimizeEnabled:
                  type: boolean
                  description: Whether Edge Optimize headers were detected in the HTTP response
              example:
                edgeOptimizeEnabled: true
      '400':
        $ref: './responses.yaml#/400'
      '401':
        $ref: './responses.yaml#/401'
      '403':
        $ref: './responses.yaml#/403'
      '404':
        $ref: './responses.yaml#/404'
      '500':
        $ref: './responses.yaml#/500'
    security:
      - api_key: [ ]