Algolia Personalization API

openapi: 3.2.0
info:
  title: Personalization API
  summary: The Personalization API lets you access user profiles built from the personalization strategy
  description: "## Base URLs\n\nBase URLs for the Personalization API:\n\n- `https://personalization.us.algolia.com`\n- `https://personalization.eu.algolia.com`\n\nUse the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).\n\n**All requests must use HTTPS.**\n\n## Authentication\n\nAdd these headers to authenticate requests:\n\n- `x-algolia-application-id`. Your Algolia application ID.\n- `x-algolia-api-key`. An API key with the necessary permissions to make the request.\n  The required access control list (ACL) to make a request is listed in each endpoint's reference.\n\nYou can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).\n\n## Request format\n\nRequest bodies must be JSON objects.\n\n## Response status and errors\n\nThe Personalization API returns JSON responses.\nSince JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.\n\nSuccessful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.\nError responses have a `message` property with more information.\n\n## Rate limiting\n\nWhen making requests to the Personalization API, you are limited to 40 API calls per second per application.\n\nThe following headers provide information about your current limit:\n\n- `x-ratelimit-limit`: The number of requests allowed every second.\n- `x-ratelimit-remaining`: The number of requests remaining in the current\nsecond period.\n- `x-ratelimit-reset`: Timestamp when the next time period starts, measured in seconds since the Unix epoch.\n\n## Version\n\nThe current version of the Personalization API is version 1, indicated by the `/1/` in each endpoint's URL.\n"
  version: 1.0.0
servers:
- url: https://personalization.{region}.algolia.com
  variables:
    region:
      description: The region where your Algolia application is hosted.
      enum:
      - us
      - eu
      default: us
security:
- appId: []
  apiKey: []
tags:
- name: personalization
paths:
  /{path}:
    get:
      operationId: customGet
      summary: Send requests to the Algolia REST API
      description: This method lets you 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 lets you 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 lets you 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 lets you 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: Retrieve a user profile
      description: Retrieves a user profile and their affinities for different facets.
      parameters:
      - $ref: '#/components/parameters/UserToken'
      responses:
        '200':
          description: OK
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          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: 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
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          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: Retrieve the personalization strategy
      description: Retrieves the current personalization strategy.
      responses:
        '200':
          description: OK
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          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: 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
      x-acl: []
      tags:
      - personalization
      operationId: setClientApiKey
      summary: 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 use for subsequent requests.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content.
components:
  schemas:
    facetsScoring:
      type: object
      additionalProperties: false
      required:
      - score
      - facetName
      properties:
        score:
          $ref: '#/components/schemas/score'
        facetName:
          type: string
          description: Facet attribute name.
    EventType:
      title: eventType
      type: string
      description: Event type.
      enum:
      - click
      - conversion
      - view
    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.

            '
    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'
    score:
      type: integer
      description: Event score.
    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
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
  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'
  parameters:
    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'
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, for example `1/newFeature`.
      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
  headers:
    x-ratelimit-reset:
      description: Timestamp when the rate limit will reset, measured in seconds since the Unix epoch.
      example: 1710682486
      schema:
        type: integer
    x-ratelimit-remaining:
      description: Number of remaining requests in the current period.
      example: 99
      schema:
        type: integer
    x-ratelimit-limit:
      description: Number of allowed requests per one minute.
      example: 100
      schema:
        type: integer
  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.

        '
externalDocs:
  url: https://www.algolia.com/doc/guides/personalization/what-is-personalization
  description: Algolia Personalization.
x-tagGroups:
- name: General
  tags:
  - profiles
  - strategies