openapi: 3.1.0
info:
  title: Algolia Advanced Personalization API
  description: >-
    Algolia Advanced Personalization API is a powerful tool that allows
    businesses to create personalized search and discovery experiences for their
    users. By leveraging machine learning algorithms, the API analyzes user
    behavior and preferences to deliver highly relevant search results and
    recommendations in real-time. This helps businesses increase user
    engagement, conversion rates, and overall customer satisfaction. With
    features such as dynamic filtering, query rules, and personalization
    strategies, the Algolia Advanced Personalization API empowers businesses to
    create tailored experiences that drive customer loyalty and revenue growth. 
  version: 2.0.0
servers:
  - url: https://ai-personalization.{region}.algolia.com
    variables:
      region:
        description: >
          Use the URL that matches your [analytics
          region](https://dashboard.algolia.com/account/infrastructure/analytics).
        enum:
          - eu
          - us
        default: eu
security:
  - appId: []
    apiKey: []
tags:
  - name: Advanced-Personalization
externalDocs:
  url: >-
    https://www.algolia.com/doc/guides/personalization/ai-personalization/what-is-ai-personalization/
paths:
  /{path}:
    get:
      operationId: customGet
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Advanced-Personalization
    post:
      operationId: customPost
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Advanced-Personalization
    put:
      operationId: customPut
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Advanced-Personalization
    delete:
      operationId: customDelete
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Advanced-Personalization
  /2/config:
    get:
      tags:
        - Advanced-Personalization
      operationId: getConfig
      x-acl:
        - search
        - browse
        - recommendation
      summary: Algolia Retrieve the configuration
      description: Retrieves a list of configuration objects for each index.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/configurationObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - Advanced-Personalization
      operationId: putConfig
      x-acl:
        - search
        - browse
        - recommendation
      summary: Algolia Update the configuration
      description: >
        Updates the configuration.


        The configuration is a list of configuration objects for each index. To
        configure Advanced Personalization for an index, create a new
        configuration object for the index.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: configurationParameters
              type: object
              properties:
                indices:
                  type: array
                  items:
                    title: configurationParametersObject
                    type: object
                    properties:
                      index:
                        type: string
                      affinities:
                        type: array
                        items:
                          type: string
                      source:
                        title: source
                        type: object
                        properties:
                          type:
                            $ref: '#/components/schemas/sourceType'
                          events:
                            $ref: '#/components/schemas/events'
                        required:
                          - type
                  required:
                    - index
                    - affinities
                    - source
                personalizationReRanking:
                  $ref: '#/components/schemas/personalizationReRanking'
                profileType:
                  $ref: '#/components/schemas/profileType'
              required:
                - indices
                - personalizationReRanking
                - profileType
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: putConfigResponse
                type: object
                properties:
                  status:
                    type: number
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/issue'
                  warnings:
                    type: array
                    items:
                      $ref: '#/components/schemas/issue'
                  message:
                    type: string
                required:
                  - status
                  - errors
                  - warnings
                  - message
        '400':
          $ref: '#/components/responses/BadRequest-2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /2/users:
    get:
      tags:
        - Advanced-Personalization
      operationId: getUsers
      x-acl:
        - search
        - browse
        - recommendation
      summary: Algolia Get a list of user profiles
      description: >-
        Retrieves a list of user profiles in [lexicographical
        order](https://www.educative.io/answers/what-is-a-lexicographic-order).
      parameters:
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/affinity'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/nextPageToken'
        - $ref: '#/components/parameters/previousPageToken'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: getUsersResponse
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/user'
                  previousPageToken:
                    type: string
                  nextPageToken:
                    type: string
                required:
                  - users
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/GenericUnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /2/users/{userID}:
    get:
      tags:
        - Advanced-Personalization
      operationId: getUser
      x-acl:
        - search
        - browse
        - recommendation
      summary: Algolia Get a user profile
      description: Retrieves a user profile.
      parameters:
        - $ref: '#/components/parameters/userID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        '400':
          $ref: '#/components/responses/BadUserID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/GenericNotFound'
        '422':
          $ref: '#/components/responses/InvalidUserID'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Advanced-Personalization
      operationId: deleteUser
      x-acl:
        - search
        - browse
        - recommendation
      summary: Algolia Delete a user profile
      description: Deletes a user profile.
      parameters:
        - $ref: '#/components/parameters/userID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: deleteUserResponse
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: integer
                  userID:
                    type: string
                  deletedUntil:
                    type: string
                  deletedAt:
                    type: string
        '400':
          $ref: '#/components/responses/BadUserID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/InvalidUserID'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-algolia-application-id
      description: Your Algolia application ID.
    apiKey:
      type: apiKey
      in: header
      name: x-algolia-api-key
      description: >
        Your Algolia API key with the necessary permissions to make the request.

        Permissions are controlled through access control lists (ACL) and access
        restrictions.

        The required ACL to make a request is listed in each endpoint's
        reference.
  parameters:
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, anything after "/1" must be specified.
      required: true
      schema:
        type: string
        example: /keys
    Parameters:
      name: parameters
      in: query
      description: Query parameters to apply to the current query.
      schema:
        type: object
        additionalProperties: true
    startDate:
      name: startDate
      description: |
        Filter users by start date (in RFC3339 format).
        Only users that were updated after the passed date will be returned.
      in: query
      schema:
        type: string
        example: '2024-06-27T08:27:26Z'
    endDate:
      name: endDate
      description: |
        Filter users by end date (in RFC3339 format).
        Only users that were updated before the passed date will be returned.
      in: query
      schema:
        type: string
        example: '2024-06-28T08:27:26Z'
    indices:
      name: indices
      description: |
        Filter users by matching indices.
        If multiple indices are passed, returned users will match all indices.
      in: query
      schema:
        type: array
        items:
          type: string
      examples:
        singleIndex:
          value:
            - products_EN
          summary: Filter by single index
        multipleIndices:
          value:
            - products_EN
            - products_FR
          summary: Filter by multiple indices
      style: form
      explode: false
    affinity:
      name: affinity
      description: |
        Filter users by affinity name and value.
        If multiple values are passed, returned users will match all values.
      in: query
      schema:
        type: array
        items:
          type: string
      examples:
        affinityName:
          value: brand
          summary: Filter by single affinity name
        affinityValuePair:
          value: brand:Nike
          summary: Filter by single affinity name and value
        multipleAffinityNames:
          value: brand,color
          summary: Filter by multiple affinity names
        multipleAffinityValuePairs:
          value: brand:Nike,color:white
          summary: Filter by multiple affinity name and value pairs
    limit:
      name: limit
      description: |
        Limit the number of users in the response.
        The value of this parameter ranges from 1 to 1000.
      in: query
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 1000
    nextPageToken:
      name: nextPageToken
      description: |
        Reference for the next page, when navigating forward using pagination.
        Can't be used in the same request as `previousPageToken`.
      in: query
      schema:
        type: string
    previousPageToken:
      name: previousPageToken
      description: >
        Reference for the previous page, when navigating backward using
        pagination.

        Can't be used in the same request as `nextPageToken`.
      in: query
      schema:
        type: string
    userID:
      name: userID
      description: ID of the user.
      in: path
      required: true
      schema:
        type: string
  schemas:
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    sourceType:
      title: type
      type: string
      enum:
        - insights
    eventType:
      type: string
      enum:
        - view
        - click
        - conversion
    subtype:
      type: string
      enum:
        - addToCart
        - purchase
    event:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/eventType'
        subtype:
          $ref: '#/components/schemas/subtype'
        name:
          type: string
      required:
        - type
        - name
    events:
      type: object
      properties:
        viewDetails:
          type: array
          items:
            $ref: '#/components/schemas/event'
        viewListing:
          type: array
          items:
            $ref: '#/components/schemas/event'
        addToCart:
          type: array
          items:
            $ref: '#/components/schemas/event'
        purchase:
          type: array
          items:
            $ref: '#/components/schemas/event'
      required:
        - viewDetails
        - viewListing
        - addToCart
        - purchase
    issue:
      type: object
      description: >-
        An issue is either an 'error' or a 'warning' that is generated by the
        validator.
      properties:
        code:
          type: string
        index:
          type: string
        message:
          type: string
      required:
        - code
        - index
        - message
    personalizationReRanking:
      type: string
      description: The impact that personalization has on the re-ranking of search results.
      enum:
        - none
        - low
        - medium
        - high
        - maximum
    profileType:
      type: string
      enum:
        - basic
      description: >
        The type of user profiles to generate.


        Basic profiles are based on past behaviors, ensuring search results
        align with previous interests.
    status:
      title: status
      type: string
      enum:
        - pending
        - active
        - paused
    errorCodes:
      title: errorCodes
      type: string
      enum:
        - blocked
        - deleted
        - no_perso_access
        - all_attr_value_filtered
        - missing_index
        - no_events_last_30_days
        - pending_pipelines
        - invalid_config
        - all_facets_invalid
    Configuration_status:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/status'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errorCodes'
        lastUpdatedAt:
          type: string
    configurationObject:
      type: object
      properties:
        indices:
          type: array
          items:
            title: configurationObject
            type: object
            properties:
              index:
                type: string
              affinities:
                type: array
                items:
                  type: string
              source:
                title: source
                type: object
                properties:
                  type:
                    $ref: '#/components/schemas/sourceType'
                  events:
                    $ref: '#/components/schemas/events'
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/issue'
              warnings:
                type: array
                items:
                  $ref: '#/components/schemas/issue'
              lastUpdatedAt:
                type: string
            required:
              - index
              - affinities
              - source
              - errors
              - warnings
              - lastUpdatedAt
        personalizationReRanking:
          $ref: '#/components/schemas/personalizationReRanking'
        profileType:
          $ref: '#/components/schemas/profileType'
        status:
          $ref: '#/components/schemas/Configuration_status'
      required:
        - indices
        - personalzationReRanking
        - profileType
        - status
    unauthorized:
      type: integer
      description: HTTP status code for an authorization error.
      enum:
        - 401
    ErrorMessages_unauthorized:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - Unauthorized
    ErrorResponses_unauthorized:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/unauthorized'
        message:
          $ref: '#/components/schemas/ErrorMessages_unauthorized'
    internalServerError:
      type: integer
      description: HTTP status code for an internal server error.
      enum:
        - 500
    ErrorMessages_internalServerError:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - Internal Server Error
    ErrorResponses_internalServerError:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/internalServerError'
        message:
          $ref: '#/components/schemas/ErrorMessages_internalServerError'
    badRequest:
      type: integer
      description: HTTP status code for a bad request error.
      enum:
        - 400
    ErrorMessages_badRequest:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - Invalid request body
    ErrorResponses_badRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/badRequest'
        message:
          $ref: '#/components/schemas/ErrorMessages_badRequest'
    user:
      type: object
      properties:
        userID:
          type: string
        affinities:
          type: array
          items:
            title: affinity
            type: object
            properties:
              name:
                type: string
              indices:
                type: array
                items:
                  type: string
                  minimum: 1
              value:
                type: string
              score:
                type: number
                minimum: 1
                maximum: 20
              lastUpdatedAt:
                type: string
            required:
              - name
              - indices
              - value
              - score
              - lastUpdatedAt
        lastUpdatedAt:
          type: string
      required:
        - userID
        - affinities
        - lastUpdatedAt
    unprocessableEntity:
      type: integer
      description: HTTP status code for an unprocessable entity error.
      enum:
        - 422
    genericUnprocessableEntity:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - Unprocessable Entity
    ErrorResponses_genericUnprocessableEntity:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/unprocessableEntity'
        message:
          $ref: '#/components/schemas/genericUnprocessableEntity'
    badUserID:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - Invalid userID format
    ErrorResponses_badUserID:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/badRequest'
        message:
          $ref: '#/components/schemas/badUserID'
    notFound:
      type: integer
      description: HTTP status code for a not found error.
      enum:
        - 404
    genericNotFound:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - Not Found
    ErrorResponses_genericNotFound:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/notFound'
        message:
          $ref: '#/components/schemas/genericNotFound'
    invalidUserID:
      type: string
      description: Details about the response, such as error messages.
      enum:
        - UserID must contain only alphanumeric
        - equal
        - plus
        - slash
        - hyphen
        - or underscore characters
        - and be between 1 and 129 characters long
    ErrorResponses_invalidUserID:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/unprocessableEntity'
        message:
          $ref: '#/components/schemas/invalidUserID'
  responses:
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    Unauthorized:
      description: Not authorized to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_unauthorized'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_internalServerError'
    BadRequest-2:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_badRequest'
    GenericUnprocessableEntity:
      description: Unprocessable entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_genericUnprocessableEntity'
    BadUserID:
      description: Bad user ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_badUserID'
    GenericNotFound:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_genericNotFound'
    InvalidUserID:
      description: Invalid user ID format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponses_invalidUserID'
x-tagGroups:
  - name: Advanced Personalization
    tags:
      - config
      - users