Algolia

Algolia Personalization API

Configures and applies user-affinity profiles built from Insights events to re-rank search and browse results per user.

GitHub OpenAPI

Operations 9

GET /{path} Send requests to the Algolia REST API #
POST /{path} Send requests to the Algolia REST API #
PUT /{path} Send requests to the Algolia REST API #
DELETE /{path} Send requests to the Algolia REST API #
GET /1/profiles/personalization/{userToken} Retrieve a user profile #
DELETE /1/profiles/{userToken} Delete a user profile #
GET /1/strategies/personalization Retrieve the personalization strategy #
POST /1/strategies/personalization Define the personalization strategy #
GET /setClientApiKey Switch the API key used to authenticate requests #

Documentation

📖
Documentation
https://www.algolia.com/doc/rest-api/personalization/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/algolia/refs/heads/main/openapi/algolia-personalization-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/algolia/refs/heads/main/json-schema/algolia-personalization-strategy-params-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/algolia/refs/heads/main/json-schema/algolia-user-token-schema.json

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/algolia/refs/heads/main/overlays/algolia-personalization-api-overlay.yaml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/algolia-personalization-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

algolia-personalization-api-openapi.yml Raw ↑ 
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


    Base URLs for the Personalization API:


    - `https://personalization.us.algolia.com`

    - `https://personalization.eu.algolia.com`


    Use the URL that matches your analytics region.'
  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:
  headers:
    x-ratelimit-limit:
      description: Number of allowed requests per one minute.
      example: 100
      schema:
        type: integer
    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
  parameters:
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, for example `1/newFeature`.
      required: true
      schema:
        type: string
        example: /keys
    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'
    Parameters:
      name: parameters
      in: query
      description: Query parameters to apply to the current query.
      schema:
        type: object
        additionalProperties: true
  schemas:
    EventType:
      title: eventType
      type: string
      description: Event type.
      enum:
      - click
      - conversion
      - view
    score:
      type: integer
      description: Event score.
    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.

            '
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    facetsScoring:
      type: object
      additionalProperties: false
      required:
      - score
      - facetName
      properties:
        score:
          $ref: '#/components/schemas/score'
        facetName:
          type: string
          description: Facet attribute name.
    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'
    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
  responses:
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    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'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
  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