openapi: 3.0.2
info:
  title: Recommend API
  summary: The Recommend API lets you retrieve recommendations from one of Algolia's AI recommendation models that you previously trained on your data
  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

    Base URLs for the Recommend API:

    - `https://{APPLICATION_ID}.algolia.net`
    - `https://{APPLICATION_ID}-dsn.algolia.net`.
      If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra),
      this ensures that requests are sent to servers closest to users.

    Both URLs provide high availability by distributing requests with load balancing.

    **All requests must use HTTPS.**

    ## Retry strategy

    To guarantee a high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks:

    - `https://{APPLICATION_ID}-1.algolianet.com`
    - `https://{APPLICATION_ID}-2.algolianet.com`
    - `https://{APPLICATION_ID}-3.algolianet.com`

    These URLs use a different DNS provider than the primary URLs.
    Randomize this list to ensure an even load across the three servers.

    All Algolia API clients implement this retry strategy.

    ## 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 Recommend 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.

    ## Version

    The current version of the Recommend API is version 1, indicated by the `/1/` in each endpoint's URL.
  version: 1.0.0
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
servers:
  - url: https://{appId}.algolia.net
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-1.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-2.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-3.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-dsn.algolia.net
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
security:
  - appId: []
    apiKey: []
tags:
  - name: recommendations
    x-displayName: Recommendations
    description: Retrieve recommendations from a pre-trained AI model. You can train models in the [Algolia dashboard](https://dashboard.algolia.com/recommend).
    externalDocs:
      url: https://www.algolia.com/doc/guides/algolia-recommend/overview
      description: Algolia Recommend.
  - name: rules
    x-displayName: Rules
    description: Curate your recommendations with rules, which are _if_-_then_ statements.
    externalDocs:
      url: https://www.algolia.com/doc/guides/algolia-recommend/how-to/rules
      description: Recommend Rules.
x-tagGroups:
  - name: Recommend
    tags:
      - recommendations
      - rules
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  /1/indexes/*/recommendations:
    $ref: 'paths/getRecommendations.yml'

  /1/indexes/{indexName}/{model}/recommend/rules/{objectID}:
    $ref: 'paths/recommendRule.yml'

  /1/indexes/{indexName}/{model}/task/{taskID}:
    $ref: 'paths/getRecommendStatus.yml'

  /1/indexes/{indexName}/{model}/recommend/rules/search:
    $ref: 'paths/searchRecommendRules.yml'

  /1/indexes/{indexName}/{model}/recommend/rules/batch:
    $ref: 'paths/batchRecommendRules.yml'

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