openapi: 3.0.2 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](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 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](https://dashboard.algolia.com/account/api-keys). ## 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 `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 Personalization API, you are limited to 40 API calls per second per application. The following headers provide information about your current limit: - `x-ratelimit-limit`: The number of requests allowed every second. - `x-ratelimit-remaining`: The number of requests remaining in the current 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 Personalization API is version 1, indicated by the `/1/` in each endpoint's URL. 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: profiles x-displayName: Profiles description: > 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. - name: strategies x-displayName: Strategies description: > The personalization strategy defines how personalization should affect the search results, and how much each facet and event type impact the personalization. externalDocs: url: https://www.algolia.com/doc/guides/personalization/what-is-personalization description: Algolia 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: 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. parameters: PathInPath: name: path in: path description: Path of the endpoint, for example `1/newFeature`. required: true schema: type: string example: /keys 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' schemas: ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key 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 score: type: integer description: Event score. EventType: title: eventType type: string description: Event type. enum: - click - conversion - view 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' facetsScoring: type: object additionalProperties: false required: - score - facetName properties: score: $ref: '#/components/schemas/score' facetName: type: string description: Facet attribute name. 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. responses: BadRequest: description: Bad request or request arguments. 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' 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' headers: 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 x-ratelimit-reset: description: >- Timestamp when the rate limit will reset, measured in seconds since the Unix epoch. example: 1710682486 schema: type: integer x-tagGroups: - name: General tags: - profiles - strategies