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

Query Suggestions API (1.0.0)

Download OpenAPI specification:Download

The Query Suggestions API lets you manage your Query Suggestions configurations. Query Suggestions add new indices to your Algolia application with popular search queries, external suggestions, or facet values. In your user interface, you can query the Query Suggestions indices like regular indices and add suggested searches to guide users and speed up their search.

Base URLs

The base URLs for requests to the Query Suggestions API are:

  • https://query-suggestions.us.algolia.com
  • https://query-suggestions.eu.algolia.com

Use the URL that matches your analytics region.

All requests must use HTTPS.

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

Response bodies are JSON objects. Deleting a user token returns an empty response body with rate-limiting information as headers.

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 Query Suggestions API is version 1, as indicated by the /1/ in each endpoint's URL.

Configurations

Manage Query Suggestions configurations.

List configurations

Retrieves all Query Suggestions configurations of your Algolia application.

acl: ["settings"]

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.GetAllConfigsAsync();

Response samples

Content type
application/json
[
  • {
    }
]

Create a configuration

Creates a new Query Suggestions configuration.

You can have up to 100 configurations per Algolia application.

acl: ["editSettings"]
Request Body schema: application/json
required
indexName
required
string

Name of the Query Suggestions index (case-sensitive).

required
Array of objects non-empty

Algolia indices from which to get the popular searches for query suggestions.

allowSpecialCharacters
boolean
Default: false

Whether to include suggestions with special characters.

enablePersonalization
boolean
Default: false

Whether to turn on personalized query suggestions.

Array of exclude (strings) or exclude (null)
Default: null

Words or regular expressions to exclude from the suggestions.

Array of languages (strings) or languages (boolean)
Default: false

Languages for deduplicating singular and plural suggestions. If specified, only the more popular form is included.

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.CreateConfigAsync(
  new QuerySuggestionsConfigurationWithIndex
  {
    IndexName = "theIndexName",
    SourceIndices = new List<SourceIndex>
    {
      new SourceIndex
      {
        IndexName = "testIndex",
        Facets = new List<Facet> { new Facet { Attribute = "test", } },
        Generate = new List<List<string>>
        {
          new List<string> { "facetA", "facetB" },
          new List<string> { "facetC" }
        },
      }
    },
    Languages = new Languages(new List<string> { "french" }),
    Exclude = new List<string> { "test" },
  }
);

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Configuration was created, and a new indexing job has been scheduled."
}

Retrieve a configuration

Retrieves a single Query Suggestions configuration by its index name.

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

Query Suggestions index name.

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.GetConfigAsync("cts_e2e_browse_query_suggestions");

Response samples

Content type
application/json
{
  • "appID": "string",
  • "indexName": "products_query_suggestions",
  • "sourceIndices": [
    ],
  • "languages": false,
  • "exclude": null,
  • "enablePersonalization": false,
  • "allowSpecialCharacters": false
}

Update a configuration

Updates a QuerySuggestions configuration.

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

Query Suggestions index name.

Request Body schema: application/json
required
required
Array of objects non-empty

Algolia indices from which to get the popular searches for query suggestions.

allowSpecialCharacters
boolean
Default: false

Whether to include suggestions with special characters.

enablePersonalization
boolean
Default: false

Whether to turn on personalized query suggestions.

Array of exclude (strings) or exclude (null)
Default: null

Words or regular expressions to exclude from the suggestions.

Array of languages (strings) or languages (boolean)
Default: false

Languages for deduplicating singular and plural suggestions. If specified, only the more popular form is included.

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.UpdateConfigAsync(
  "theIndexName",
  new QuerySuggestionsConfiguration
  {
    SourceIndices = new List<SourceIndex>
    {
      new SourceIndex
      {
        IndexName = "testIndex",
        Facets = new List<Facet> { new Facet { Attribute = "test", } },
        Generate = new List<List<string>>
        {
          new List<string> { "facetA", "facetB" },
          new List<string> { "facetC" }
        },
      }
    },
    Languages = new Languages(new List<string> { "french" }),
    Exclude = new List<string> { "test" },
  }
);

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Configuration was updated, and a new indexing job has been scheduled."
}

Delete a configuration

Deletes a Query Suggestions configuration.

Deleting only removes the configuration and stops updates to the Query Suggestions index. To delete the Query Suggestions index itself, use the Search API and the Delete an index operation.

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

Query Suggestions index name.

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.DeleteConfigAsync("theIndexName");

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Configuration was deleted with success."
}

Retrieve configuration status

Reports the status of a Query Suggestions index.

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

Query Suggestions index name.

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.GetConfigStatusAsync("theIndexName");

Response samples

Content type
application/json
{
  • "indexName": "products_query_suggestions",
  • "isRunning": false,
  • "lastBuiltAt": "2023-07-05T08:03:53Z",
  • "lastSuccessfulBuiltAt": "2023-07-05T08:03:53Z",
  • "lastSuccessfulBuildDuration": 28
}

Logs

Get logs for a Query Suggestions index.

Retrieve logs

Retrieves the logs for a single Query Suggestions index.

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

Query Suggestions index name.

Responses

Request samples 

// Initialize the client
var client = new QuerySuggestionsClient(
  new QuerySuggestionsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.GetLogFileAsync("theIndexName");

Response samples

Content type
application/json
{
  • "timestamp": "2023-07-05T08:03:33.898076171Z",
  • "level": "ERROR",
  • "message": "skipping query \"Brooke Adams\": not enough search results, got 1, expected 5",
  • "contextLevel": 1
}