The successor to classic Personalization: real-time user profiles, personalization strategies and a dedicated error-code reference. Runs on its own AI personalization host and publishes the only per-product error catalogue in the estate.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/algolia-advanced-personalization-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Advanced Personalization API
summary: The Advanced Personalization API lets you access user profiles built based on the behavior of your users on your website or app
description: '## Client libraries
Use Algolia''s API clients and libraries to reliably integrate Algolia''s APIs with your apps.
The official API clients are covered by Algolia''s [Service Level Agreement](https://www.algolia.com/policies/sla).
For more information, see [Algolia''s ecosystem](https://www.algolia.com/doc/libraries).
## Base URLs
The Advanced Personalization API can be reached from multiple domains, each specific to a region.
- `https://ai-personalization.eu.algolia.com`
- `https://ai-personalization.us.algolia.com`
Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).
**All requests must use HTTPS.**
## Authentication
Add these headers to authenticate requests:
- `x-algolia-application-id`. Your Algolia application ID.
- `x-algolia-api-key`. An API key with the `search`, `browse` and `recommendation` ACL permissions.
You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).
## Request format
Request bodies must be JSON objects.
## Response status and errors
The Advanced 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 `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
Error responses have a `message` property with more information.
## Rate limiting
When making requests to the Advanced Personalization API, you are limited to 500 API calls per minute per application.
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`: Timestamp when the next time period starts, measured in seconds since the Unix epoch.
## Version
The current version of the Advanced Personalization API is version 2, indicated by the `/2/` in each endpoint''s URL.
'
version: 2.0.0
servers:
- url: https://ai-personalization.{region}.algolia.com
variables:
region:
description: 'Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).
'
enum:
- eu
- us
default: eu
security:
- appId: []
apiKey: []
tags:
- name: advanced-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:
- advanced-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:
- advanced-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:
- advanced-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:
- advanced-personalization
/2/config:
get:
tags:
- advanced-personalization
operationId: getConfig
x-acl:
- search
- browse
- recommendation
summary: Retrieve the configuration
description: Retrieves a list of configuration objects for each index.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/configurationObject'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
put:
tags:
- advanced-personalization
operationId: putConfig
x-acl:
- search
- browse
- recommendation
summary: Update the configuration
description: 'Updates the configuration.
The configuration is a list of configuration objects for each index. To configure Advanced Personalization for an index, create a new configuration object for the index.
'
requestBody:
required: true
content:
application/json:
schema:
title: configurationParameters
type: object
properties:
indices:
type: array
items:
title: configurationParametersObject
type: object
properties:
index:
type: string
affinities:
type: array
items:
type: string
source:
title: source
type: object
properties:
type:
$ref: '#/components/schemas/sourceType'
events:
$ref: '#/components/schemas/events'
required:
- type
required:
- index
- affinities
- source
personalizationReRanking:
$ref: '#/components/schemas/personalizationReRanking'
profileType:
$ref: '#/components/schemas/profileType'
features:
$ref: '#/components/schemas/features'
required:
- indices
- personalizationReRanking
- profileType
- features
responses:
'200':
description: OK
content:
application/json:
schema:
title: putConfigResponse
type: object
properties:
status:
type: number
errors:
type: array
items:
$ref: '#/components/schemas/issue'
warnings:
type: array
items:
$ref: '#/components/schemas/issue'
message:
type: string
required:
- status
- errors
- warnings
- message
'400':
$ref: '#/components/responses/BadRequest-2'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/FeatureNotEnabled-2'
'500':
$ref: '#/components/responses/InternalServerError'
/2/users:
get:
tags:
- advanced-personalization
operationId: getUsers
x-acl:
- search
- browse
- recommendation
summary: Get a list of user profiles
description: Retrieves a list of user profiles in [lexicographical order](https://www.educative.io/answers/what-is-a-lexicographic-order).
parameters:
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- $ref: '#/components/parameters/indices'
- $ref: '#/components/parameters/affinity'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/nextPageToken'
- $ref: '#/components/parameters/previousPageToken'
responses:
'200':
description: OK
content:
application/json:
schema:
title: getUsersResponse
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/user'
previousPageToken:
type: string
nextPageToken:
type: string
required:
- users
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/GenericUnprocessableEntity'
'500':
$ref: '#/components/responses/InternalServerError'
/2/users/{userID}:
get:
tags:
- advanced-personalization
operationId: getUser
x-acl:
- search
- browse
- recommendation
summary: Get a user profile
description: Retrieves a user profile.
parameters:
- $ref: '#/components/parameters/userID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
$ref: '#/components/responses/BadUserID'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/GenericNotFound'
'422':
$ref: '#/components/responses/InvalidUserID'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
tags:
- advanced-personalization
operationId: deleteUser
x-acl:
- search
- browse
- recommendation
summary: Delete a user profile
description: Deletes a user profile.
parameters:
- $ref: '#/components/parameters/userID'
responses:
'200':
description: OK
content:
application/json:
schema:
title: deleteUserResponse
type: object
properties:
message:
type: string
status:
type: integer
userID:
type: string
deletedUntil:
type: string
deletedAt:
type: string
'400':
$ref: '#/components/responses/BadUserID'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/InvalidUserID'
'500':
$ref: '#/components/responses/InternalServerError'
/2/realtime/users/{userToken}:
get:
tags:
- advanced-personalization
operationId: getRealtimeUser
x-acl:
- recommendation
summary: Retrieve the real-time user's personalization profile
description: Retrieves the real-time user's personalization profiles containing search filters.
parameters:
- $ref: '#/components/parameters/UserToken'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RealtimeUser'
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/FeatureNotEnabled'
'421':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
/2/realtime/users/{userToken}/compute:
post:
tags:
- advanced-personalization
operationId: computeRealtimeUser
x-acl:
- recommendation
summary: Compute the real-time user's personalization profile
description: Sends a request to compute the real-time user's personalization profile.
deprecated: true
parameters:
- $ref: '#/components/parameters/UserToken'
responses:
'202':
$ref: '#/components/responses/Accepted'
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/FeatureNotEnabled'
'409':
$ref: '#/components/responses/Conflict'
'421':
$ref: '#/components/responses/TooManyRequests'
'422':
$ref: '#/components/responses/StatusUnprocessableEntity'
'500':
$ref: '#/components/responses/InternalError'
/setClientApiKey:
get:
x-helper: true
x-asynchronous-helper: false
x-acl: []
tags:
- advanced-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:
unauthorized:
type: integer
description: HTTP status code for an authorization error.
enum:
- 401
ErrorResponses_internalServerError:
type: object
properties:
status:
$ref: '#/components/schemas/internalServerError'
message:
$ref: '#/components/schemas/ErrorMessages_internalServerError'
RealtimeUser:
title: RealtimeUser
type: object
additionalProperties: false
required:
- version
- userID
- lastUpdatedAt
- search
properties:
version:
type: string
description: Version of the response format.
userID:
type: string
description: User ID of the user.
lastUpdatedAt:
type: string
description: Date and time when the profile was last computed, in RFC 3339 format.
example: '2023-06-15T15:06:04.249906Z'
search:
type: object
description: 'Index personalization filters by index name.
'
additionalProperties:
$ref: '#/components/schemas/searchFilters'
genericNotFound:
type: string
description: Details about the response, such as error messages.
enum:
- Not Found
event:
type: object
properties:
type:
$ref: '#/components/schemas/eventType'
subtype:
$ref: '#/components/schemas/subtype'
name:
type: string
required:
- type
- name
profileType:
type: string
enum:
- basic
description: 'The type of user profiles to generate.
Basic profiles are based on past behaviors, ensuring search results align with previous interests.
'
userType:
title: userType
type: string
enum:
- basic
- predictive
- realtime
issue:
type: object
description: An issue is either an 'error' or a 'warning' that is generated by the validator.
properties:
code:
type: string
index:
type: string
message:
type: string
required:
- code
- index
- message
searchFilters:
type: object
additionalProperties: false
properties:
indices:
type: array
items:
type: string
example:
- storefront
- storefront_price_asc
- storefront_price_desc
strategy:
$ref: '#/components/schemas/strategy'
filters:
$ref: '#/components/schemas/searchFilter'
realtime:
type: object
properties:
enabled:
type: boolean
description: Whether the realtime personalization feature is enabled.
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
featureNotEnabled:
type: string
description: Details about the response, such as error messages.
enum:
- 'Predictive profiles are not allowed for this app. Please contact support to upgrade your plan: https://support.algolia.com/'
- 'Realtime Personalization is not allowed for this app. Please contact support to upgrade your plan: https://support.algolia.com/'
events:
type: object
properties:
viewDetails:
type: array
items:
$ref: '#/components/schemas/event'
viewListing:
type: array
items:
$ref: '#/components/schemas/event'
addToCart:
type: array
items:
$ref: '#/components/schemas/event'
purchase:
type: array
items:
$ref: '#/components/schemas/event'
required:
- viewDetails
- viewListing
- addToCart
- purchase
ErrorResponses_genericNotFound:
type: object
properties:
status:
$ref: '#/components/schemas/notFound'
message:
$ref: '#/components/schemas/genericNotFound'
ErrorResponses_badRequest:
type: object
properties:
status:
$ref: '#/components/schemas/badRequest'
message:
$ref: '#/components/schemas/ErrorMessages_badRequest'
badRequest:
type: integer
description: HTTP status code for a bad request error.
enum:
- 400
ErrorMessages_badRequest:
type: string
description: Details about the response, such as error messages.
enum:
- Invalid request body
ErrorResponses_badUserID:
type: object
properties:
status:
$ref: '#/components/schemas/badRequest'
message:
$ref: '#/components/schemas/badUserID'
unprocessableEntity:
type: integer
description: HTTP status code for an unprocessable entity error.
enum:
- 422
sourceType:
title: type
type: string
enum:
- insights
features:
type: object
properties:
realtime:
$ref: '#/components/schemas/realtime'
strategy:
type: string
enum:
- session
- historical
- hybrid
example: session
ErrorResponses_invalidUserID:
type: object
properties:
status:
$ref: '#/components/schemas/unprocessableEntity'
message:
$ref: '#/components/schemas/invalidUserID'
eventType:
type: string
enum:
- view
- click
- conversion
badUserID:
type: string
description: Details about the response, such as error messages.
enum:
- Invalid userID format
paymentRequired:
type: integer
description: HTTP status code for a payment required error.
enum:
- 402
internalServerError:
type: integer
description: HTTP status code for an internal server error.
enum:
- 500
Configuration_status:
type: object
properties:
type:
$ref: '#/components/schemas/status'
errors:
type: array
items:
$ref: '#/components/schemas/errorCodes'
lastUpdatedAt:
type: string
errorCodes:
title: errorCodes
type: string
enum:
- blocked
- deleted
- no_perso_access
- all_attr_value_filtered
- missing_index
- no_events_last_30_days
- pending_pipelines
- invalid_config
- all_facets_invalid
subtype:
type: string
enum:
- addToCart
- purchase
user:
type: object
properties:
userID:
type: string
type:
$ref: '#/components/schemas/userType'
affinities:
type: array
items:
title: affinity
type: object
properties:
name:
type: string
indices:
type: array
items:
type: string
minimum: 1
value:
type: string
score:
type: number
minimum: 1
maximum: 20
lastUpdatedAt:
type: string
required:
- name
- indices
- value
- score
- lastUpdatedAt
lastUpdatedAt:
type: string
required:
- userID
- type
- affinities
- lastUpdatedAt
ErrorMessages_internalServerError:
type: string
description: Details about the response, such as error messages.
enum:
- Internal Server Error
configurationObject:
type: object
properties:
indices:
type: array
items:
title: configurationObject
type: object
properties:
index:
type: string
affinities:
type: array
items:
type: string
source:
title: source
type: object
properties:
type:
$ref: '#/components/schemas/sourceType'
events:
$ref: '#/components/schemas/events'
errors:
type: array
items:
$ref: '#/components/schemas/issue'
warnings:
type: array
items:
$ref: '#/components/schemas/issue'
lastUpdatedAt:
type: string
required:
- index
- affinities
- source
- errors
- warnings
- lastUpdatedAt
personalizationReRanking:
$ref: '#/components/schemas/personalizationReRanking'
profileType:
$ref: '#/components/schemas/profileType'
status:
$ref: '#/components/schemas/Configuration_status'
features:
$ref: '#/components/schemas/features'
required:
- indices
- personalzationReRanking
- profileType
- status
- features
ErrorMessages_unauthorized:
type: string
description: Details about the response, such as error messages.
enum:
- Unauthorized
invalidUserID:
type: string
description: Details about the response, such as error messages.
enum:
- UserID must contain only alphanumeric
- equal
- plus
- slash
- hyphen
- or underscore characters
- and be between 1 and 129 characters long
genericUnprocessableEntity:
type: string
description: Details about the response, such as error messages.
enum:
- Unprocessable Entity
ErrorResponses_unauthorized:
type: object
properties:
status:
$ref: '#/components/schemas/unauthorized'
message:
$ref: '#/components/schemas/ErrorMessages_unauthorized'
notFound:
type: integer
description: HTTP status code for a not found error.
enum:
- 404
ErrorResponses_genericUnprocessableEntity:
type: object
properties:
status:
$ref: '#/components/schemas/unprocessableEntity'
message:
$ref: '#/components/schemas/genericUnprocessableEntity'
searchFilter:
type: object
additionalProperties: false
properties:
session:
type: array
items:
type: string
example:
- brand:Dyson<score=12>
personalizationReRanking:
type: string
description: The impact that personalization has on the re-ranking of search results.
enum:
- none
- low
- medium
- high
- maximum
ErrorResponses_featureNotEnabled:
type: object
properties:
status:
$ref: '#/components/schemas/paymentRequired'
message:
$ref: '#/components/schemas/featureNotEnabled'
status:
title: status
type: string
enum:
- pending
- active
- paused
ErrorBase:
description: Error.
type: object
x-keep-model: true
additionalProperties: true
properties:
message:
type: string
example: Invalid Application-Id or API-Key
responses:
GenericNotFound:
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_genericNotFound'
TooManyRequests:
description: Too Many Requests.
content:
application/json:
schema:
title: tooManyRequestsResponse
type: object
additionalProperties: false
required:
- status
- message
properties:
status:
type: integer
example: 421
description: Status code.
message:
type: string
example: Too Many Requests
description: Response message.
StatusUnprocessableEntity:
description: Unprocessable Entity.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
Unauthorized:
description: Not authorized to access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_unauthorized'
GenericUnprocessableEntity:
description: Unprocessable entity.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_genericUnprocessableEntity'
InternalServerError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_internalServerError'
Accepted:
description: Accepted.
content:
application/json:
schema:
title: acceptedResponse
type: object
additionalProperties: false
required:
- status
- message
properties:
status:
type: integer
example: 202
description: Status code.
message:
type: string
example: Accepted
description: Response message.
InvalidUserID:
description: Invalid user ID format.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_invalidUserID'
BadUserID:
description: Bad user ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_badUserID'
InternalError:
description: Internal error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
FeatureNotEnabled-2:
description: Feature not enabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_featureNotEnabled'
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'
BadRequest:
description: Bad request or request arguments.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
BadRequest-2:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponses_badRequest'
Conflict:
description: Conflict.
content:
application/json:
schema:
title: conflictResponse
type: object
additionalProperties: false
required:
- status
- message
properties:
status:
type: integer
example: 409
description: Status code.
message:
type: string
example: Conflict
description: Response message.
FeatureNotEnabled:
description: This feature is not enabled on your Algolia account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
parameters:
PathInPath:
name: path
in: path
description: Path of the endpoint, for example `1/newFeature`.
required: true
schema:
type: string
example: /keys
indices:
name: indices
description: 'Filter users by matching indices.
If multiple indices are passed, returned users will match all indices.
'
in: query
schema:
type: array
items:
type: string
examples:
singleIndex:
value:
- products_EN
summary: Filter by single index
multipleIndices:
value:
- products_EN
- products_FR
summary: Filter by multiple indices
style: form
explode: false
affinity:
name: affinity
description: 'Filter users by affinity name and value.
If multiple values are passed, returned
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/algolia/refs/heads/main/openapi/algolia-advanced-personalization-api-openapi.yml