The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Skip to main content
API docs by Redocly

Recommend API (1.0.0)

Download OpenAPI specification:Download

The Recommend API lets you retrieve recommendations from one of Algolia's AI recommendation models that you previously trained on your data.

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.

See: Algolia's ecosystem

Base URLs

The base URLs for requests to the Recommend API are:

  • https://{APPLICATION_ID}.algolia.net
  • https://{APPLICATION_ID}-dsn.algolia.net. If your subscription includes a Distributed Search Network, 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. You should randomize this list to ensure an even load across the three servers.

All Algolia API clients implement this retry strategy.

Authentication

To authenticate your API requests, add these headers:

  • 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.

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 a 2xx status. Client errors return a 4xx status. Server errors are indicated by a 5xx status. Error responses have a message property with more information.

Version

The current version of the Recommend API is version 1, as indicated by the /1/ in each endpoint's URL.

Recommendations

Retrieve recommendations from a pre-trained AI model. You can train models in the Algolia dashboard.

Related guide: Algolia Recommend.

Retrieve recommendations

Retrieves recommendations from selected AI models.

acl: ["search"]
Request Body schema: application/json
required
required
Array of Frequently bought together (object) or Related products (object) or Trending items (object) or Trending facet values (object) or Looking similar (object) or Recommended for you (object)

Recommendation request with parameters depending on the requested model.

Array
One of
indexName
required
string

Index name (case-sensitive).

model
required
string
Value: "bought-together"

Frequently bought together model.

This model recommends items that have been purchased within 1 day with the item with the ID objectID.

objectID
required
string

Unique record identifier.

threshold
required
number <double> [ 0 .. 100 ]

Minimum score a recommendation must have to be included in the response.

maxRecommendations
integer [ 1 .. 1000 ]
Default: 30

Maximum number of recommendations to retrieve. By default, all recommendations are returned and no fallback request is made. Depending on the available recommendations and the other request parameters, the actual number of recommendations may be lower than this value.

object

Each parameter value, including the query must not be larger than 512 bytes.

Responses

Request samples 

// Initialize the client
var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY"));

// Call the API
var response = await client.GetRecommendationsAsync(
  new GetRecommendationsParams
  {
    Requests = new List<RecommendationsRequest>
    {
      new RecommendationsRequest(
        new RelatedQuery
        {
          IndexName = "indexName",
          ObjectID = "objectID",
          Model = Enum.Parse<RelatedModel>("RelatedProducts"),
          Threshold = 42.1,
        }
      )
    },
  }
);

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Rules

Curate your recommendations with rules, which are if-then statements.

Related guide: Recommend Rules.

Retrieve a rule

Retrieves a Recommend rule that you previously created in the Algolia dashboard.

acl: ["settings"]
path Parameters
indexName
required
string
Example: YourIndexName

Name of the index on which to perform the operation.

model
required
string
Enum: "bought-together" "related-products" "trending-facets" "trending-items"
objectID
required
string
Example: test-record-123

Unique record identifier.

Responses

Request samples 

// Initialize the client
var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY"));

// Call the API
var response = await client.GetRecommendRuleAsync(
  "indexName",
  Enum.Parse<RecommendModels>("RelatedProducts"),
  "objectID"
);

Response samples

Content type
application/json
{
  • "_metadata": {
    },
  • "objectID": "string",
  • "condition": {
    },
  • "consequence": {
    },
  • "description": "Display a promotional banner",
  • "enabled": true
}

Delete a rule

Deletes a Recommend rule from a recommendation scenario.

acl: ["editSettings"]
path Parameters
indexName
required
string
Example: YourIndexName

Name of the index on which to perform the operation.

model
required
string
Enum: "bought-together" "related-products" "trending-facets" "trending-items"
objectID
required
string
Example: test-record-123

Unique record identifier.

Responses

Request samples 

// Initialize the client
var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY"));

// Call the API
var response = await client.DeleteRecommendRuleAsync(
  "indexName",
  Enum.Parse<RecommendModels>("RelatedProducts"),
  "objectID"
);

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "deletedAt": "2023-06-27T14:42:38.831Z"
}

Check task status

Checks the status of a given task.

Deleting a Recommend rule is asynchronous. When you delete a rule, a task is created on a queue and completed depending on the load on the server. The API response includes a task ID that you can use to check the status.

acl: ["editSettings"]
path Parameters
indexName
required
string
Example: YourIndexName

Name of the index on which to perform the operation.

model
required
string
Enum: "bought-together" "related-products" "trending-facets" "trending-items"
taskID
required
integer <int64>
Example: 1514562690001

Unique task identifier.

Responses

Request samples 

// Initialize the client
var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY"));

// Call the API
var response = await client.GetRecommendStatusAsync(
  "indexName",
  Enum.Parse<RecommendModels>("RelatedProducts"),
  12345L
);

Response samples

Content type
application/json
{
  • "status": "notPublished"
}

Search for rules

Searches for Recommend rules.

Use an empty query to list all rules for this recommendation scenario.

acl: ["settings"]
path Parameters
indexName
required
string
Example: YourIndexName

Name of the index on which to perform the operation.

model
required
string
Enum: "bought-together" "related-products" "trending-facets" "trending-items"
Request Body schema: application/json
context
string

Only search for rules with matching context.

enabled
boolean

Whether to only show rules where the value of their enabled property matches this parameter. If absent, show all rules, regardless of their enabled property.

facets
Array of strings

Include facets and facet values in the response. Use ['*'] to include all facets.

filters
string

Filter expression. This only searches for rules matching the filter expression.

hitsPerPage
integer [ 1 .. 1000 ]
Default: 20

Maximum number of hits per page.

maxValuesPerFacet
integer [ 1 .. 1000 ]

Maximum number of values to return for each facet.

page
integer >= 0

Requested page of the API response.

query
string
Default: ""

Search query.

Responses

Request samples 

// Initialize the client
var client = new RecommendClient(new RecommendConfig("YOUR_APP_ID", "YOUR_API_KEY"));

// Call the API
var response = await client.SearchRecommendRulesAsync(
  "indexName",
  Enum.Parse<RecommendModels>("RelatedProducts")
);

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "nbHits": 20,
  • "page": 0,
  • "nbPages": 1
}