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

Search API (1.0.0)

Download OpenAPI specification:Download

Use the Search REST API to manage your data (indices and records), implement search, and improve relevance (with Rules, synonyms, and language dictionaries).

Although Algolia provides a REST API, you should use the official open source API clients, libraries, and tools instead. There's no SLA if you use the REST API directly.

Indices

Manage indices, including listing them, checking and updating settings, deleting, copying, and renaming.

Delete index

Delete an existing index.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Responses

Response samples

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

Get index settings

Return an object containing an index's configuration settings.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Responses

Response samples

Content type
application/json
{
  • "replicas": [
    ],
  • "paginationLimitedTo": 20,
  • "unretrievableAttributes": [
    ],
  • "disableTypoToleranceOnWords": [
    ],
  • "attributesToTransliterate": [
    ],
  • "camelCaseAttributes": [
    ],
  • "decompoundedAttributes": {
    },
  • "indexLanguages": [
    ],
  • "disablePrefixOnAttributes": [
    ],
  • "allowCompressionOfIntegerArray": false,
  • "numericAttributesForFiltering": [
    ],
  • "separatorsToIndex": "+#",
  • "searchableAttributes": [
    ],
  • "userData": {
    },
  • "customNormalization": "{default: {'ä': 'ae', 'ü': 'ue'}}\n",
  • "attributesForFaceting": [
    ],
  • "attributesToRetrieve": [
    ],
  • "ranking": [
    ],
  • "customRanking": [
    ],
  • "relevancyStrictness": 90,
  • "attributesToHighlight": [
    ],
  • "attributesToSnippet": [
    ],
  • "highlightPreTag": "<em>",
  • "highlightPostTag": "</em>",
  • "snippetEllipsisText": "…",
  • "restrictHighlightAndSnippetArrays": false,
  • "hitsPerPage": 20,
  • "minWordSizefor1Typo": 4,
  • "minWordSizefor2Typos": 8,
  • "typoTolerance": true,
  • "allowTyposOnNumericTokens": true,
  • "disableTypoToleranceOnAttributes": [
    ],
  • "ignorePlurals": [
    ],
  • "removeStopWords": [
    ],
  • "keepDiacriticsOnCharacters": "øé",
  • "queryLanguages": [
    ],
  • "decompoundQuery": true,
  • "enableRules": true,
  • "enablePersonalization": false,
  • "queryType": "prefixLast",
  • "removeWordsIfNoResults": "firstWords",
  • "mode": "neuralSearch",
  • "semanticSearch": {
    },
  • "advancedSyntax": false,
  • "optionalWords": [
    ],
  • "disableExactOnAttributes": [
    ],
  • "exactOnSingleWordQuery": "attribute",
  • "alternativesAsExact": [
    ],
  • "advancedSyntaxFeatures": [
    ],
  • "distinct": 1,
  • "attributeForDistinct": "url",
  • "replaceSynonymsInHighlight": false,
  • "minProximity": 1,
  • "responseFields": [ ],
  • "maxFacetHits": 10,
  • "maxValuesPerFacet": 100,
  • "sortFacetValuesBy": "count",
  • "attributeCriteriaComputedByMinProximity": false,
  • "renderingContent": {
    },
  • "enableReRanking": true,
  • "reRankingApplyFilter": [
    ]
}

Update index settings

Update the specified index settings. Specifying null for a setting resets it to its default value.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Request Body schema: application/json
replicas
Array of strings
Default: []

Creates replicas, which are copies of a primary index with the same records but different settings.

paginationLimitedTo
integer
Default: 1000

Maximum number of hits accessible through pagination.

unretrievableAttributes
Array of strings
Default: []

Attributes that can't be retrieved at query time.

disableTypoToleranceOnWords
Array of strings
Default: []

Words for which you want to turn off typo tolerance.

attributesToTransliterate
Array of strings

Attributes in your index to which Japanese transliteration applies. This will ensure that words indexed in Katakana or Kanji can also be searched in Hiragana.

camelCaseAttributes
Array of strings
Default: []

Attributes on which to split camel case words.

decompoundedAttributes
object
Default: {}

Attributes in your index to which word segmentation (decompounding) applies.

indexLanguages
Array of strings
Default: []

Set the languages of your index, for language-specific processing steps such as tokenization and normalization.

disablePrefixOnAttributes
Array of strings
Default: []

Attributes for which you want to turn off prefix matching.

allowCompressionOfIntegerArray
boolean
Default: false

Incidates whether the engine compresses arrays with exclusively non-negative integers. When enabled, the compressed arrays may be reordered.

numericAttributesForFiltering
Array of strings
Default: []

Numeric attributes that can be used as numerical filters.

separatorsToIndex
string
Default: ""

Controls which separators are added to an Algolia index as part of normalization. Separators are all non-letter characters except spaces and currency characters, such as $€£¥.

searchableAttributes
userData
object (userData)
Default: {}

Lets you store custom data in your indices.

object

A list of characters and their normalized replacements to override Algolia's default normalization.

attributesForFaceting
Array of strings
Default: []

Attributes used for faceting and the modifiers that can be applied: filterOnly, searchable, and afterDistinct.

attributesToRetrieve
Array of strings
Default: ["*"]

Attributes to include in the API response. To reduce the size of your response, you can retrieve only some of the attributes. By default, the response includes all attributes.

ranking
Array of strings
Default: ["typo","geo","words","filters","proximity","attribute","exact","custom"]

Determines the order in which Algolia returns your results.

customRanking
Array of strings
Default: []

Specifies the Custom ranking criterion. Use the asc and desc modifiers to specify the ranking order: ascending or descending.

relevancyStrictness
integer
Default: 100

Relevancy threshold below which less relevant results aren't included in the results.

attributesToHighlight
Array of strings

Attributes to highlight. Strings that match the search query in the attributes are highlighted by surrounding them with HTML tags (highlightPreTag and highlightPostTag).

attributesToSnippet
Array of strings
Default: []

Attributes to snippet. 'Snippeting' is shortening the attribute to a certain number of words. If not specified, the attribute is shortened to the 10 words around the matching string but you can specify the number. For example: body:20.

highlightPreTag
string
Default: "<em>"

HTML string to insert before the highlighted parts in all highlight and snippet results.

highlightPostTag
string
Default: "</em>"

HTML string to insert after the highlighted parts in all highlight and snippet results.

snippetEllipsisText
string
Default: "…"

String used as an ellipsis indicator when a snippet is truncated.

restrictHighlightAndSnippetArrays
boolean
Default: false

Restrict highlighting and snippeting to items that matched the query.

hitsPerPage
integer (hitsPerPage) [ 1 .. 1000 ]
Default: 20

Number of hits per page.

minWordSizefor1Typo
integer
Default: 4

Minimum number of characters a word in the query string must contain to accept matches with one typo.

minWordSizefor2Typos
integer
Default: 8

Minimum number of characters a word in the query string must contain to accept matches with two typos.

boolean or typoToleranceEnum (string) (typoTolerance)

Controls whether typo tolerance is enabled and how it is applied.

allowTyposOnNumericTokens
boolean
Default: true

Whether to allow typos on numbers ("numeric tokens") in the query string.

disableTypoToleranceOnAttributes
Array of strings
Default: []

Attributes for which you want to turn off typo tolerance.

Array of strings or boolean (ignorePlurals)

Treats singular, plurals, and other forms of declensions as matching terms. ignorePlurals is used in conjunction with the queryLanguages setting. list: language ISO codes for which ignoring plurals should be enabled. This list will override any values that you may have set in queryLanguages. true: enables the ignore plurals feature, where singulars and plurals are considered equivalent ("foot" = "feet"). The languages supported here are either every language (this is the default) or those set by queryLanguages. false: turns off the ignore plurals feature, so that singulars and plurals aren't considered to be the same ("foot" will not find "feet").

Array of strings or boolean (removeStopWords)

Removes stop (common) words from the query before executing it. removeStopWords is used in conjunction with the queryLanguages setting. list: language ISO codes for which stop words should be enabled. This list will override any values that you may have set in queryLanguages. true: enables the stop words feature, ensuring that stop words are removed from consideration in a search. The languages supported here are either every language (this is the default) or those set by queryLanguages. false: turns off the stop words feature, allowing stop words to be taken into account in a search.

keepDiacriticsOnCharacters
string
Default: ""

Characters that the engine shouldn't automatically normalize.

queryLanguages
Array of strings
Default: []

Sets your user's search language. This adjusts language-specific settings and features such as ignorePlurals, removeStopWords, and CJK word detection.

decompoundQuery
boolean
Default: true

Splits compound words into their component word parts in the query.

enableRules
boolean
Default: true

Incidates whether Rules are enabled.

enablePersonalization
boolean
Default: false

Incidates whether Personalization is enabled.

queryType
string (queryType)
Default: "prefixLast"
Enum: "prefixLast" "prefixAll" "prefixNone"

Determines how query words are interpreted as prefixes.

removeWordsIfNoResults
string (removeWordsIfNoResults)
Default: "none"
Enum: "none" "lastWords" "firstWords" "allOptional"

Strategy to remove words from the query when it doesn't match any hits.

mode
string (mode)
Default: "keywordSearch"
Enum: "neuralSearch" "keywordSearch"

Search mode the index will use to query for results.

object (semanticSearch)

Settings for the semantic search part of NeuralSearch. Only used when mode is neuralSearch.

advancedSyntax
boolean
Default: false

Enables the advanced query syntax.

optionalWords
Array of strings
Default: []

Words which should be considered optional when found in a query.

disableExactOnAttributes
Array of strings
Default: []

Attributes for which you want to turn off the exact ranking criterion.

exactOnSingleWordQuery
string (exactOnSingleWordQuery)
Default: "attribute"
Enum: "attribute" "none" "word"

Determines how the Exact ranking criterion is computed when the query contains only one word.

alternativesAsExact
Array of strings (alternativesAsExact)
Default: ["ignorePlurals","singleWordSynonym"]
Items Enum: "ignorePlurals" "singleWordSynonym" "multiWordsSynonym"

Alternatives that should be considered an exact match by the exact ranking criterion.

advancedSyntaxFeatures
Array of strings (advancedSyntaxFeatures)
Default: ["exactPhrase","excludeWords"]
Items Enum: "exactPhrase" "excludeWords"

Allows you to specify which advanced syntax features are active when advancedSyntax is enabled.

attributeForDistinct
string

Name of the deduplication attribute to be used with Algolia's distinct feature.

replaceSynonymsInHighlight
boolean
Default: false

Whether to highlight and snippet the original word that matches the synonym or the synonym itself.

minProximity
integer [ 1 .. 7 ]
Default: 1

Precision of the proximity ranking criterion.

responseFields
Array of strings
Default: []

Attributes to include in the API response for search and browse queries.

maxFacetHits
integer (maxFacetHits) <= 100
Default: 10

Maximum number of facet hits to return when searching for facet values.

maxValuesPerFacet
integer
Default: 100

Maximum number of facet values to return for each facet.

sortFacetValuesBy
string
Default: "count"

Controls how facet values are fetched.

attributeCriteriaComputedByMinProximity
boolean
Default: false

When the Attribute criterion is ranked above Proximity in your ranking formula, Proximity is used to select which searchable attribute is matched in the Attribute ranking stage.

object (renderingContent)

Extra content for the search UI, for example, to control the ordering and display of facets. You can set a default value and dynamically override it with Rules.

enableReRanking
boolean
Default: true

Indicates whether this search will use Dynamic Re-Ranking.

(Array of listOfSearchFilters (Array of searchFiltersArrayString (strings) or strings or null)) or (string or null) (reRankingApplyFilter)

When Dynamic Re-Ranking is enabled, only records that match these filters will be affected by Dynamic Re-Ranking.

Responses

Request samples

Content type
application/json
{
  • "replicas": [
    ],
  • "paginationLimitedTo": 20,
  • "unretrievableAttributes": [
    ],
  • "disableTypoToleranceOnWords": [
    ],
  • "attributesToTransliterate": [
    ],
  • "camelCaseAttributes": [
    ],
  • "decompoundedAttributes": {
    },
  • "indexLanguages": [
    ],
  • "disablePrefixOnAttributes": [
    ],
  • "allowCompressionOfIntegerArray": false,
  • "numericAttributesForFiltering": [
    ],
  • "separatorsToIndex": "+#",
  • "searchableAttributes": [
    ],
  • "userData": {
    },
  • "customNormalization": "{default: {'ä': 'ae', 'ü': 'ue'}}\n",
  • "attributesForFaceting": [
    ],
  • "attributesToRetrieve": [
    ],
  • "ranking": [
    ],
  • "customRanking": [
    ],
  • "relevancyStrictness": 90,
  • "attributesToHighlight": [
    ],
  • "attributesToSnippet": [
    ],
  • "highlightPreTag": "<em>",
  • "highlightPostTag": "</em>",
  • "snippetEllipsisText": "…",
  • "restrictHighlightAndSnippetArrays": false,
  • "hitsPerPage": 20,
  • "minWordSizefor1Typo": 4,
  • "minWordSizefor2Typos": 8,
  • "typoTolerance": true,
  • "allowTyposOnNumericTokens": true,
  • "disableTypoToleranceOnAttributes": [
    ],
  • "ignorePlurals": [
    ],
  • "removeStopWords": [
    ],
  • "keepDiacriticsOnCharacters": "øé",
  • "queryLanguages": [
    ],
  • "decompoundQuery": true,
  • "enableRules": true,
  • "enablePersonalization": false,
  • "queryType": "prefixLast",
  • "removeWordsIfNoResults": "firstWords",
  • "mode": "neuralSearch",
  • "semanticSearch": {
    },
  • "advancedSyntax": false,
  • "optionalWords": [
    ],
  • "disableExactOnAttributes": [
    ],
  • "exactOnSingleWordQuery": "attribute",
  • "alternativesAsExact": [
    ],
  • "advancedSyntaxFeatures": [
    ],
  • "distinct": 1,
  • "attributeForDistinct": "url",
  • "replaceSynonymsInHighlight": false,
  • "minProximity": 1,
  • "responseFields": [ ],
  • "maxFacetHits": 10,
  • "maxValuesPerFacet": 100,
  • "sortFacetValuesBy": "count",
  • "attributeCriteriaComputedByMinProximity": false,
  • "renderingContent": {
    },
  • "enableReRanking": true,
  • "reRankingApplyFilter": [
    ]
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Check a task's status

Some operations, such as copying an index, will respond with a taskID value. Use this value here to check the status of that task.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

taskID
required
integer <int64>
Example: 1506303845001

Unique task identifier.

Responses

Response samples

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

Copy, move, or rename an index

This operation, copy or move, will copy or move a source index's (IndexName) records, settings, synonyms, and rules to a destination index. If the destination index exists, it will be replaced, except for index-specific API keys and analytics data. If the destination index doesn't exist, it will be created.

The choice between moving or copying an index depends on your needs. Choose:

  • Move to rename an index.
  • Copy to create a new index with the same records and configuration as an existing one.

Note: When considering copying or moving, be aware of the rate limitations on these processes and the impact on your analytics data.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json
operation
required
string (operationType)
Enum: "move" "copy"

Operation to perform (move or copy).

destination
required
string (indexName)

Algolia index name.

scope
Array of strings (scopeType)
Items Enum: "settings" "synonyms" "rules"

This only applies to the copy operation.

If you omit scope, the copy command copies all records, settings, synonyms, and rules.

If you specify scope, only the specified scopes are copied.

Responses

Request samples

Content type
application/json
{
  • "operation": "copy",
  • "destination": "products",
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

List indices

List indices in an Algolia application.

Authorizations:
(appIdapiKey)
query Parameters
page
integer or null >= 0
Default: null

Returns the requested page number. The page size is determined by the hitsPerPage parameter. You can see the number of available pages in the nbPages response attribute. When page is null, the API response is not paginated.

hitsPerPage
integer
Default: 100

Maximum number of hits per page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nbPages": 100
}

Records

Record operations.

Add or update a record

Add a record (object) to an index or replace it. If the record doesn't contain an objectID, Algolia automatically adds it. If you use an existing objectID, the existing record is replaced with the new one. To add multiple records to your index in a single API request, use the batch operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json

The Algolia record.

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2023-06-29T15:15:40.747Z",
  • "taskID": 1514562690001,
  • "objectID": "product-1"
}

Get a record

To get more than one record, use the objects operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: 123

Unique record (object) identifier.

query Parameters
attributesToRetrieve
Array of strings

Attributes to include with the records in the response. This is useful to reduce the size of the API response. By default, all retrievable attributes are returned. objectID is always retrieved, even when not specified. unretrievableAttributes won't be retrieved unless the request is authenticated with the admin API key.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Add or update a record (using objectID)

If you use an existing objectID, the existing record will be replaced with the new one.

To update only some attributes of an existing record, use the partial operation instead.

To add multiple records to your index in a single API request, use the batch operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: 123

Unique record (object) identifier.

Request Body schema: application/json

Algolia record.

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z",
  • "objectID": "product-1"
}

Delete a record

To delete a set of records matching a query, use the deleteByQuery operation instead.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: 123

Unique record (object) identifier.

Responses

Response samples

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

Delete all records matching a query

This operation doesn't support all the query options, only its filters (numeric, facet, or tag) and geo queries. It doesn't accept empty filters or queries.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json
(Array of listOfSearchFilters (Array of searchFiltersArrayString (strings) or strings)) or string (facetFilters)
filters
string (filters)
Default: ""

Filter the query with numeric, facet, or tag filters.

(Array of listOfSearchFilters (Array of searchFiltersArrayString (strings) or strings)) or string (numericFilters)
(Array of listOfSearchFilters (Array of searchFiltersArrayString (strings) or strings)) or string (tagFilters)
aroundLatLng
string (aroundLatLng)
Default: ""

Search for entries around a central location, enabling a geographical search within a circular area.

integer or aroundRadiusAll (string) (aroundRadius)

Maximum radius for a geographical search (in meters).

insideBoundingBox
Array of numbers <double> (insideBoundingBox) [ items <double > ]

Search inside a rectangular area (in geographical coordinates).

insidePolygon
Array of numbers <double> (insidePolygon) [ items <double > ]

Search inside a polygon (in geographical coordinates).

Responses

Request samples

Content type
application/json
{
  • "facetFilters": [
    ],
  • "filters": "(category:Book OR category:Ebook) AND _tags:published",
  • "numericFilters": [
    ],
  • "tagFilters": [
    ],
  • "aroundLatLng": "40.71,-74.01",
  • "aroundRadius": 1,
  • "insideBoundingBox": [
    ],
  • "insidePolygon": [
    ]
}

Response samples

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

Delete all records from an index

Delete the records but leave settings and index-specific API keys untouched.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Responses

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Update record attributes

Add new attributes or update current ones in an existing record. You can use any first-level attribute but not nested attributes. If you specify a nested attribute, the engine treats it as a replacement for its first-level ancestor.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: 123

Unique record (object) identifier.

query Parameters
createIfNotExists
boolean
Default: true

Indicates whether to create a new record if it doesn't exist yet.

Request Body schema: application/json

Object with attributes to update.

additional property
attribute (string) or builtInOperation (object) (attributeToUpdate)
One of
string (attribute)

Value of the attribute to be updated.

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z",
  • "objectID": "product-1"
}

Batch write operations on one index

To reduce the time spent on network round trips, you can perform several write actions in a single API call. Actions are applied in the order they are specified. The supported actions are equivalent to the individual operations of the same name.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json
required
Array of objects (batchRequest)
Array
action
required
string (action)
Enum: "addObject" "updateObject" "partialUpdateObject" "partialUpdateObjectNoCreate" "deleteObject" "delete" "clear"

Type of batch operation.

body
required
object

Operation arguments (varies with specified action).

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "objectIDs": [
    ]
}

Batch write operations on multiple indices

To reduce the time spent on network round trips, you can perform several write actions in a single request. It's a multi-index version of the batch operation. Actions are applied in the order they are specified. The supported actions are equivalent to the individual operations of the same name.

Authorizations:
(appIdapiKey)
Request Body schema: application/json
required
Array of objects (multipleBatchRequest)
Array
action
required
string (action)
Enum: "addObject" "updateObject" "partialUpdateObject" "partialUpdateObjectNoCreate" "deleteObject" "delete" "clear"

Type of batch operation.

body
required
object

Operation arguments (varies with specified action).

indexName
required
string

Index to target for this operation.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "taskID": {
    },
  • "objectIDs": [
    ]
}

Get multiple records

Retrieve one or more records, potentially from different indices, in a single API operation. Results will be received in the same order as the requests.

Authorizations:
(appIdapiKey)
Request Body schema: application/json

Request object.

required
Array of objects (getObjectsRequest)
Array
attributesToRetrieve
Array of strings

Attributes to retrieve. If not specified, all retrievable attributes are returned.

objectID
required
string

Record's objectID.

indexName
required
string

Name of the index containing the required records.

Responses

Request samples

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

Response samples

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

Search

Search operations.

Search an index

Return records that match the query.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json
One of
params
string (paramsAsString)
Default: ""

Search parameters as a URL-encoded query string.

Responses

Request samples

Content type
application/json
Example
{
  • "params": "hitsPerPage=2&getRankingInfo=1"
}

Response samples

Content type
application/json
{
  • "abTestID": 0,
  • "abTestVariantID": 1,
  • "aroundLatLng": "40.71,-74.01",
  • "automaticRadius": "string",
  • "exhaustiveFacetsCount": true,
  • "exhaustiveNbHits": true,
  • "exhaustiveTypo": true,
  • "facets": {
    },
  • "facets_stats": {
    },
  • "hitsPerPage": 20,
  • "index": "indexName",
  • "indexUsed": "indexNameAlt",
  • "message": "string",
  • "nbHits": 20,
  • "nbPages": 1,
  • "nbSortedHits": 20,
  • "page": 0,
  • "redirect": {
    },
  • "parsedQuery": "george clo",
  • "processingTimeMS": 20,
  • "queryAfterRemoval": "string",
  • "serverUsed": "c2-uk-3.algolia.net",
  • "userData": {
    },
  • "renderingContent": {
    },
  • "hits": [
    ],
  • "query": "",
  • "params": "query=a&hitsPerPage=20"
}

Search multiple indices

Send multiple search queries to one or more indices.

Authorizations:
(appIdapiKey)
Request Body schema: application/json

Query requests and strategies. Results will be received in the same order as the queries.

required
Array of (SearchForHits (searchParamsString (object) or baseSearchParams (object))) or (SearchForFacets (searchParamsString (object) or baseSearchParams (object))) (SearchQuery)
strategy
string (searchStrategy)
Enum: "none" "stopIfEnoughMatches"
  • none: executes all queries. - stopIfEnoughMatches: executes queries one by one, stopping further query execution as soon as a query matches at least the hitsPerPage number of results.

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ],
  • "strategy": "none"
}

Response samples

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

Search for facet values

Search for a facet's values, optionally restricting the returned values to those contained in records matching other search criteria.

Note: Pagination isn't supported (page and hitsPerPage are ignored). By default, the engine returns a maximum of 10 values but you can adjust this with maxFacetHits.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

facetName
required
string

Facet name.

Request Body schema: application/json
params
string (paramsAsString)
Default: ""

Search parameters as a URL-encoded query string.

facetQuery
string (facetQuery)
Default: ""

Text to search inside the facet's values.

maxFacetHits
integer (maxFacetHits) <= 100
Default: 10

Maximum number of facet hits to return when searching for facet values.

Responses

Request samples

Content type
application/json
{
  • "params": "hitsPerPage=2&getRankingInfo=1",
  • "facetQuery": "george",
  • "maxFacetHits": 10
}

Response samples

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

Get all records from an index

Retrieve up to 1,000 records per call. Supports full-text search and filters. For better performance, it doesn't support:

  • The distinct query parameter - Sorting by typos, proximity, words, or geographical distance.
Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json
One of
params
string (paramsAsString)
Default: ""

Search parameters as a URL-encoded query string.

Responses

Request samples

Content type
application/json
Example
{
  • "params": "hitsPerPage=2&getRankingInfo=1"
}

Response samples

Content type
application/json
{
  • "abTestID": 0,
  • "abTestVariantID": 1,
  • "aroundLatLng": "40.71,-74.01",
  • "automaticRadius": "string",
  • "exhaustiveFacetsCount": true,
  • "exhaustiveNbHits": true,
  • "exhaustiveTypo": true,
  • "facets": {
    },
  • "facets_stats": {
    },
  • "hitsPerPage": 20,
  • "index": "indexName",
  • "indexUsed": "indexNameAlt",
  • "message": "string",
  • "nbHits": 20,
  • "nbPages": 1,
  • "nbSortedHits": 20,
  • "page": 0,
  • "redirect": {
    },
  • "parsedQuery": "george clo",
  • "processingTimeMS": 20,
  • "queryAfterRemoval": "string",
  • "serverUsed": "c2-uk-3.algolia.net",
  • "userData": {
    },
  • "renderingContent": {
    },
  • "hits": [
    ],
  • "query": "",
  • "params": "query=a&hitsPerPage=20",
  • "cursor": "jMDY3M2MwM2QwMWUxMmQwYWI0ZTN"
}

Rules

Rules operations.

Get a rule

Get a rule by its objectID. To find the objectID for rules, use the search operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: a-rule-id

Unique identifier of a rule object.

Responses

Response samples

Content type
application/json
{
  • "objectID": "hide-12345",
  • "conditions": [
    ],
  • "consequence": {
    },
  • "description": "Display a promotional banner",
  • "enabled": true,
  • "validity": [
    ]
}

Create or update a rule

To create or update more than one rule, use the batch operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: a-rule-id

Unique identifier of a rule object.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Request Body schema: application/json
objectID
required
string

Unique identifier for a rule object.

Array of objects (condition)

Conditions required to activate a rule. You can use up to 25 conditions per rule.

object (consequence)

Consequences of a rule.

description
string

Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.

enabled
boolean
Default: true

Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.

Array of objects (timeRange)

If you specify a validity period, the rule only applies only during that period. If specified, the array must not be empty.

Responses

Request samples

Content type
application/json
{
  • "objectID": "hide-12345",
  • "conditions": [
    ],
  • "consequence": {
    },
  • "description": "Display a promotional banner",
  • "enabled": true,
  • "validity": [
    ]
}

Response samples

Content type
application/json
{
  • "objectID": "product-1",
  • "updatedAt": "2023-07-04T12:49:15Z",
  • "taskID": 1514562690001
}

Delete a rule

Delete a rule by its objectID. To find the objectID for rules, use the search operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: a-rule-id

Unique identifier of a rule object.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Responses

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Save a batch of rules

Create or update multiple rules.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

clearExistingRules
boolean

Indicates whether existing rules should be deleted before adding this batch.

Request Body schema: application/json
Array
objectID
required
string

Unique identifier for a rule object.

Array of objects (condition)

Conditions required to activate a rule. You can use up to 25 conditions per rule.

object (consequence)

Consequences of a rule.

description
string

Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.

enabled
boolean
Default: true

Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.

Array of objects (timeRange)

If you specify a validity period, the rule only applies only during that period. If specified, the array must not be empty.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Delete all rules

Delete all rules in the index.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Responses

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Search for rules

Search for rules in your index. You can control the search with parameters. To list all rules, send an empty request body.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

Request Body schema: application/json
query
string (parameters_query)
Default: ""

Rule object query.

anchoring
string (anchoring)
Enum: "is" "startsWith" "endsWith" "contains"

Whether the pattern parameter matches the beginning (startsWith) or end (endsWith) of the query string, is an exact match (is), or a partial match (contains).

context
string

Restricts responses to the specified contextual rule.

page
integer (parameters_page) >= 0

Requested page (the first page is page 0).

hitsPerPage
integer (parameters_hitsPerPage) [ 1 .. 1000 ]
Default: 20

Maximum number of hits per page.

enabled
boolean or null
Default: null

Restricts responses to enabled rules. When not specified (default), all rules are retrieved.

requestOptions
Array of objects

Request options to send with the API call.

Responses

Request samples

Content type
application/json
{
  • "query": "",
  • "anchoring": "is",
  • "context": "mobile",
  • "page": 0,
  • "hitsPerPage": 20,
  • "enabled": null,
  • "requestOptions": "{timeouts:{read:20}}\n"
}

Response samples

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

Synonyms

Synonym operations.

Get a synonym object

Get a syonym by its objectID. To find the object IDs for your synonyms, use the search operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: synonymID

Unique identifier of a synonym object.

Responses

Response samples

Content type
application/json
{
  • "objectID": "synonymID",
  • "type": "onewaysynonym",
  • "synonyms": [
    ],
  • "input": "car",
  • "word": "car",
  • "corrections": [
    ],
  • "placeholder": "<Street>",
  • "replacements": [
    ]
}

Save a synonym

Add a synonym to an index or replace it. If the synonym objectID doesn't exist, Algolia adds a new one. If you use an existing synonym objectID, the existing synonym is replaced with the new one. To add multiple synonyms in a single API request, use the batch operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: synonymID

Unique identifier of a synonym object.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Request Body schema: application/json
objectID
required
string

Unique identifier of a synonym object.

type
required
string (SynonymType)
Enum: "synonym" "onewaysynonym" "altcorrection1" "altcorrection2" "placeholder"

Synonym type.

synonyms
Array of strings

Words or phrases considered equivalent.

input
string

Word or phrase to appear in query strings (for onewaysynonyms).

word
string

Word or phrase to appear in query strings (for altcorrection1 and altcorrection2).

corrections
Array of strings

Words to be matched in records.

placeholder
string

Placeholder token to be put inside records.

replacements
Array of strings

Query words that will match the placeholder token.

Responses

Request samples

Content type
application/json
{
  • "objectID": "synonymID",
  • "type": "onewaysynonym",
  • "synonyms": [
    ],
  • "input": "car",
  • "word": "car",
  • "corrections": [
    ],
  • "placeholder": "<Street>",
  • "replacements": [
    ]
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z",
  • "id": "12"
}

Delete a synonym

Delete a synonym by its objectID. To find the object IDs of your synonyms, use the search operation.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

objectID
required
string
Example: synonymID

Unique identifier of a synonym object.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Responses

Response samples

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

Save a batch of synonyms

Create or update multiple synonyms.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

replaceExistingSynonyms
boolean

Indicates whether to replace all synonyms in the index with the ones sent with this request.

Request Body schema: application/json
Array
objectID
required
string

Unique identifier of a synonym object.

type
required
string (SynonymType)
Enum: "synonym" "onewaysynonym" "altcorrection1" "altcorrection2" "placeholder"

Synonym type.

synonyms
Array of strings

Words or phrases considered equivalent.

input
string

Word or phrase to appear in query strings (for onewaysynonyms).

word
string

Word or phrase to appear in query strings (for altcorrection1 and altcorrection2).

corrections
Array of strings

Words to be matched in records.

placeholder
string

Placeholder token to be put inside records.

replacements
Array of strings

Query words that will match the placeholder token.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Delete all synonyms

Delete all synonyms in the index.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

query Parameters
forwardToReplicas
boolean

Indicates whether changed index settings are forwarded to the replica indices.

Responses

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Search for synonyms

Search for synonyms in your index. You can control and filter the search with parameters. To get all synonyms, send an empty request body.

Authorizations:
(appIdapiKey)
path Parameters
indexName
required
string
Example: myIndexName

Index on which to perform the request.

query Parameters
type
string (SynonymType)
Enum: "synonym" "onewaysynonym" "altcorrection1" "altcorrection2" "placeholder"
Example: type=onewaysynonym

Search for specific types of synonyms.

page
integer or null >= 0
Default: 0

Returns the requested page number (the first page is 0). Page size is set by hitsPerPage. When null, there's no pagination.

hitsPerPage
integer
Default: 100

Maximum number of hits per page.

Request Body schema: application/json

Body of the searchSynonyms operation.

query
string (query)
Default: ""

Text to search for in an index.

Responses

Request samples

Content type
application/json
{
  • "query": ""
}

Response samples

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

Dictionaries

Dictionary operations allow you to customize linguistic features such as stop words, plurals, and segmentation (compounds).

Batch dictionary entries

Add or remove a batch of dictionary entries.

Authorizations:
(appIdapiKey)
path Parameters
dictionaryName
required
string (dictionaryType)
Enum: "plurals" "stopwords" "compounds"

Dictionary to search in.

Request Body schema: application/json
clearExistingDictionaryEntries
boolean
Default: false

Incidates whether to replace all custom entries in the dictionary with the ones sent with this request.

required
Array of objects (batchDictionaryEntriesRequest)

Operations to batch.

Responses

Request samples

Content type
application/json
{
  • "clearExistingDictionaryEntries": false,
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Search dictionary entries

Search for standard and custom entries in the stop words, plurals, or segmentation (compounds) dictionaries.

Authorizations:
(appIdapiKey)
path Parameters
dictionaryName
required
string (dictionaryType)
Enum: "plurals" "stopwords" "compounds"

Dictionary to search in.

Request Body schema: application/json
query
required
string (query)
Default: ""

Text to search for in an index.

page
integer (page)
Default: 0

Page to retrieve (the first page is 0, not 1).

hitsPerPage
integer (hitsPerPage) [ 1 .. 1000 ]
Default: 20

Number of hits per page.

language
string (language)

Responses

Request samples

Content type
application/json
{
  • "query": "",
  • "page": 0,
  • "hitsPerPage": 20,
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Get stop word settings

Get the languages for which stop words are turned off.

Authorizations:
(appIdapiKey)

Responses

Response samples

Content type
application/json
{
  • "disableStandardEntries": {
    }
}

Set stop word settings

Set stop word settings for a specific language.

Authorizations:
(appIdapiKey)
Request Body schema: application/json
required
object (standardEntries)

Key-value pairs of supported language ISO codes and boolean values.

object or null (standardEntry)

Key-value pair of a language ISO code and a boolean value.

object or null (standardEntry)

Key-value pair of a language ISO code and a boolean value.

object or null (standardEntry)

Key-value pair of a language ISO code and a boolean value.

Responses

Request samples

Content type
application/json
{
  • "disableStandardEntries": {
    }
}

Response samples

Content type
application/json
{
  • "taskID": 1514562690001,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

List available languages

Lists Algolia's supported languages and any customizations applied to each language's stop word, plural, and segmentation (compound) features.

Authorizations:
(appIdapiKey)

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Api Keys

Manage your API keys.

List API keys

List all API keys associated with your Algolia application, including their permissions and restrictions.

Authorizations:
(appIdapiKey)

Responses

Response samples

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

Add API key

Add a new API key with specific permissions and restrictions. The request must be authenticated with the admin API key. The response returns an API key string.

Authorizations:
(appIdapiKey)
Request Body schema: application/json
acl
required
Array of strings (acl)
Default: []
Items Enum: "addObject" "analytics" "browse" "deleteObject" "deleteIndex" "editSettings" "inference" "listIndexes" "logs" "personalization" "recommendation" "search" "seeUnretrievableAttributes" "settings" "usage"

Permissions associated with the key.

description
string
Default: ""

Description of an API key for you and your team members.

indexes
Array of strings
Default: []

Restricts this API key to a list of indices or index patterns. If the list is empty, all indices are allowed. Specify either an exact index name or a pattern with a leading or trailing wildcard character (or both). For example:

  • dev_* matches all indices starting with "dev_" - *_dev matches all indices ending with "_dev" - *_products_* matches all indices containing "products".
maxHitsPerQuery
integer
Default: 0

Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced.

Note: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.

maxQueriesPerIPPerHour
integer
Default: 0

Maximum number of API calls per hour allowed from a given IP address or user token. Each time an API call is performed with this key, a check is performed. If there were more than the specified number of calls within the last hour, the API returns an error with the status code 429 (Too Many Requests).

Note: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.

queryParameters
string
Default: ""

Force some query parameters to be applied for each query made with this API key. It's a URL-encoded query string.

referers
Array of strings
Default: []

Restrict this API key to specific referrers. If empty, all referrers are allowed. For example:

  • https://algolia.com/* matches all referrers starting with "https://algolia.com/" - *.algolia.com matches all referrers ending with ".algolia.com" - *algolia.com* allows everything in the domain "algolia.com".
validity
integer
Default: 0

Validity duration of a key (in seconds). The key will automatically be removed after this time has expired. The default value of 0 never expires. Short-lived API keys are useful to grant temporary access to your data. For example, in mobile apps, you can't control when users update your app. So instead of encoding keys into your app as you would for a web app, you should dynamically fetch them from your mobile app's backend.

Responses

Request samples

Content type
application/json
{
  • "acl": [
    ],
  • "description": "Browse-restricted key",
  • "indexes": [
    ],
  • "maxHitsPerQuery": 0,
  • "maxQueriesPerIPPerHour": 0,
  • "queryParameters": "typoTolerance%3Dstrict%26ignorePlurals%3Dfalse%26filters%3Drights%3Apublic",
  • "referers": [
    ],
  • "validity": 86400
}

Response samples

Content type
application/json
{
  • "key": "13ad45b4d0a2f6ea65ecbddf6aa260f2",
  • "createdAt": "2023-07-04T12:49:15Z"
}

Get API key permissions

Get the permissions and restrictions of a specific API key. When authenticating with the admin API key, you can request information for any of your application's keys. When authenticating with other API keys, you can only retrieve information for that key.

Authorizations:
(appIdapiKey)
path Parameters
key
required
string
Example: YourAPIKey

API key.

Responses

Response samples

Content type
application/json
{
  • "value": "13ad45b4d0a2f6ea65ecbddf6aa260f2",
  • "createdAt": 1656345570000,
  • "acl": [
    ],
  • "description": "Browse-restricted key",
  • "indexes": [
    ],
  • "maxHitsPerQuery": 0,
  • "maxQueriesPerIPPerHour": 0,
  • "queryParameters": "typoTolerance%3Dstrict%26ignorePlurals%3Dfalse%26filters%3Drights%3Apublic",
  • "referers": [
    ],
  • "validity": 86400
}

Update an API key

Replace the permissions of an existing API key. Any unspecified parameter resets that permission to its default value. The request must be authenticated with the admin API key.

Authorizations:
(appIdapiKey)
path Parameters
key
required
string
Example: YourAPIKey

API key.

Request Body schema: application/json
acl
required
Array of strings (acl)
Default: []
Items Enum: "addObject" "analytics" "browse" "deleteObject" "deleteIndex" "editSettings" "inference" "listIndexes" "logs" "personalization" "recommendation" "search" "seeUnretrievableAttributes" "settings" "usage"

Permissions associated with the key.

description
string
Default: ""

Description of an API key for you and your team members.

indexes
Array of strings
Default: []

Restricts this API key to a list of indices or index patterns. If the list is empty, all indices are allowed. Specify either an exact index name or a pattern with a leading or trailing wildcard character (or both). For example:

  • dev_* matches all indices starting with "dev_" - *_dev matches all indices ending with "_dev" - *_products_* matches all indices containing "products".
maxHitsPerQuery
integer
Default: 0

Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced.

Note: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.

maxQueriesPerIPPerHour
integer
Default: 0

Maximum number of API calls per hour allowed from a given IP address or user token. Each time an API call is performed with this key, a check is performed. If there were more than the specified number of calls within the last hour, the API returns an error with the status code 429 (Too Many Requests).

Note: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.

queryParameters
string
Default: ""

Force some query parameters to be applied for each query made with this API key. It's a URL-encoded query string.

referers
Array of strings
Default: []

Restrict this API key to specific referrers. If empty, all referrers are allowed. For example:

  • https://algolia.com/* matches all referrers starting with "https://algolia.com/" - *.algolia.com matches all referrers ending with ".algolia.com" - *algolia.com* allows everything in the domain "algolia.com".
validity
integer
Default: 0

Validity duration of a key (in seconds). The key will automatically be removed after this time has expired. The default value of 0 never expires. Short-lived API keys are useful to grant temporary access to your data. For example, in mobile apps, you can't control when users update your app. So instead of encoding keys into your app as you would for a web app, you should dynamically fetch them from your mobile app's backend.

Responses

Request samples

Content type
application/json
{
  • "acl": [
    ],
  • "description": "Browse-restricted key",
  • "indexes": [
    ],
  • "maxHitsPerQuery": 0,
  • "maxQueriesPerIPPerHour": 0,
  • "queryParameters": "typoTolerance%3Dstrict%26ignorePlurals%3Dfalse%26filters%3Drights%3Apublic",
  • "referers": [
    ],
  • "validity": 86400
}

Response samples

Content type
application/json
{
  • "key": "13ad45b4d0a2f6ea65ecbddf6aa260f2",
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Delete API key

Delete an existing API key. The request must be authenticated with the admin API key.

Authorizations:
(appIdapiKey)
path Parameters
key
required
string
Example: YourAPIKey

API key.

Responses

Response samples

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

Restore API key

Restore a deleted API key, along with its associated permissions. The request must be authenticated with the admin API key.

Authorizations:
(appIdapiKey)
path Parameters
key
required
string
Example: YourAPIKey

API key.

Responses

Response samples

Content type
application/json
{
  • "key": "13ad45b4d0a2f6ea65ecbddf6aa260f2",
  • "createdAt": "2023-07-04T12:49:15Z"
}

Clusters

Multi-cluster operations. Algolia no longer offers multi-cluster management.

  • If you want to partition your data per user, use facets and secured API keys instead. - If you need more data, consider upgrading to a bigger cluster to suit your needs. Contact Algolia's support team for details.

Assign or move a user ID

Assign or move a user ID to a cluster. The time it takes to move a user is proportional to the amount of data linked to the user ID.

Authorizations:
(appIdapiKey)
header Parameters
X-Algolia-User-ID
required
string^[a-zA-Z0-9 \-*.]+$

userID to assign.

Request Body schema: application/json
cluster
required
string (clusterName)

Cluster name.

Responses

Request samples

Content type
application/json
{
  • "cluster": "c11-test"
}

Response samples

Content type
application/json
{
  • "createdAt": "2023-07-04T12:49:15Z"
}

List userIDs

List the userIDs assigned to a multi-cluster application. Since it can take up to a few seconds to get the data from the different clusters, the response isn't real-time.

Authorizations:
(appIdapiKey)
query Parameters
page
integer or null >= 0
Default: null

Returns the requested page number. The page size is determined by the hitsPerPage parameter. You can see the number of available pages in the nbPages response attribute. When page is null, the API response is not paginated.

hitsPerPage
integer
Default: 100

Maximum number of hits per page.

Responses

Response samples

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

Batch assign userIDs

Assign multiple user IDs to a cluster. You can't move users with this operation..

Authorizations:
(appIdapiKey)
header Parameters
X-Algolia-User-ID
required
string^[a-zA-Z0-9 \-*.]+$

userID to assign.

Request Body schema: application/json
cluster
required
string (clusterName)

Cluster name.

users
required
Array of strings

User IDs to assign.

Responses

Request samples

Content type
application/json
{
  • "cluster": "c11-test",
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2023-07-04T12:49:15Z"
}

Get top userID

Get the IDs of the 10 users with the highest number of records per cluster. Since it can take up to a few seconds to get the data from the different clusters, the response isn't real-time.

Authorizations:
(appIdapiKey)

Responses

Response samples

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

Get userID

Returns the userID data stored in the mapping. Since it can take up to a few seconds to get the data from the different clusters, the response isn't real-time.

Authorizations:
(appIdapiKey)
path Parameters
userID
required
string^[a-zA-Z0-9 \-*.]+$

userID to assign.

Responses

Response samples

Content type
application/json
{
  • "userID": "user1",
  • "clusterName": "c1-test",
  • "nbRecords": 42,
  • "dataSize": 0
}

Remove userID

Remove a userID and its associated data from the multi-clusters.

Authorizations:
(appIdapiKey)
path Parameters
userID
required
string^[a-zA-Z0-9 \-*.]+$

userID to assign.

Responses

Response samples

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

List clusters

List the available clusters in a multi-cluster setup.

Authorizations:
(appIdapiKey)

Responses

Response samples

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

Search for a user ID

Since it can take up to a few seconds to get the data from the different clusters, the response isn't real-time. To ensure rapid updates, the user IDs index isn't built at the same time as the mapping. Instead, it's built every 12 hours, at the same time as the update of user ID usage. For example, if you add or move a user ID, the search will show an old value until the next time the mapping is rebuilt (every 12 hours).

Authorizations:
(appIdapiKey)
Request Body schema: application/json
query
required
string

Query to search. The search is a prefix search with typo tolerance enabled. An empty query will retrieve all users.

clusterName
string (clusterName)

Cluster name.

page
integer (page)
Default: 0

Page to retrieve (the first page is 0, not 1).

hitsPerPage
integer (hitsPerPage) [ 1 .. 1000 ]
Default: 20

Number of hits per page.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "clusterName": "c11-test",
  • "page": 0,
  • "hitsPerPage": 20
}

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "nbHits": 20,
  • "page": 0,
  • "hitsPerPage": 20,
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Get migration and user mapping status

To determine when the time-consuming process of creating a large batch of users or migrating users from one cluster to another is complete, this operation retrieves the status of the process.

Authorizations:
(appIdapiKey)
query Parameters
getClusters
boolean

Indicates whether to include the cluster's pending mapping state in the response.

Responses

Response samples

Content type
application/json
{
  • "pending": true,
  • "clusters": {
    }
}

Vaults

Vault operations. Algolia Vault allows you to restrict network-level access to your cluster to a specific set of IP addresses: for non-authorized IP addresses, the cluster is invisible. You should authorize the IP addresses of team members who need to access the Alglolia dashboard, as it's also affected by the restricted list you set up. To access this feature, Algolia Vault must be enabled on your server. Contact Algolia's support team for details.

Note: The maximum number of allowed sources is 1,000.

Get all allowed IP addresses

Get all allowed sources (IP addresses).

Authorizations:
(appIdapiKey)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Replace all sources

Replace all allowed sources.

Authorizations:
(appIdapiKey)
Request Body schema: application/json

Allowed sources.

Array
source
required
string

IP address range of the source.

description
string

Source description.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "updatedAt": "2023-07-04T12:49:15Z"
}

Add a source

Add a source to the list of allowed sources.

Authorizations:
(appIdapiKey)
Request Body schema: application/json

Source to add.

source
required
string

IP address range of the source.

description
string

Source description.

Responses

Request samples

Content type
application/json
{
  • "source": "10.0.0.1/32",
  • "description": "Server subnet"
}

Response samples

Content type
application/json
{
  • "createdAt": "2023-07-04T12:49:15Z"
}

Remove a source

Remove a source from the list of allowed sources.

Authorizations:
(appIdapiKey)
path Parameters
source
required
string
Example: 10.0.0.1/32

IP address range of the source.

Responses

Response samples

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

Advanced

Advanced operations.

Return the latest log entries

The request must be authenticated by an API key with the logs ACL. Logs are held for the last seven days. There's also a logging limit of 1,000 API calls per server. This request counts towards your operations quota but doesn't appear in the logs itself.

Note: To fetch the logs for a Distributed Search Network (DSN) cluster, target the DSN's endpoint.

Authorizations:
(appIdapiKey)
query Parameters
offset
integer
Default: 0

First log entry to retrieve. Sorted by decreasing date with 0 being the most recent.

length
integer <= 1000
Default: 10

Maximum number of entries to retrieve.

indexName
string or null
Example: indexName=products

Index for which log entries should be retrieved. When omitted, log entries are retrieved for all indices.

type
string (logType)
Default: "all"
Enum: "all" "query" "build" "error"

Type of log entries to retrieve. When omitted, all log entries are retrieved.

Responses

Response samples

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

Index settings

replicas
Array of strings
Default: []

Creates replicas, which are copies of a primary index with the same records but different settings.

paginationLimitedTo
integer
Default: 1000

Maximum number of hits accessible through pagination.

unretrievableAttributes
Array of strings
Default: []

Attributes that can't be retrieved at query time.

disableTypoToleranceOnWords
Array of strings
Default: []

Words for which you want to turn off typo tolerance.

attributesToTransliterate
Array of strings

Attributes in your index to which Japanese transliteration applies. This will ensure that words indexed in Katakana or Kanji can also be searched in Hiragana.

camelCaseAttributes
Array of strings
Default: []

Attributes on which to split camel case words.

decompoundedAttributes
object
Default: {}

Attributes in your index to which word segmentation (decompounding) applies.

indexLanguages
Array of strings
Default: []

Set the languages of your index, for language-specific processing steps such as tokenization and normalization.

disablePrefixOnAttributes
Array of strings
Default: []

Attributes for which you want to turn off prefix matching.

allowCompressionOfIntegerArray
boolean
Default: false

Incidates whether the engine compresses arrays with exclusively non-negative integers. When enabled, the compressed arrays may be reordered.

numericAttributesForFiltering
Array of strings
Default: []

Numeric attributes that can be used as numerical filters.

separatorsToIndex
string
Default: ""

Controls which separators are added to an Algolia index as part of normalization. Separators are all non-letter characters except spaces and currency characters, such as $€£¥.

searchableAttributes
userData
object (userData)
Default: {}

Lets you store custom data in your indices.

object

A list of characters and their normalized replacements to override Algolia's default normalization.

attributesForFaceting
Array of strings
Default: []

Attributes used for faceting and the modifiers that can be applied: filterOnly, searchable, and afterDistinct.

attributesToRetrieve
Array of strings
Default: ["*"]

Attributes to include in the API response. To reduce the size of your response, you can retrieve only some of the attributes. By default, the response includes all attributes.

ranking
Array of strings
Default: ["typo","geo","words","filters","proximity","attribute","exact","custom"]

Determines the order in which Algolia returns your results.

customRanking
Array of strings
Default: []

Specifies the Custom ranking criterion. Use the asc and desc modifiers to specify the ranking order: ascending or descending.

relevancyStrictness
integer
Default: 100

Relevancy threshold below which less relevant results aren't included in the results.

attributesToHighlight
Array of strings

Attributes to highlight. Strings that match the search query in the attributes are highlighted by surrounding them with HTML tags (highlightPreTag and highlightPostTag).

attributesToSnippet
Array of strings
Default: []

Attributes to snippet. 'Snippeting' is shortening the attribute to a certain number of words. If not specified, the attribute is shortened to the 10 words around the matching string but you can specify the number. For example: body:20.

highlightPreTag
string
Default: "<em>"

HTML string to insert before the highlighted parts in all highlight and snippet results.

highlightPostTag
string
Default: "</em>"

HTML string to insert after the highlighted parts in all highlight and snippet results.

snippetEllipsisText
string
Default: "…"

String used as an ellipsis indicator when a snippet is truncated.

restrictHighlightAndSnippetArrays
boolean
Default: false

Restrict highlighting and snippeting to items that matched the query.

hitsPerPage
integer (hitsPerPage) [ 1 .. 1000 ]
Default: 20

Number of hits per page.

minWordSizefor1Typo
integer
Default: 4

Minimum number of characters a word in the query string must contain to accept matches with one typo.

minWordSizefor2Typos
integer
Default: 8

Minimum number of characters a word in the query string must contain to accept matches with two typos.

boolean or typoToleranceEnum (string) (typoTolerance)

Controls whether typo tolerance is enabled and how it is applied.

allowTyposOnNumericTokens
boolean
Default: true

Whether to allow typos on numbers ("numeric tokens") in the query string.

disableTypoToleranceOnAttributes
Array of strings
Default: []

Attributes for which you want to turn off typo tolerance.

Array of strings or boolean (ignorePlurals)

Treats singular, plurals, and other forms of declensions as matching terms. ignorePlurals is used in conjunction with the queryLanguages setting. list: language ISO codes for which ignoring plurals should be enabled. This list will override any values that you may have set in queryLanguages. true: enables the ignore plurals feature, where singulars and plurals are considered equivalent ("foot" = "feet"). The languages supported here are either every language (this is the default) or those set by queryLanguages. false: turns off the ignore plurals feature, so that singulars and plurals aren't considered to be the same ("foot" will not find "feet").

Array of strings or boolean (removeStopWords)

Removes stop (common) words from the query before executing it. removeStopWords is used in conjunction with the queryLanguages setting. list: language ISO codes for which stop words should be enabled. This list will override any values that you may have set in queryLanguages. true: enables the stop words feature, ensuring that stop words are removed from consideration in a search. The languages supported here are either every language (this is the default) or those set by queryLanguages. false: turns off the stop words feature, allowing stop words to be taken into account in a search.

keepDiacriticsOnCharacters
string
Default: ""

Characters that the engine shouldn't automatically normalize.

queryLanguages
Array of strings
Default: []

Sets your user's search language. This adjusts language-specific settings and features such as ignorePlurals, removeStopWords, and CJK word detection.

decompoundQuery
boolean
Default: true

Splits compound words into their component word parts in the query.

enableRules
boolean
Default: true

Incidates whether Rules are enabled.

enablePersonalization
boolean
Default: false

Incidates whether Personalization is enabled.

queryType
string (queryType)
Default: "prefixLast"
Enum: "prefixLast" "prefixAll" "prefixNone"

Determines how query words are interpreted as prefixes.

removeWordsIfNoResults
string (removeWordsIfNoResults)
Default: "none"
Enum: "none" "lastWords" "firstWords" "allOptional"

Strategy to remove words from the query when it doesn't match any hits.

mode
string (mode)
Default: "keywordSearch"
Enum: "neuralSearch" "keywordSearch"

Search mode the index will use to query for results.

object (semanticSearch)

Settings for the semantic search part of NeuralSearch. Only used when mode is neuralSearch.

advancedSyntax
boolean
Default: false

Enables the advanced query syntax.

optionalWords
Array of strings
Default: []

Words which should be considered optional when found in a query.

disableExactOnAttributes
Array of strings
Default: []

Attributes for which you want to turn off the exact ranking criterion.

exactOnSingleWordQuery
string (exactOnSingleWordQuery)
Default: "attribute"
Enum: "attribute" "none" "word"

Determines how the Exact ranking criterion is computed when the query contains only one word.

alternativesAsExact
Array of strings (alternativesAsExact)
Default: ["ignorePlurals","singleWordSynonym"]
Items Enum: "ignorePlurals" "singleWordSynonym" "multiWordsSynonym"

Alternatives that should be considered an exact match by the exact ranking criterion.

advancedSyntaxFeatures
Array of strings (advancedSyntaxFeatures)
Default: ["exactPhrase","excludeWords"]
Items Enum: "exactPhrase" "excludeWords"

Allows you to specify which advanced syntax features are active when advancedSyntax is enabled.

attributeForDistinct
string

Name of the deduplication attribute to be used with Algolia's distinct feature.

replaceSynonymsInHighlight
boolean
Default: false

Whether to highlight and snippet the original word that matches the synonym or the synonym itself.

minProximity
integer [ 1 .. 7 ]
Default: 1

Precision of the proximity ranking criterion.

responseFields
Array of strings
Default: []

Attributes to include in the API response for search and browse queries.

maxFacetHits
integer (maxFacetHits) <= 100
Default: 10

Maximum number of facet hits to return when searching for facet values.

maxValuesPerFacet
integer
Default: 100

Maximum number of facet values to return for each facet.

sortFacetValuesBy
string
Default: "count"

Controls how facet values are fetched.

attributeCriteriaComputedByMinProximity
boolean
Default: false

When the Attribute criterion is ranked above Proximity in your ranking formula, Proximity is used to select which searchable attribute is matched in the Attribute ranking stage.

object (renderingContent)

Extra content for the search UI, for example, to control the ordering and display of facets. You can set a default value and dynamically override it with Rules.

enableReRanking
boolean
Default: true

Indicates whether this search will use Dynamic Re-Ranking.

(Array of listOfSearchFilters (Array of searchFiltersArrayString (strings) or strings or null)) or (string or null) (reRankingApplyFilter)

When Dynamic Re-Ranking is enabled, only records that match these filters will be affected by Dynamic Re-Ranking.

{
  • "replicas": [
    ],
  • "paginationLimitedTo": 20,
  • "unretrievableAttributes": [
    ],
  • "disableTypoToleranceOnWords": [
    ],
  • "attributesToTransliterate": [
    ],
  • "camelCaseAttributes": [
    ],
  • "decompoundedAttributes": {
    },
  • "indexLanguages": [
    ],
  • "disablePrefixOnAttributes": [
    ],
  • "allowCompressionOfIntegerArray": false,
  • "numericAttributesForFiltering": [
    ],
  • "separatorsToIndex": "+#",
  • "searchableAttributes": [
    ],
  • "userData": {
    },
  • "customNormalization": "{default: {'ä': 'ae', 'ü': 'ue'}}\n",
  • "attributesForFaceting": [
    ],
  • "attributesToRetrieve": [
    ],
  • "ranking": [
    ],
  • "customRanking": [
    ],
  • "relevancyStrictness": 90,
  • "attributesToHighlight": [
    ],
  • "attributesToSnippet": [
    ],
  • "highlightPreTag": "<em>",
  • "highlightPostTag": "</em>",
  • "snippetEllipsisText": "…",
  • "restrictHighlightAndSnippetArrays": false,
  • "hitsPerPage": 20,
  • "minWordSizefor1Typo": 4,
  • "minWordSizefor2Typos": 8,
  • "typoTolerance": true,
  • "allowTyposOnNumericTokens": true,
  • "disableTypoToleranceOnAttributes": [
    ],
  • "ignorePlurals": [
    ],
  • "removeStopWords": [
    ],
  • "keepDiacriticsOnCharacters": "øé",
  • "queryLanguages": [
    ],
  • "decompoundQuery": true,
  • "enableRules": true,
  • "enablePersonalization": false,
  • "queryType": "prefixLast",
  • "removeWordsIfNoResults": "firstWords",
  • "mode": "neuralSearch",
  • "semanticSearch": {
    },
  • "advancedSyntax": false,
  • "optionalWords": [
    ],
  • "disableExactOnAttributes": [
    ],
  • "exactOnSingleWordQuery": "attribute",
  • "alternativesAsExact": [
    ],
  • "advancedSyntaxFeatures": [
    ],
  • "distinct": 1,
  • "attributeForDistinct": "url",
  • "replaceSynonymsInHighlight": false,
  • "minProximity": 1,
  • "responseFields": [ ],
  • "maxFacetHits": 10,
  • "maxValuesPerFacet": 100,
  • "sortFacetValuesBy": "count",
  • "attributeCriteriaComputedByMinProximity": false,
  • "renderingContent": {
    },
  • "enableReRanking": true,
  • "reRankingApplyFilter": [
    ]
}

.