openapi: 3.0.2
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
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
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
externalDocs:
  url: https://www.algolia.com/doc/guides/personalization/ai-personalization/what-is-ai-personalization
  description: What is Advanced Personalization.
security:
  - appId: []
    apiKey: []
tags:
  - name: config
    x-displayName: Configuration
    description: |
      Manage your Advanced Personalization configuration.

      The configuration defines the indices, facet attributes and events that describe your user's 
      behaviour on your website or app. It helps Advanced Personalization determine how personalization should affect the search results.
  - name: users
    x-displayName: Users
    description: |
      Manage user profiles generated by Advanced Personalization.

      User profiles contain the affinities each user has for the different facets in your index.
    externalDocs:
      url: https://www.algolia.com/doc/guides/personalization/ai-personalization/what-is-ai-personalization/concepts/user-profiles
      description: User profiles.
x-tagGroups:
  - name: Advanced Personalization
    tags:
      - config
      - users
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  /2/config:
    $ref: 'paths/config.yml'

  /2/users:
    $ref: 'paths/users.yml'

  /2/users/{userID}:
    $ref: 'paths/user.yml'

  # #################
  # ### Real-time ###
  # #################

  /2/realtime/users/{userToken}:
    $ref: 'paths/getRealtimeUser.yml'

  /2/realtime/users/{userToken}/compute:
    $ref: 'paths/computeRealtimeUser.yml'

  # ###############
  # ### Helpers ###
  # ###############
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'