The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Skip to main content
API docs by Redocly

Personalization API (1.0.0)

Download OpenAPI specification:Download

The Personalization API lets you access user profiles built from the personalization strategy.

Related guide: Algolia Personalization.

Base URLs

The base URLs for requests to the Personalization API are:

  • https://personalization.us.algolia.com
  • https://personalization.eu.algolia.com

Use the URL that matches your analytics region.

All requests must use HTTPS.

Authentication

To authenticate your API requests, add these headers:

  • x-algolia-application-id. Your Algolia application ID.
  • x-algolia-api-key. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference.

You can find your application ID and API key in the Algolia dashboard.

Request format

Request bodies must be JSON objects.

Response status and errors

The Personalization API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.

Successful responses return a 2xx status. Client errors return a 4xx status. Server errors are indicated by a 5xx status. Error responses have a message property with more information.

Version

The current version of the Personalization API is version 1, as indicated by the /1/ in each endpoint's URL.

Profiles

User profiles represent the affinities each user profile has for the different facets in your index. The more a user viewed and clicked search results with a specific facet, the higher the affinity for that facet.

Retrieve a user profile

Retrieves a user profile and their affinities for different facets.

acl: ["recommendation"]
path Parameters
userToken
required
string
Example: test-user-123

Unique identifier representing a user for which to fetch the personalization profile.

Responses

Request samples 

// Initialize the client
var client = new PersonalizationClient(
  new PersonalizationConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.GetUserTokenProfileAsync("UserToken");

Response samples

Content type
application/json
{
  • "userToken": "test-user-123",
  • "lastEventAt": "string",
  • "scores": { }
}

Delete a user profile

Deletes a user profile.

The response includes a date and time when the user profile can safely be considered deleted.

acl: ["recommendation"]
path Parameters
userToken
required
string
Example: test-user-123

Unique identifier representing a user for which to fetch the personalization profile.

Responses

Request samples 

// Initialize the client
var client = new PersonalizationClient(
  new PersonalizationConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.DeleteUserProfileAsync("UserToken");

Response samples

Content type
application/json
{
  • "userToken": "test-user-123",
  • "deletedUntil": "string"
}

Strategies

The personalization strategy defines how personalization should affect the search results, and how much each facet and event type impact the personalization.

Retrieve the personalization strategy

Retrieves the current personalization strategy.

acl: ["recommendation"]

Responses

Request samples 

// Initialize the client
var client = new PersonalizationClient(
  new PersonalizationConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.GetPersonalizationStrategyAsync();

Response samples

Content type
application/json
{
  • "eventScoring": [
    ],
  • "facetScoring": [
    ],
  • "personalizationImpact": 100
}

Define the personalization strategy

Creates a new personalization strategy.

acl: ["recommendation"]
Request Body schema: application/json
required
required
Array of objects

Scores associated with each event.

The higher the scores, the higher the impact of those events on the personalization of search results.

required
Array of objects

Scores associated with each facet.

The higher the scores, the higher the impact of those events on the personalization of search results.

personalizationImpact
required
integer [ 0 .. 100 ]

Impact of personalization on the search results.

If set to 0, personalization has no impact on the search results.

Responses

Request samples 

// Initialize the client
var client = new PersonalizationClient(
  new PersonalizationConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.SetPersonalizationStrategyAsync(
  new PersonalizationStrategyParams
  {
    EventScoring = new List<EventScoring>
    {
      new EventScoring
      {
        Score = 42,
        EventName = "Algolia",
        EventType = Enum.Parse<EventType>("Click"),
      }
    },
    FacetScoring = new List<FacetScoring>
    {
      new FacetScoring { Score = 42, FacetName = "Event", }
    },
    PersonalizationImpact = 42,
  }
);

Response samples

Content type
application/json
{
  • "message": "Strategy was successfully updated."
}