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

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /{path} Send a raw GET request to the Personalization API · Send requests to the Algolia REST API #
Ask an LLM
“Can I read a Personalization endpoint that the client library doesn't wrap?”
“Is there a generic way to GET any Personalization API path with custom query parameters?”
Tell an agent
Send a raw GET request to Personalization API path {path}.
Fetch Personalization path {path} with query parameters {parameters}.
POST /{path} Send a raw POST request to the Personalization API · Send requests to the Algolia REST API #
Ask an LLM
“Can I POST to a Personalization endpoint the SDK doesn't expose as a method?”
“What's the generic escape hatch for posting to any Personalization API path?”
Tell an agent
Send a raw POST request to Personalization API path {path}.
POST to Personalization path {path} with query parameters {parameters}.
PUT /{path} Send a raw PUT request to the Personalization API · Send requests to the Algolia REST API #
Ask an LLM
“Can I send a custom PUT to a Personalization path that has no dedicated method?”
“Is there a passthrough for replacing a resource on an arbitrary Personalization endpoint?”
Tell an agent
Send a raw PUT request to Personalization API path {path}.
PUT to Personalization path {path} with query parameters {parameters}.
DELETE /{path} Send a raw DELETE request to the Personalization API · Send requests to the Algolia REST API #
Ask an LLM
“Can I issue a DELETE against an arbitrary Personalization API path?”
“Is there a generic delete call for Personalization endpoints without a dedicated method?”
Tell an agent destructive · confirm first
Send a raw DELETE request to Personalization API path {path}.
DELETE Personalization path {path} with query parameters {parameters}.
GET /1/profiles/personalization/{userToken} Get a user's personalization profile and affinities · Retrieve a user profile #
Ask an LLM
“Which facet values does a particular shopper have the strongest affinity for?”
“How do I look up what Algolia Personalization has learned about one user token?”
Tell an agent
Show the personalization profile and facet affinities for user token {userToken}.
Get the facet affinities recorded for user {userToken}.
DELETE /1/profiles/{userToken} Delete a user's personalization profile · Delete a user profile #
Ask an LLM
“How do I erase a user's personalization profile, for example after a privacy request?”
“When can I consider a deleted personalization profile actually gone?”
Tell an agent destructive · confirm first
Delete the personalization profile for user token {userToken}.
Erase everything Personalization stored about user {userToken} and tell me when deletion is final.
GET /1/strategies/personalization Get the current personalization strategy · Retrieve the personalization strategy #
Ask an LLM
“What events and facets is my personalization strategy currently scoring?”
“How strong is the personalization impact set on my application right now?”
Tell an agent
Show my current personalization strategy.
Tell me the event scores, facet scores and impact in the active personalization strategy.
POST /1/strategies/personalization Define the personalization strategy · Define the personalization strategy #
Ask an LLM
“How do I tell Personalization which events and facets should drive ranking?”
“Can I dial down how much personalization affects search results?”
Tell an agent
Set the personalization strategy with event scoring {eventsScoring}, facet scoring {facetsScoring} and impact {personalizationImpact}.
Change the personalization impact to {personalizationImpact} while keeping events {eventsScoring} and facets {facetsScoring}.
GET /setClientApiKey Switch the API key the Personalization client uses · Switch the API key used to authenticate requests #
Ask an LLM
“Can I change which API key my Personalization client authenticates with?”
“How do I rotate the key an existing Personalization client sends?”
Tell an agent
Switch the Personalization client to authenticate with API key {apiKey}.
Use {apiKey} for all further Personalization API 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: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:
  schemas:
    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.
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    EventType:
      title: eventType
      type: string
      description: Event type.
      enum:
      - click
      - conversion
      - view
    facetsScoring:
      type: object
      additionalProperties: false
      required:
      - score
      - facetName
      properties:
        score:
          $ref: '#/components/schemas/score'
        facetName:
          type: string
          description: Facet attribute name.
    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
    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.

            '
  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-limit:
      description: Number of allowed requests per one minute.
      example: 100
      schema:
        type: integer
    x-ratelimit-remaining:
      description: Number of remaining requests in the current period.
      example: 99
      schema:
        type: integer
  responses:
    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'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
  parameters:
    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'
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, for example `1/newFeature`.
      required: true
      schema:
        type: string
        example: /keys
  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