API reference / AI Personalization API

May. 27, 2024

AI Personalization API

Algolia’s Service Level Agreement doesn’t cover using the REST APIs directly.

Base URLs

The AI Personalization API can be reached from multiple domains, each specific to a region.

Use the domain that matches the region where your analytics data is stored and processed:

Copy
https://ai-personalization.eu.algolia.com
https://ai-personalization.us.algolia.com

Authentication

To authenticate your requests, add these headers:

X-Algolia-Application-Id: your Algolia application ID
X-Algolia-API-Key: your API key with search, browse, and recommendation ACL permissions

Find your application ID and API key in the Algolia dashboard.

Rate limiting

When making calls to the AI Personalization API, you are limited to 500 API calls per minute per app.

The following headers provide information about your current limit:

X-RateLimit-Limit: The number of requests allowed every 60-seconds.
X-RateLimit-Remaining: The number of requests remaining in the current 60-second period.
X-RateLimit-Reset: Unix timestamp of the next time period.

Response format

The responses of all AI Personalization API endpoints are JSON objects encoded in UTF-8.

The body of POST and PUT requests must be a JSON object and their Content-Type header should be set to application/json; charset=UTF-8.

The body of responses is always a JSON object, and their content type is always application/json; charset=UTF-8.

The AI Personalization API uses the conventional HTTP status codes:

Code	Description
`200`	The request was successful
`4xx`	Your request has at least one issue, such as a missing or invalid parameter
`5xx`	The AI Personalization API servers have an issue

Endpoints

Users endpoints

Quick reference

Verb	Path	Method
GET	/2/users	Get a list of user profiles
GET	/2/users/`{userID}`	Get a user profile
DELETE	/2/users/`{userID}`	Delete a user profile

Get a list of user profiles

Path: /2/users
HTTP Verb: GET
Required API Key: Any key with the search, browse, and recommendation ACLs

Description:

Get a paginated list of user profiles in lexicographical order.

Parameters:

Parameter	Description
`affinity`	type: string Return only users with specific affinities. Can be used multiple times in the same request to return multiple affinities.
`limit`	type: number default: 10 Limit the number of users in the response.
`nextPageToken`	type: URL encoded string Reference for the next page, when navigating forward using pagination. Can’t be used in the same request as `previousPageToken`.
`previousPageToken`	type: URL encoded string Reference for the previous page, when navigating backward using pagination. Can’t be used in the same request as `nextPageToken`.

Errors:

400: Bad Request
401: Unauthorized
500: Internal Error

Example:

Copy
curl "${BASE_URL}/2/users?affinity=color&limit=1&nextPageToken=dXNlcjE%3D" \
  -X GET \
  -H "X-Algolia-API-Key: ${API_KEY}" \
  -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \

Response:

Copy
{
  "users": [
    {
      "userID": "anonymous-62f2f24a-668f-11ee-8c99-0242ac120002",
      "affinities": [
        {
          "name": "color",
          "indices": ["products_EN"],
          "value": "red",
          "score": 8,
          "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
        },
        {
          "name": "color",
          "indices": ["products_EN"],
          "value": "blue",
          "score": 3,
          "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
        },
        {
          "name": "size",
          "indices": ["products_EN"],
          "value": "large",
          "score": 10,
          "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
        }
      ],
      "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
    }
  ],
  "previousPageToken": "dXNlcjI=",
  "nextPageToken": "dXNlcjQ="
}

Get a user profile

Path: /2/users/{userID}
HTTP Verb: GET
Required API Key: Any key with the search, browse, and recommendation ACLs

Description:

Get a user profile.

Errors:

400: Bad Request
401: Unauthorized
404: Not Found
422: Unprocessable Entity
500: Internal Error

Example:

Copy
curl "${BASE_URL}/2/users/${USER_ID}" \
  -X GET \
  -H "X-Algolia-API-Key: ${API_KEY}" \
  -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \

Response:

Copy
{
  "userID": "anonymous-62f2f24a-668f-11ee-8c99-0242ac120002",
  "affinities": [
    {
      "name": "color",
      "indices": ["products_EN"],
      "value": "red",
      "score": 8,
      "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
    },
    {
      "name": "color",
      "indices": ["products_EN"],
      "value": "blue",
      "score": 3,
      "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
    },
    {
      "name": "size",
      "indices": ["products_EN"],
      "value": "large",
      "score": 10,
      "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
    }
  ],
  "lastUpdatedAt": "2023-10-09T10:24:39.825Z"
}

Delete a user profile

Path: /2/users/{userID}
HTTP Verb: DELETE
Required API Key: Any key with the search, browse, and recommendation ACLs

Description:

Delete a user profile.

Errors:

400: Bad Request
401: Unauthorized
404: Not Found
422: Unprocessable Entity
500: Internal Error

Example:

Copy
curl "${BASE_URL}/2/users/${USER_ID}" \
  -X DELETE \
  -H "X-Algolia-API-Key: ${API_KEY}" \
  -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \

Response:

Copy
{
  "status": 200,
  "message": "OK",
  "userID": "anonymous-62f2f24a-668f-11ee-8c99-0242ac120002",
  "deletedUntil": "2023-09-01T00:00:00.000Z",
  "deletedAt": "2023-10-01T00:00:00.000Z"
}

Configuration endpoints

Quick reference

Verb	Path	Method
GET	/2/config	Get the configuration
PUT	/2/config	Update the configuration

Get the configuration

Path: /2/config
HTTP Verb: GET
Required API Key: Any key with the search, browse, and recommendation ACLs

Description:

Get the AI Personalization configuration for each index.

Errors:

401: Unauthorized
404: Not Found
500: Internal Error

Example:

Copy
curl "${BASE_URL}/2/config" \
  -X GET \
  -H "X-Algolia-API-Key: ${API_KEY}" \
  -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \

Response:

Copy
{
  "indices": [
    {
      "index": "products_EN",
      "affinities": ["size", "brand", "color"],
      "source": {
        "type": "insights",
        "events": {
          "viewDetails": [
            {
              "type": "view",
              "name": "Viewed product details page"
            }
          ],
          "viewListing": [
            {
              "type": "view",
              "name": "Viewed product listing page"
            }
          ],
          "addToCart": [
            {
              "type": "click",
              "subtype": "addToCart",
              "name": "Clicked add to cart button"
            }
          ],
          "purchase": [
            {
              "type": "conversion",
              "subtype": "purchase",
              "name": "Completed purchase"
            }
          ]
        }
      },
      "warnings": [
        {
          "code": "low_returning_users",
          "index": "products_EN",
          "message": "Your events indicate a rate of less than 5% returning users, please make sure to implement persistent user tokens for increased personalization impact."
        }
      ],
      "lastUpdatedAt": "2023-10-09T08:30:17.829Z"
    }
  ],
  "personalizationReRanking": "none"
}

Update the configuration

Path: /2/config
HTTP Verb: PUT
Required API Key: Any key with the search, browse, and recommendation ACLs

Description:

Configure AI Personalization for each index.

Add an AI Personalization configuration object with the name of the index, the desired affinities, and a data source to the indices array.

Predictions are not generated for an index until a valid source exists.

Parameters:

indices

Parameter	Description
`indices`	type: Array<index> Required

indices ➔ index

Parameter	Description
`index`	type: string Required
`affinities`	type: Array<string> Required
`source`	type: Array<source> Required

index ➔ source

Parameter	Description
`type`	type: string, enum pattern: `^insights$` Required
`events`	type: Object

source ➔ events

Parameter	Description
`viewDetails`	type: Array<event> Required
`viewListing`	type: Array<event> Required
`addToCart`	type: Array<event> Required
`purchase`	type: Array<event> Required

events ➔ event

Parameter	Description
`name`	type: string Required
`type`	type: string, enum Required

personalizationReRanking

Parameter	Description
`personalizationReRanking`	type: "none"\|"low"\|"medium"\|"high"\|"maximum" Required

Errors:

401: Unauthorized
404: Not Found
422: Unprocessable Entity
500: Internal Error

Example:

Copy
curl "${BASE_URL}/2/config" \
  -X PUT \
  -H "X-Algolia-API-Key: ${API_KEY}" \
  -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "indices": [
      {
        "index": "products_EN",
        "affinities": ["size", "brand", "color"],
        "source": {
          "type": "insights",
          "events": {
            "viewDetails": [
              {
                "type": "view",
                "name": "Viewed product details page"
              }
            ],
            "viewListing": [
              {
                "type": "view",
                "name": "Viewed product listing page"
              }
            ],
            "addToCart": [
              {
                "type": "conversion",
                "subtype": "addToCart",
                "name": "Clicked add to cart button"
              }
            ],
            "purchase": [
              {
                "type": "conversion",
                "subtype": "purchase",
                "name": "Completed purchase"
              }
            ]
          }
        }
      }
    ],
    "personalizationReRanking": "none"
  }'

OK Response:

A success response may include warnings about your Insights data. Resolve them to ensure the machine learning models can generate the most accurate affinities possible.

Copy
{
  "status": 200,
  "message": "OK",
  "warnings": [
    {
      "code": "low_returning_users",
      "index": "products_EN",
      "message": "Your events indicate a rate of less than 5% returning users, please make sure to implement persistent user tokens for increased personalization impact."
    }
  ]
}

Unprocessable Entity Response:

An unsuccessful request will return errors about your Insights data. To ensure the machine learning models can generate affinities, fix the errors before continuing.

Copy
{
  "status": 422,
  "message": "Some indices are invalid for AI Personalization.",
  "errors": [
    {
      "code": "no_records",
      "index": "products_EN",
      "message": "The index has no records."
    },
    {
      "code": "single_user_token",
      "index": "products_EN",
      "message": "All events have the same user token. To enable personalization, send unique tokens for each user."
    }
  ]
}

Did you find this page helpful?