API reference / 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:

1
2
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

A

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
startDate
type: string
Optional

Filter users by start date (in RFC3339 format). Only users that were updated after the passed date will be returned.

Example: startDate=2024-06-27T08:27:26Z

endDate
type: string
Optional

Filter users by end date (in RFC3339 format). Only users that were updated before the passed date will be returned.

Example: endDate=2024-06-28T08:27:26Z

indices
type: string
Optional

Filter users by matching indices. If multiple indices are passed, returned users will match all indices.

Examples:

  • Filter by a single index: indices=products_EN

  • Filter by multiple indices: indices=products_EN,products_FR

affinity
type: string
Optional

Filter users by affinity name and value. If multiple values are passed, returned users will match all values.

Examples:

  • Filter by affinity name: affinity=brand

  • Filter by affinity-value pair: affinity=brand:Nike

  • Filter by multiple affinity names: affinity=brand,color

  • Filter by multiple affinity-value pairs: affinity=brand:Nike,color:white

limit
type: number
default: 10
Optional

Limit the number of users in the response. The value of this parameter ranges from 1 to 1000.

nextPageToken

Reference for the next page, when navigating forward using pagination. Can’t be used in the same request as previousPageToken.

previousPageToken

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:

A

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

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "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

A

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:

A

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

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "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

A

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:

A

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

Response:

1
2
3
4
5
6
7
{
  "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

A

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:

A

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

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "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

A

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:

A

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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.

1
2
3
4
5
6
7
8
9
10
11
{
  "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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?