openapi: 3.0.0
info:
  title: Akeneo - PX Insights API
  description: |
    The PX Insights API allows external systems to push customer insights — such as product reviews and search terms — into the Akeneo Product Experience Management (PXM) platform.

    These insights are then made available within the Akeneo PIM, where they can be leveraged by product teams to better understand customer behavior, improve product content, and enrich the product experience.

    All incoming data is processed and linked to products via UUIDs, product model codes, or reconciliation mechanisms. An asynchronous ingestion endpoint is available.
  version: 1.0.0

# Define top-level tags to group operations by domain
tags:
  - name: Reviews
    description: Operations related to product reviews and ratings

# Import paths from separate files
paths:
  # Reviews API endpoints
  /api/v1/reviews/ingest/async:
    $ref: "./schemas/reviews.yml#/paths/~1api~1v1~1reviews~1ingest~1async"
  /api/v1/reviews/ingest:
    $ref: "./schemas/reviews.yml#/paths/~1api~1v1~1reviews~1ingest"

security:
  - pimAccessToken: []

components:
  parameters:
    X-PIM-URL:
      name: X-PIM-URL
      in: header
      required: true
      schema:
        type: string
        format: uri
      description: Base URL of the PIM instance (e.g. https://my-pim.cloud.akeneo.com)
    X-PIM-TOKEN:
      name: X-PIM-TOKEN
      in: header
      required: true
      schema:
        type: string
      description: PIM API token used for authentication
    X-PIM-CLIENT-ID:
      name: X-PIM-CLIENT-ID
      in: header
      required: true
      schema:
        type: string
      description: Client ID used coming from the PIM

  securitySchemes:
    pimAccessToken:
      type: apiKey
      description: Valid PIM API Access Token
      in: header
      name: X-PIM-TOKEN

  schemas:
    # Common schemas
    ApiErrorResponse:
      type: object
      description: Represents the response you will receive in case of error
      properties:
        errors:
          type: array
          items:
            properties:
              message:
                type: string
                description: The detail about the error
      example:
        errors: [message: error message]

    # Reference to domain-specific schemas
    # Reviews
    IngestRequest:
      $ref: "./schemas/reviews.yml#/components/schemas/IngestRequest"
    RawReviewRequest:
      $ref: "./schemas/reviews.yml#/components/schemas/RawReviewRequest"
    breakdown:
      $ref: "./schemas/reviews.yml#/components/schemas/breakdown"

  responses:
    "400":
      description: Bad Request – The request payload is malformed or required fields are missing.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            malformed:
              value:
                errors: ["message": "Validation failed: one or more required fields are missing or invalid."]
    "401":
      description: Unauthorized – Authentication failed or tenant context is missing.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            unauthorized:
              value:
                errors: ["message": "Unauthorized: invalid API key or tenant context not found."]
    "403":
      description: Forbidden – The client is authenticated but not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            notAllowed:
              value:
                errors: ["message": "You are not allowed to perform this action."]
    "404":
      description: Not Found – The specified product or product model could not be found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            subscriptionNotFound:
              value:
                errors: ["message": "No matching product or product model found for the provided identifier."]
    "409":
      description: Conflict – The current system state prevents the request from being processed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            subscriptionDeleted:
              value:
                errors: ["message": "Cannot add more reviews for this tenant."]

    "500":
      description: Internal Server Error – An unexpected error occurred. Retry the request later.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            subscriptionDeleted:
              value:
                errors: ["message": "Internal server error. Please try again later."]
