openapi: 3.0.2
info:
  title: Algolia Personalization API
  description: >-
    The Algolia Personalization API is a powerful tool that allows businesses to
    deliver highly personalized search and recommendation experiences to their
    users. By harnessing machine learning algorithms, the API can analyze user
    behavior and preferences to deliver tailored search results and product
    recommendations in real-time. This leads to increased engagement, conversion
    rates, and customer satisfaction. Additionally, the API provides insights
    into user behavior and preferences, allowing businesses to make informed
    decisions to optimize their search and recommendation strategies. Overall,
    the Algolia Personalization API enables businesses to create a more
    customized and relevant experience for their users, ultimately driving
    better outcomes for their business.
  version: 1.0.0
servers:
  - url: https://personalization.{region}.algolia.com
    variables:
      region:
        enum:
          - us
          - eu
        default: us
security:
  - appId: []
    apiKey: []
tags:
  - name: Personalization
externalDocs:
  url: https://www.algolia.com/doc/guides/personalization/what-is-personalization/
  description: |
    Related guide: Algolia 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:
        - 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:
        - 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:
        - 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:
        - Personalization
  /1/profiles/personalization/{userToken}:
    get:
      tags:
        - Personalization
      operationId: getUserTokenProfile
      x-acl:
        - recommendation
      summary: Algolia Retrieve a user profile
      description: Retrieves a user profile and their affinities for different facets.
      parameters:
        - $ref: '#/components/parameters/UserToken'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: getUserTokenResponse
                type: object
                additionalProperties: false
                required:
                  - userToken
                  - scores
                  - lastEventAt
                properties:
                  userToken:
                    $ref: '#/components/schemas/userToken'
                  lastEventAt:
                    type: string
                    description: >-
                      Date and time of the last event from this user, in RFC
                      3339 format.
                  scores:
                    type: object
                    description: >
                      Scores for different facet values.


                      Scores represent the user affinity for a user profile
                      towards specific facet values,

                      given the personalization strategy and past events.
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
  /1/profiles/{userToken}:
    delete:
      tags:
        - Personalization
      operationId: deleteUserProfile
      x-acl:
        - recommendation
      summary: Algolia Delete a user profile
      description: >
        Deletes a user profile.


        The response includes a date and time when the user profile can safely
        be considered deleted.
      parameters:
        - $ref: '#/components/parameters/UserToken'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: deleteUserProfileResponse
                type: object
                additionalProperties: false
                required:
                  - userToken
                  - deletedUntil
                properties:
                  userToken:
                    $ref: '#/components/schemas/userToken'
                  deletedUntil:
                    type: string
                    description: >
                      Date and time when the user profile can be safely
                      considered to be deleted.

                      Any events received after the `deletedUntil` date start a
                      new user profile.
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
  /1/strategies/personalization:
    get:
      tags:
        - Personalization
      operationId: getPersonalizationStrategy
      x-acl:
        - recommendation
      summary: Algolia Retrieve the personalization strategy
      description: Retrieves the current personalization strategy.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personalizationStrategyParams'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
    post:
      tags:
        - Personalization
      operationId: setPersonalizationStrategy
      x-acl:
        - recommendation
      summary: Algolia Define the personalization strategy
      description: Creates a new personalization strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personalizationStrategyParams'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: setPersonalizationStrategyResponse
                type: object
                additionalProperties: false
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A message confirming the strategy update.
                    example: Strategy was successfully updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
  /setClientApiKey:
    get:
      x-helper: true
      x-asynchronous-helper: false
      tags:
        - Personalization
      operationId: setClientApiKey
      summary: Algolia Switch the API key used to authenticate requests
      description: |
        Switch the API key used to authenticate requests.
      parameters:
        - in: query
          name: apiKey
          description: API key to be used from now on.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content.
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
    UserToken:
      name: userToken
      in: path
      required: true
      description: >-
        Unique identifier representing a user for which to fetch the
        personalization profile.
      schema:
        $ref: '#/components/schemas/userToken'
  schemas:
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    userToken:
      type: string
      description: >
        Unique pseudonymous or anonymous user identifier.


        This helps with analytics and click and conversion events.

        For more information, see [user
        token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/).
      example: test-user-123
      x-categories:
        - Personalization
    score:
      type: integer
      description: Event score.
    EventType:
      title: eventType
      type: string
      description: Event type.
      enum:
        - click
        - conversion
        - view
    eventsScoring:
      type: object
      additionalProperties: false
      required:
        - score
        - eventName
        - eventType
      properties:
        score:
          $ref: '#/components/schemas/score'
        eventName:
          type: string
          description: Event name.
        eventType:
          $ref: '#/components/schemas/EventType'
    facetsScoring:
      type: object
      additionalProperties: false
      required:
        - score
        - facetName
      properties:
        score:
          $ref: '#/components/schemas/score'
        facetName:
          type: string
          description: Facet attribute name.
    personalizationStrategyParams:
      type: object
      additionalProperties: false
      required:
        - eventsScoring
        - facetsScoring
        - personalizationImpact
      properties:
        eventsScoring:
          type: array
          description: >
            Scores associated with each event.


            The higher the scores, the higher the impact of those events on the
            personalization of search results.
          items:
            $ref: '#/components/schemas/eventsScoring'
        facetsScoring:
          type: array
          description: >
            Scores associated with each facet.


            The higher the scores, the higher the impact of those events on the
            personalization of search results.
          items:
            $ref: '#/components/schemas/facetsScoring'
        personalizationImpact:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            Impact of personalization on the search results.

            If set to 0, personalization has no impact on the search results.
  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'
x-tagGroups:
  - name: General
    tags:
      - profiles
      - strategies