API reference / Search API

Search API

The Search REST API is the core of Algolia Search. Around it, Algolia built a complete ecosystem, of libraries, tools, and a dashboard. You should use the official API clients and libraries to implement Algolia. They’re all open source, and the code is available on GitHub.

There’s no SLA if you use the REST API directly.

Hosts

The REST API lets you interact directly with Algolia from anything that can send an HTTP request. All API access must use HTTPS.

The primary hosts are {Application-ID}.algolia.net for write operations and {Application-ID}-dsn.algolia.net for read operations. The *-dsn host guarantees high availability through automatic load balancing and also leverages the Distributed Search Network (if you subscribed that option).

To guarantee a high availability, you should implement a retry strategy for all API calls on the following fallback hosts: {Application-ID}-1.algolianet.com, {Application-ID}-2.algolianet.com, {Application-ID}-3.algolianet.com. (Note that the domain is different because it’s hosted on another DNS provider, to increase reliability). It’s best to shuffle (randomize) the list of fallback hosts to ensure load balancing across clients. All Algolia API clients implement this retry strategy.

You can find the Application-ID in the Algolia dashboard.

The relative path prefix /1/ indicates that you’re using version 1 of the API.

Format

The entire API uses JSON encoded as UTF-8. The Content-Type header for both request bodies and responses is application/json; charset=UTF-8.

The body of POST and PUT requests must be either a JSON object or a JSON array, depending on the endpoint.

The body of responses is always a JSON object. Don’t rely on the order of attributes in the JSON response, as JSON doesn’t guarantee a stable ordering of keys in an object.

Parameters

Unless otherwise stated, parameters must be passed:

  • In the URL query string for GET and DELETE requests
  • In the request body for PUT and POST requests

Parameters passed in the URL must be properly URL-encoded, using the UTF-8 encoding for non-ASCII characters. Furthermore, the plus character (+) is interpreted as a space (it’s therefore an alternative to %20).

Arrays

Unless otherwise stated, arrays passed in the URL can be specified either:

  • As a comma-separated string; example: attributesToRetrieve=title,description; or
  • As a JSON array (which must be properly URL-encoded); example: attributesToRetrieve=%5B%22title%22,%22description%22%5D.

Arrays passed in the body must always be regular JSON arrays.

Authentication

To authenticate your API requests, add these headers:

  • X-Algolia-Application-Id: the ID of your Algolia application
  • X-Algolia-API-Key: an API key

You can find your application ID and manage your API keys in the Algolia dashboard.

Algolia supports Cross-Origin Resource Sharing (CORS), so that you can use these headers in conjunction with XMLHttpRequest.

Secured API keys

To restrict the scope of an API key, use secured API keys.

Adding a filter or other parameters to a search query in your frontend exposes it to users. If you want to prevent users from changing or removing the parameters, you can encode them in a secured API key, so that they can’t be removed or changed on the client.

Instead of using the search API key and applying a filter at query time, you request a secured API key from your backend. On your backend, you use one of Algolia’s API clients to generate a secured API key. Then, your users use the secured API keys to search. They won’t be able to change or remove the parameters from the secured API keys.

A secured API key is used like any other API key via the X-Algolia-API-Key request header.

Generate a secured API key

A secured API key is a form of hash-based message authentication code (HMAC), using the parent API key as a secret and the query parameters as a message.

To generate a secured API key on your backend, use the built-in method of Algolia’s API clients.

The process for creating a secured API key is as follows:

  1. Compute a SHA-256 HMAC with:

    • Your API key (secret). Any API key except the Admin API key is accepted.

    • A URL-encoded list of query parameters (message). These are the restrictions you want to enforce on this API key.

  2. Concatenate the SHA-256 HMAC with the list of query parameters to a single string.
  3. Encode the string in Base64.

Restriction parameters

You can encode any query parameter in the secured API keys. Secured API keys can also contain these parameters as further constraints:

Name Type Description
userToken string An identifier used for rate limiting, to differentiate users using the same IP address.
validUntil integer Expiration time of the API key as a Unix timestamp.
restrictIndices list of strings Comma-separated list of allowed index names for the secured API key.
referers string array

Restricts the API key to specific referrers. If empty or blank, defaults to all referrers. You can specify a pattern with either a leading or trailing wildcard (*), or both.

For example:

  • https://algolia.com/* allows referrers starting with https://algolia.com/
  • *.algolia.com allows referrers ending with .algolia.com
  • *algolia.com*
    • allows all referrers from the domain algolia.com.
The parameter is intentionally spelled as referers to be conform with RFC 1945.
restrictSources string Allowed IPv4 network for the secured API key.

Some browsers intentionally remove the Referer and Origin headers from third-party requests. If you’re using a search API key with restrictions on the referrer, this will prevent users from searching on these browsers.

Error handling

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

When a request fails, the response body is still JSON, but always contains a message field with a description of the error, which you can inspect for debugging. For example, trying to add an object with an invalid key will return the message:

Copy 
1
2
3

{
  "message": "Invalid Application-Id or API-Key"
}

Search endpoints

Quick reference

Verb Path Method

POST

/1/indexes/{indexName}/query

Search index (POST)

GET

/1/indexes/{indexName}

Search index (GET)

POST

/1/indexes/*/queries

Search multiple indices

POST

/1/indexes/{indexName}/facets/{facetName}/query

Search for facet values

POST

/1/indexes/{indexName}/browse

Browse index (POST)

GET

/1/indexes/{indexName}/browse

Browse index (GET)

Search index (POST)

A

Path: /1/indexes/{indexName}/query
HTTP Verb: POST
Required API Key: any key with the search ACL

Description:

Return objects that match the query.

You can find the list of parameters that you can use in the POST body in the Search Parameters section.

Alternatively, parameters may be specified as a URL-encoded query string inside the params attribute.

This method has a constant URL, thus allowing the web browser to cache Cross-Origin Resource Sharing (CORS) OPTION requests.

Parameters:

Parameter Description
params
type: URL-encoded string
default: "" (no search parameters)
Optional

Search parameters

Errors:

  • 400: Bad request or request argument
  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "params": "query=george%20clo&hitsPerPage=2&getRankingInfo=1" }' \
     "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/imdb/query"

When the query is successful, the HTTP response is a 200 OK and returns the list of results in the hits attribute of the returned JSON object:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

{
    "hits": [
        {
            "name": "George Clooney",
            "objectID": "2051967",
            "_highlightResult": {
                "name": {
                    "value": "<em>George</em> <em>Clo</em>oney",
                    "matchLevel": "full"
                }
            },
            "_snippetResult": {
                "bio": {
                    "value": "is the son of <em>George</em> <em>Clo</em>oney as was his father"
                }
            },
            "_rankingInfo": {
                "nbTypos": 0,
                "firstMatchedWord": 0,
                "proximityDistance": 1,
                "userScore": 5,
                "geoDistance": 0,
                "geoPrecision": 1,
                "nbExactWords": 0
            }
        },
        {
            "name": "George Clooney's Irish Roots",
            "year": "(2012 Documentary)",
            "objectID": "825416",
            "_highlightResult": {
                "name": {
                    "value": "<em>George</em> <em>Clo</em>oney's Irish Roots",
                    "matchLevel": "full"
                },
                "year": {
                    "value": "(2012 Documentary)",
                    "matchLevel": "none"
                }
            },
            "_rankingInfo": {
                "nbTypos": 0,
                "firstMatchedWord": 0,
                "proximityDistance": 1,
                "userScore": 4,
                "geoDistance": 0,
                "geoPrecision": 1,
                "nbExactWords": 0
            }
        }
    ],
    "page": 0,
    "nbHits": 38,
    "nbPages": 19,
    "hitsPerPage": 2,
    "processingTimeMS": 6,
    "query": "george clo",
    "parsedQuery": "george clo",
    "params": "query=george%20clo&hitsPerPage=2&getRankingInfo=1"
}

Search index (GET)

A

Path: /1/indexes/{indexName}
HTTP Verb: GET
Required API Key: any key with the search ACL

Description:

You can also query an index with a GET request.

The GET method’s URL varies with the search parameters, and thus forces the browser to perform one Cross-Origin Resource Sharing (CORS) OPTION request for each query, without any way to cache them. Its use is therefore discouraged.

Parameters

You can pass any of the Search Parameters in the URL’s query string.

Errors:

  • 400: Bad request or request argument
  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/imdb?query=george%20clo&hitsPerPage=2&getRankingInfo=1"

Search multiple indices

A

Path: /1/indexes/*/queries
HTTP Verb: POST
Required API Key: any key with the search ACL

Description:

This method allows to send multiple search queries, potentially targeting multiple indices, in a single API call.

Parameters:

Parameter Description
requests
type: list
Required

A list of queries. Results will be received in the same order as the queries in the requests attribute.

Each query is described by the following attributes:

  • indexName: index targeted by the query;
  • params: URL-encoded list of search parameters.
strategy
type: string
default: "none"
Optional

Allows optimizing execution of the queries by potentially skipping some of them.

The following values are allowed:

  • none: Execute all queries.

  • stopIfEnoughMatches: Execute queries one by one, but stop as soon as one query matches at least as many hits as its hitsPerPage parameter. More formally: query N is executed only if all of queries 0 through N-1 had strictly less hits than their requested number of hits per page.

Let’s illustrate stopIfEnoughMatches: Let’s say you send 3 queries with hitsPerPage set to 50, 5 and 20 (respectively). There are different possible scenarios:

  1. Run query #1
    • 50+ hits are found: skip to step 4
    • otherwise: continue with query #2
  2. Run query #2
    • 5+ hits where found: skip to step 4
    • otherwise: continue with query #3
  3. Run query #3
    • This is the last query, so we don’t care about its outcome
  4. Return results
    • Return actual results for queries that were processed
    • Return empty hits for queries that were skipped, along with a processed attribute set to false

Errors:

  • 400: Bad request argument
  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4
5
6
7
8
9
10

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "requests": [
                        { "indexName": "index1", "params": "query=van" },
                        { "indexName": "index2", "params": "query=van" }
                      ],
                      "strategy": "none"
                    }' \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/*/queries"

When queries are successful, the HTTP response is a 200 OK and returns all results:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

{
  "results":[
    {
      "hits":[
        {
          "name": "Betty Jane Mccamey",
          "company": "Vita Foods Inc.",
          "email": "betty@mccamey.com",
          "objectID": "6891Y2usk0",
          "_highlightResult": {
              "name": {"value": "Betty <b>Jan</b>e Mccamey", "matchLevel": "full"},
              "company": {"value": "Vita Foods Inc.", "matchLevel": "none"},
              "email": {"value": "betty@mccamey.com", "matchLevel": "none"}
          }
        }],
      "page": 0,
      "nbHits": 1,
      "nbPages": 1,
      "hitsPerPage": 20,
      "processingTimeMS": 1,
      "query": "van",
      "params": "query=van",
      "index": "index1"
    },
    {
      "hits": [
        {
          "name": "Gayla Geimer Dan",
          "company": "Ortman Mccain Co",
          "email": "gayla@geimer.com",
          "objectID": "ap78784310"
          "_highlightResult": {
            "name": {"value": "Gayla Geimer <b>Dan</b>", "matchLevel": "full" },
            "company": {"value": "Ortman Mccain Co", "matchLevel": "none" },
            "email": {"highlighted": "gayla@geimer.com", "matchLevel": "none" }
          }
        }],
      "page": 0,
      "nbHits": 1,
      "nbPages": 1,
      "hitsPerPage": 20,
      "processingTimeMS": 1,
      "query": "van",
      "params": "query=van",
      "index": "index2"
    }
  ]
}

Search for facet values

A

Path: /1/indexes/{indexName}/facets/{facetName}/query
HTTP Verb: POST
Required API Key: any key with the search ACL

Description:

Search for values of a given facet, optionally restricting the returned values to those contained in objects matching other search criteria.

Pagination isn’t supported (page and hitsPerPage parameters are ignored). By default, the engine returns a maximum of 10 values. You can adjust with maxFacetHits.

Parameters:

Parameter Description
params
type: URL-encoded query string
default: ""
Optional

Search parameters. You may use this parameter to specify parameters specific to this endpoint. You may also specify any number of other regular search parameters. They will apply to objects in the index.
facetQuery
type: string
default: ""
Optional

Text to search inside the facet’s values.
maxFacetHits
type: integer
default: 10
Optional

The maximum number of facet hits to return.

For performance reasons, the maximum allowed number of returned values is 100.

Errors:

  • 400: Attribute facetName isn’t in attributesForFaceting, or not with the searchable() specifier
  • 404: Index indexName doesn’t exist

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{\"params\": \"facetQuery=${facetQuery}\"}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/facets/${facetName}/query"

When the query is successful, the HTTP response is a 200 OK. It contains values that match the queried text, and that are contained in at least one object matching the other search parameters.

The response body contains the following fields:

  • facetHits (array): Matched values. Each hit contains the following fields:
    • value (string): Raw value of the facet
    • highlighted (string): Highlighted facet value
    • count (integer): How many objects contain this facet value. This takes into account the extra search parameters specified in the query. Like for a regular search query, the counts may not be exhaustive. See the related discussion.

Values are sorting by decreasing frequency.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "facetHits": [
        {
            "value": "Mobile phones",
            "highlighted": "Mobile <em>phone</em>s",
            "count": 507
        },
        {
            "value": "Phone cases",
            "highlighted": "<em>Phone</em> cases",
            "count": 63
        }
    ]
}

Browse index (POST)

A

Path: /1/indexes/{indexName}/browse
HTTP Verb: POST
Required API Key: any key with the browse ACL

Description:

Retrieve all objects from an index, for example, as a backup, for SEO, or for analytics. Each API request retrieves up to 1,000 objects and supports filters and full-text search via the params parameter.

For better performance, browse doesn’t support:

  • The distinct query parameter (used for grouping or deduplication)
  • Sorting by typos, proximity, words or geo distance (only the custom ranking is applied)

Pagination

If your index has more than 1,000 objects, the API response includes a cursor field. You can include this cursor in your next API request to get the next page of results. When you reached the end of the index, cursor is absent from the response.

Alternatively, you can include hitsPerPage and page in your params to paginate the results.

Parameters:

Parameter Description
params
type: URL-encoded string
default: "" (no search parameters)
Optional

Search parameters used to filter the index content. If not specified, all objects are returned. Can only be used on the first call.
cursor
type: string
default: (no search parameters)
yes (on subsequent calls)

Cursor indicating the location to resume browsing from. Must match the value returned by the previous call.

Errors:

  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data '{}' \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/contacts/browse"

Upon success, the response is 200 OK and returns the list of matching hits:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "hits":[
    {
      "name": "Betty Jane Mccamey",
      "company": "Vita Foods Inc.",
      "email": "betty@mccamey.com",
      "objectID": "6891Y2usk0"
    }
  ],
  "page": 0,
  "nbHits": 10000,
  "nbPages": 10,
  "hitsPerPage": 1000,
  "processingTimeMS": 1,
  "query": "",
  "params": ""
  "cursor": "jMDY3M2MwM2QwMWUxMmQwYWI0ZTN",
}

Browse index (GET)

A

Path: /1/indexes/{indexName}/browse
HTTP Verb: GET
Required API Key: any key with the browse ACL

Description:

This method is an alternative to Browse index (POST). Add the parameters as URL-encoded query parameters.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/contacts/browse?filters%3Dprice%3C500"

Objects endpoints

Quick reference

Verb Path Method

POST

/1/indexes/{indexName}

Add or replace object

PUT

/1/indexes/{indexName}/{objectID}

Add or replace object by ID

DELETE

/1/indexes/{indexName}/{objectID}

Delete object

POST

/1/indexes/{indexName}/deleteByQuery

Delete by

POST

/1/indexes/{indexName}/clear

Clear objects

POST

/1/indexes/{indexName}/{objectID}/partial

Partially update objects

POST

/1/indexes/{indexName}/batch

Batch write operations

POST

/1/indexes/*/batch

Batch write operations (multiple indices)

POST

/1/indexes/*/objects

Get objects

GET

/1/indexes/{indexName}/{objectID}

Get object

Add or replace object

A

Path: /1/indexes/{indexName}
HTTP Verb: POST
Required API Key: any key with the addObject ACL

Description:

Add a single record to an index or replace it.

If the object doesn’t contain an objectID property, Algolia automatically adds it.

If you call this method with an existing objectID, the existing record is replaced with the new one.

If you want to add multiple records to your index in a single API request, use the /batch endpoint.

Errors:

  • 400: Invalid indexName or JSON

Example:

A

Copy 
1
2
3
4
5
6
7
8

curl "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     -d '{
          "name": "Betty Jane Mccamey",
          "company": "Vita Foods Inc.",
          "email": "betty@mccamey.com"
        }'

Successful API requests respond with 201 Created.

A successful response means that the operation is scheduled. It might not run immediately. Check the status of the operation with the taskID attribute and the get task status method.

Copy 
1
2
3
4
5

{
  "updatedAt": "2023-03-22T09:37:00.193Z",
  "taskID": 82061078001,
  "objectID": "myID"
}

Add or replace object by ID

A

Path: /1/indexes/{indexName}/{objectID}
HTTP Verb: PUT
Required API Key: any key with the addObject ACL

Description:

Add a single object to an index or replace it.

If the object doesn’t exist, it will be added to the index. If it exists, the object will be completely replaced.

If you want to update only some attributes of an existing object, use a partial update instead.

To update multiple objects in a single API request, use the /batch endpoint.

Errors:

  • 400: Invalid indexName or JSON

Example:

A

Copy 
1
2
3
4
5
6
7
8
9

curl "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/myID" \
     -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     -d '{
            "name": "Betty Jane Mccamey",
            "company": "Vita Foods Inc.",
            "email": "betty@mccamey.com"
         }'

Successful API requests respond with 201 Created.

A successful response means that the operation is scheduled. It might not run immediately. Check the status of the operation with the taskID attribute and the get task status method.

Copy 
1
2
3
4
5

{
  "updatedAt": "2023-03-22T09:23:34.155Z",
  "taskID": 82061078001,
  "objectID": "myID"
}

Delete object

A

Path: /1/indexes/{indexName}/{objectID}
HTTP Verb: DELETE
Required API Key: any key with the deleteObject ACL

Description:

Delete an existing record from an index.

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/myID"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, but it may not have been executed yet. You can check the status of the operation via the taskID attribute and the get task status command.

Copy 
1
2
3
4

{
  "deletedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 681
}

Delete by

A

Path: /1/indexes/{indexName}/deleteByQuery
HTTP Verb: POST
Required API Key: any key with the deleteIndex ACL

Description:

Delete all records matching the query.

This endpoint doesn’t support all the options of a query, only its filters (numeric, facet, or tag) and geo queries. It also doesn’t accept empty filters or query.

Example:

A

Copy 
1
2
3
4
5
6

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
      "params":"facetFilters=category:test"}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/deleteByQuery" \

Upon success, the response is a 200 OK and a task to delete the record matching the query is created

Copy 
1
2
3
4

{
    "deletedAt":"2013-01-18T15:33:13.556Z",
    "taskID": 4242
}

Clear objects

A

Path: /1/indexes/{indexName}/clear
HTTP Verb: POST
Required API Key: any key with the deleteIndex ACL

Description:

Delete an index’s content, but leave settings and index-specific API keys untouched.

Errors:

  • 400: Invalid indexName

Example:

A

Copy 
1
2
3
4

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/myIndex/clear"

When delete is successful, the HTTP response is a 200 OK and returns the delete date:

Copy 
1
2
3
4

{
    "updatedAt": "2013-01-18T15:33:13.556Z",
    "taskID": 722
}

Partially update objects

A

Path: /1/indexes/{indexName}/{objectID}/partial
HTTP Verb: POST
Required API Key: any key with the addObject ACL

Description:

Update one or more attributes of records.

This method creates a new record if one doesn’t already exist (and the createIfNotExists parameter is set to true).

You can pass any first-level attribute you want to add or replace within the record, but you can’t individually update nested attributes. If you specify a nested attribute, the engine treats it as a replacement of its first-level ancestor.

Built-in operations

To update an attribute without pushing the entire record, you can use these built-in operations. These operations can be helpful if you don’t have access to your initial data.

  • Increment: increment a numeric attribute
  • Decrement: decrement a numeric attribute
  • Add: append a number or string element to an array attribute
  • Remove: remove all matching number or string elements from an array attribute made of numbers or strings
  • AddUnique: add a number or string element to an array attribute made of numbers or strings only if it’s not already present
  • IncrementFrom: increment a numeric integer attribute only if the provided value matches the current value, and otherwise ignore the whole object update. For example, if you pass an IncrementFrom value of 2 for the version attribute, but the current value of the attribute is 1, the engine ignores the update. If the object doesn’t exist, the engine only creates it if you pass an IncrementFrom value of 0.
  • IncrementSet : increment a numeric integer attribute only if the provided value is greater than the current value, and otherwise ignore the whole object update. For example, if you pass an IncrementSet value of 2 for the version attribute, and the current value of the attribute is 1, the engine updates the object. If the object doesn’t exist yet, the engine only creates it if you pass an IncrementSet value that’s greater than 0.

For Remove and AddUnique: the operation will be silently ignored if the array attribute has any nested object or array.

You can specify an operation by providing an object with the attribute to update as the key and its value being an object with the following properties:

  • _operation: the operation to apply on the attribute
  • value: the right-hand side argument to the operation, for example, increment or decrement step, value to add or remove

Only the IncrementFrom and IncrementSet operations guarantee idempotent record updates. The other built-in operations aren’t idempotent and can cause unexpected side-effects, unless you use them in combination with the idempotent operations. For example, if you’re using the Increment or Decrement operations in a concurrent or multi-threaded environment, you may trigger it more than once and end up with wrong data in your records.

For example:

Copy 
1
2
3
4
5
6

{
  "_tags": {
    "_operation": "AddUnique",
    "value": "public"
  }
}
Copy 
1
2
3
4
5
6

{
  "count": {
    "_operation": "Increment",
    "value": 2
  }
}

Parameters:

Parameter Description
createIfNotExists
type: boolean
default: true
Optional

If true, updating a record with a non-existing objectID creates a new record with the specified attributes. If false, trying to update a record with non-existing objectID is silently ignored (no error will be returned).

Errors:

  • 400: Invalid indexName or JSON

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{"email": "betty@mccamey.com" }' \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/myID/partial"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, but it may not have been executed yet. You can check the status of the operation via the taskID attribute and the get task status command.

Copy 
1
2
3
4
5

{
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 680,
  "objectID": "myID"
}

Batch write operations

A

Path: /1/indexes/{indexName}/batch
HTTP Verb: POST
Required API Key: any key with the depends on operations performed inside the batch ACL

Description:

Perform multiple write operations in a single API call.

In order to reduce the amount of time spent on network round trips, you can perform multiple write operations at once. All operations will be applied in the order they are specified.

Operations you can batch

The following actions are supported:

  • addObject: Add an object. Equivalent to Add or replace an object.

  • updateObject: Add or replace an existing object. You must set the objectID attribute to indicate the object to update. Equivalent to Add or replace an object by ID.

  • partialUpdateObject: Partially update an object. You must set the objectID attribute to indicate the object to update. Equivalent to Partially update an object.

  • partialUpdateObjectNoCreate: Same as partialUpdateObject, except that the object is not created if the object designated by objectID does not exist.

  • deleteObject: Delete an object. You must set the objectID attribute to indicate the object to delete. Equivalent to Delete an object.

  • delete: Delete the index. Equivalent to Delete an index.

  • clear: Remove the index’s content, but keep settings and index-specific API keys untouched. Equivalent to Clear objects.

Parameters:

Parameter Description
requests
type: list
Required

List of operations to batch.

Each operation is described by:

  • action (string): type of operation
  • body (object): arguments to the operation (depends on the type of the operation)

Example:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "requests": [
    {
      "action": "addObject",
      "body": {
                "name": "Betty Jane Mccamey",
                "company": "Vita Foods Inc.",
                "email": "betty@mccamey.com"
              }
    },
    {
        "action": "addObject",
        "body": {
                  "name": "Gayla Geimer",
                  "company": "Ortman Mccain Co",
                  "email": "gayla@geimer.com"
                }
      }
  ]
}

If the batch is stored in the file batchFile.json, the following curl command will apply it:

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary @batchFile.json \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/batch"

Upon success, the response is 200 OK.

A successful response indicates that the operations have been taken into account, but they may not have been executed yet. You can check the status of the operations via the taskID attribute and the get task status command.

A typical response is:

Copy 
1
2
3
4

{
  "taskID": 792,
  "objectIDs": ["6891", "6892"]
}

Batch write operations (multiple indices)

A

Path: /1/indexes/*/batch
HTTP Verb: POST
Required API Key: any key with the depends on operations performed inside the batch ACL

Description:

Perform multiple write operations, potentially targeting multiple indices, in a single API call.

This is essentially a multi-index version of Batch write operations. It can be useful to modify multiple indices at the same time, for example, if you have one index per user.

Parameters:

Parameter Description
requests
type: list
Required

List of operations to batch.

Each operation is described by:

  • indexName (string): name of the index targeted by this operation
  • action (string): type of operation, see list of batch operations.
  • body (object): arguments to the operation (depends on the type of the operation)

Errors:

  • 400: Invalid JSON

Example:

A

The payload format is similar to the one-index batch write operations. You just need to add an indexName attribute to each request to indicate which index is targeted:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "requests": [
    {
      "action": "addObject",
      "indexName": "contacts",
      "body": {
        "name": "Betty Jane Mccamey",
        "company": "Vita Foods Inc.",
        "email": "betty@mccamey.com"
      }
    },
    {
      "action": "addObject",
      "indexName": "public_contacts",
      "body": {
        "name": "Gayla Geimer",
        "company": "Ortman Mccain Co",
        "email": "gayla@geimer.com"
      }
    }
  ]
}

For example, if the batch is stored in the file batchFile.json, the following curl command will apply it:

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary @batchFile.json \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/*/batch"

Upon success, the response is 200 OK.

A successful response indicates that the operations have been taken into account, but they may not have been executed yet. You can check the status of the operations via their taskID attribute and the get task status command. There is one taskID per targeted index.

A typical response is:

Copy 
1
2
3
4
5
6
7

{
  "taskID": {
      "contacts": 792,
      "public_contacts": 793
    },
  "objectIDs": ["6891", "6892"]
}

Get objects

A

Path: /1/indexes/*/objects
HTTP Verb: POST
Required API Key: any key with the search ACL

Description:

Get one or more records, potentially from different indices, in a single API call.

The request body must contain:

  • requests (array of objects): list of objects to retrieve. Each object is identified by:
    • index_name (string): name of the index containing the record
    • objectID (string): ID of the record within that index
    • attributesToRetrieve (array of strings) (optional): List of attributes to retrieve. By default, all retrievable attributes are returned.

Results will be received in the same order as the requests.

Errors:

  • 400: Bad request argument
  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4
5
6
7
8

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "requests": [
                      { "indexName": "index1", "objectID": "myId1" },
                      { "indexName": "index1", "objectID": "myId2" }
                    ] }' \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/*/objects"

The HTTP response is a 200 OK and returns an array of objects:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "results":[
    {
      "name": "Betty Jane Mccamey",
      "email": "betty@mccamey.com",
      "objectID": "myId1"
    },
    {
      "name": "Stacey Blow",
      "email": "stacey@blow.com"
      "objectID": "myId2"
    }
  ]
}

If one objectID does not exist null will be returned for this object.

Get object

A

Path: /1/indexes/{indexName}/{objectID}
HTTP Verb: GET
Required API Key: any key with the search ACL

Description:

Retrieve one object from the index.

Parameters:

Parameter Description
attributesToRetrieve
type: list
default: all retrievable attributes
formerly known as: attributes
Optional

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

objectID is always retrieved, even when not specified.

Attributes listed in unretrievableAttributes will not be retrieved even if requested, unless the request is authenticated with the admin API key.

Errors:

  • 404: Index or object does not exist

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/contacts/myID?attributes=email,name"

When the command is successful, the HTTP response is a 200 OK and returns the object:

Copy 
1
2
3
4
5

{
  "name": "Betty Jane Mccamey",
  "email": "betty@mccamey.com",
  "objectID": "myID"
}

Settings endpoints

Quick reference

Verb Path Method

GET

/1/indexes/{indexName}/settings

Get settings

PUT

/1/indexes/{indexName}/settings

Set settings

Get settings

A

Path: /1/indexes/{indexName}/settings
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

Retrieve index settings.

Find the list of settings in the Settings API parameters page.

The response only includes values for settings that aren’t null.

Errors:

  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/contacts/settings"

Upon success, the response is 200 OK and returns all index settings:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
    "minWordSizefor1Typo": 4,
    "minWordSizefor2Typos": 8,
    "hitsPerPage": 20,
    "searchableAttributes": null,
    "attributesToRetrieve": null,
    "attributesToSnippet": null,
    "attributesToHighlight": null,
    "ranking": [
        "typo",
        "geo",
        "words",
        "proximity",
        "attribute",
        "exact",
        "custom"
    ],
    "customRanking": null,
    "separatorsToIndex": "",
    "queryType": "prefixAll"
}

Set settings

A

Path: /1/indexes/{indexName}/settings
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL

Description:

Update some index settings.

Only specified settings are overridden; unspecified settings are left unchanged. Specifying null for a setting resets it to its default value.

The supported settings are listed in the Settings Parameters page.

Parameters:

Parameter Description
forwardToReplicas
type: boolean
default: false
formerly known as: forwardToSlaves
Optional

(URL parameter) If this parameter is added to the URL, the change is also propagated to replicas of this index.

Errors:

  • 400: Invalid JSON

Example:

A

Copy 
1
2
3
4
5
6
7
8
9

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{
      "hitsPerPage": 50,
      "searchableAttributes": ["name", "email", "address"],
      "customRanking": ["desc(population)", "asc(name)"]
     }' \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/settings?forwardToReplicas=true"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, but it may not have been executed yet. You can check the status of the operation via the taskID attribute and the get task status command. The taskID will mark the operation as completed once the settings are propagated to all replicas.

Copy 
1
2
3
4

{
    "updatedAt": "2013-08-21T13:20:18.960Z",
    "taskID": 10210332
}

Manage indices endpoints

Quick reference

Verb Path Method

DELETE

/1/indexes/{indexName}

Delete index

POST

/1/indexes/{indexName}/operation

Copy/move index

GET

/1/indexes

List indices

Delete index

A

Path: /1/indexes/{indexName}
HTTP Verb: DELETE
Required API Key: any key with the deleteIndex ACL

Description:

Delete an index.

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${YOUR_INDEX_NAME}"

When delete is successful, the HTTP response is a 200 OK and returns the delete date:

Copy 
1
2
3
4

{
    "deletedAt": "2013-01-18T15:33:13.556Z",
    "taskID": 721
}

Copy/move index

A

Path: /1/indexes/{indexName}/operation
HTTP Verb: POST
Required API Key: any key with the addObject ACL

Description:

Copy or move an existing index.

If the destination index already exists, its API keys are preserved, and the source API keys are added (unless performing a partial copy, see below).

When copying, you may specify optional scopes to the operation. Doing so results in a partial copy: it only copies the specified scopes, replacing the corresponding scopes in the destination. The other scopes, as well as the records and the index-specific API keys, are left untouched.

Possible scopes are “settings”, “synonyms”, and “rules”. Keep in mind that when you use the scope parameter, you’re no longer copying records but only the specified scopes. On the other hand, if you don’t specify a scope (that is, you omit the scope parameter) then the copy command work as by default: copying all records, settings, Synonyms, and Rules.

Parameters:

Parameter Description
operation
type: string
Required

Type of operation to perform: move or copy.
destination
type: string
Required

Name of the destination index.
scope
type: list
Optional

Scope of the data to copy. When absent, a full copy is performed. When present, only the selected scopes are copied. Allowed scopes are: settings, synonyms and rules. This parameter is only allowed when operation is copy.

Errors:

  • 400: Invalid JSON

Example:

A

Here is an example to copy index1 to index2:

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "operation": "copy", "destination":"index2" }' \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${YOUR_INDEX_NAME}/operation"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, but it may not have been executed yet. You can check the status of the operation via the taskID attribute and the get task status command.

Copy 
1
2
3
4

{
    "updatedAt":"2013-09-03T19:55:41.346Z",
    "taskID":96
}

List indices

A

Path: /1/indexes
HTTP Verb: GET
Required API Key: any key with the listIndexes ACL

Description:

List all indices.

Parameters:

Parameter Description
page
type: integer
Optional

Retrieve a specific page. Pages are zero-based. The page size is set to 100. This parameter isn’t set by default, and all indices are retrieved at once.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes"

When the query is successful, the HTTP response is a 200 OK and returns a list of index with associated number of entries.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "items": [
    {
      "name": "contacts",
      "createdAt": "2013-08-15T19:49:47.714Z",
      "updatedAt": "2013-08-17T07:59:28.313Z",
      "entries": 2436442,
      "dataSize": 224152664,
      "fileSize": 269450853,
      "lastBuildTimeS": 0,
      "numberOfPendingTask": 0,
      "pendingTask": false
    }
  ],
  "nbPages": 1
}

Synonyms endpoints

Quick reference

Verb Path Method

PUT

/1/indexes/{indexName}/synonyms/{objectID}

Save synonym

POST

/1/indexes/{indexName}/synonyms/batch

Save synonyms

GET

/1/indexes/{indexName}/synonyms/{objectID}

Get synonym

POST

/1/indexes/{indexName}/synonyms/clear

Clear all synonyms

DELETE

/1/indexes/{indexName}/synonyms/{objectID}

Delete synonym

POST

/1/indexes/{indexName}/synonyms/search

Search synonyms

Save synonym

A

Path: /1/indexes/{indexName}/synonyms/{objectID}
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL

Description:

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.

The body of the request must be a JSON object representing the synonyms. It must contain the following attributes:

  • objectID (string): Unique identifier of the synonym object to be created or updated.
  • type (string): Type of the synonym object (see below).

The rest of the body depends on the type of synonyms to add:

synonym Multi-way synonyms (a.k.a. “regular synonyms”). A set of words or phrases that are all substitutable to one another. Any query containing one of them can match records containing any of them. The body must contain the following fields:

  • synonyms (array of strings): Words or phrases to be considered equivalent.

Example:

Copy 
1
2
3
4
5

{
    "objectID": "1",
    "type": "synonym",
    "synonyms": ["iphone", "ephone", "aphone", "yphone", "apple phone"]
}

onewaysynonym One-way synonym. Alternative matches for a given input. If the input appears inside a query, it will match records containing any of the defined synonyms. The opposite is not true: if a synonym appears in a query, it will not match records containing the input, nor the other synonyms. The body must contain the following fields:

  • input (string): Word or phrase to appear in query strings.
  • synonyms (array of strings): Words or phrases to be matched in records.

Example:

Copy 
1
2
3
4
5
6

{
    "objectID": "2",
    "type": "onewaysynonym",
    "input": "iphone",
    "synonyms": ["ephone", "aphone", "yphone", "apple phone"]
}

altcorrection1, altcorrection2 Alternative corrections. Same as a one-way synonym, except that when matched, they will count as 1 (respectively 2) typos in the ranking formula. The body must contain the following fields:

  • word (string): Word or phrase to appear in query strings.
  • corrections (array of strings): Words to be matched in records. Phrases (multiple-word synonyms) are not supported.

Example:

Copy 
1
2
3
4
5
6

{
    "objectID": "3",
    "type": "altcorrection1",
    "word": "iphone",
    "corrections": ["ephone", "aphone", "yphone"]
}

placeholder Placeholder: A placeholder is a special text token that is placed inside records and can match many inputs. The body must contain the following fields:

  • placeholder (string): Token to be put inside records.
  • replacements (array of strings): List of query words that will match the token.
Copy 
1
2
3
4
5
6

{
    "objectID": "4",
    "type": "placeholder",
    "placeholder": "<number>",
    "replacements": ["0", "1", "2"]
}

For more information, see Adding synonyms.

Parameters:

Parameter Description
forwardToReplicas
type: boolean
default: false
Optional

(URL parameter) Indicates whether to send the new or updated synonyms to all replica indices.

Example:

A

Copy 
1
2
3
4
5

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "synonymID": "1", "type": "synonym", "synonyms": [ "iphone", "ephone", "aphone", "yphone", "apple phone"] }' \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/{indexName}/synonyms/{objectID}"

Save synonyms

A

Path: /1/indexes/{indexName}/synonyms/batch
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:

Create or update multiple synonym objects at once, potentially replacing the entire list of synonyms (if replaceExistingSynonyms is true).

Always use replaceExistingSynonyms to replace all your synonyms on a production index.

The POST body must be a JSON array of synonym objects. The syntax of each object is the same as in save synonym.

Example:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

[
  {
    "objectID": "synonymID1",
    "type": "synonym",
    "synonyms": [ "iphone", "ephone", "aphone", "yphone", "apple phone"]
  },
  {
    "objectID": "synonymID2",
    "type": "onewaysynonym",
    "input": "iphone",
    "synonyms": [ "ephone", "aphone", "yphone", "apple phone"]
  }
]

Parameters:

Parameter Description
forwardToReplicas
type: boolean
default: `false`
Optional

(URL parameter) Replicate the new/updated synonyms to all replica indices.
replaceExistingSynonyms
type: boolean
default: `false`
Optional

(URL parameter) Replace all synonyms of the index with the ones sent with this request.

Get synonym

A

Path: /1/indexes/{indexName}/synonyms/{objectID}
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

Fetch the synonym object identified by its objectID.

Clear all synonyms

A

Path: /1/indexes/{indexName}/synonyms/clear
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:

Delete all synonyms from the index.

This is a convenience method to delete all synonyms at once. It should not be used on a production index before pushing a new list of synonyms, as there would be a short period of time during which your index would have no synonyms at all. In order to replace atomically all synonyms of an index, use the batch method with the replaceExistingSynonyms parameter set to true.

Parameters:

Parameter Description
forwardToReplicas
type: boolean
default: false
Optional

(URL parameter) Clear synonyms on the replica indices as well.

Example:

A

Copy 
1
2
3
4

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/{indexName}/synonyms/clear"

Delete synonym

A

Path: /1/indexes/{indexName}/synonyms/{objectID}
HTTP Verb: DELETE
Required API Key: any key with the editSettings ACL

Description:

Delete a single synonyms set, identified by the given objectID

Parameters:

Parameter Description
forwardToReplicas
type: boolean
default: false
Optional

(URL parameter) delete the synonyms set in all replica indices as well

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/{indexName}/synonyms/{objectID}"

Search synonyms

A

Path: /1/indexes/{indexName}/synonyms/search
HTTP Verb: POST
Required API Key: any key with the settings ACL

Description:

Search or browse all synonyms, optionally filtering them by type.

Parameters:

Parameter Description
query
type: string
default: ""
Optional

Search for specific synonyms matching this string.

Use an empty string (default) to browse all synonyms.
type
type: string
default: ""
Optional

Only search for specific types of synonyms.

Multiple types can be specified using a comma-separated list. Possible values are: synonym, onewaysynonym, altcorrection1, altcorrection2, placeholder.
page
type: integer
default: 0
Optional

Number of the page to retrieve (zero-based).
hitsPerPage
type: integer
default: 100
Optional

Maximum number of synonym objects to retrieve.

Keys endpoints

Quick reference

Verb Path Method

POST

/1/keys

Add API key

PUT

/1/keys/{key}

Update API key

GET

/1/keys

List API keys

GET

/1/keys/{key}

Get API key permissions

DELETE

/1/keys/{key}

Delete API key

POST

/1/keys/{key}/restore

Restore API key

POST

/1/indexes/{indexName}/keys

Add index API key

PUT

/1/indexes/{indexName}/keys/{key}

Update index API key

GET

/1/indexes/{indexName}/keys

List index API keys (for one index)

GET

/1/indexes/*/keys

List index API keys (for all indices)

GET

/1/indexes/{indexName}/keys/{key}

Get index API key

DELETE

/1/indexes/{indexName}/keys/{key}

Delete index API key

Add API key

A

Path: /1/keys
HTTP Verb: POST
Required API Key: Admin

Description:

Create a new API key.

The request must be authenticated by the admin API key.

Parameters:

Parameter Description
acl
type: list
default: [] (no rights)
Optional

List of rights for the newly created key.

The following rights can be used:

  • search: allows to search the index
  • browse: allows to retrieve all index content via the browse API
  • addObject: allows to add/update an object in the index (copy/move index are also allowed with this right)
  • deleteObject: allows to delete objects from the index
  • deleteIndex: allows to delete or clear index content
  • settings: allows to get index settings
  • editSettings: allows to change index settings
  • analytics: allows to retrieve the analytics through the Analytics API
  • recommendation: Allows usage of the Personalization dashboard and the Recommendation API.
  • listIndexes: allows to list all accessible indices
  • logs: allows to get the logs
  • seeUnretrievableAttributes: disable unretrievableAttributes feature for all operations returning records
description
type: string
default: ""
Optional

A comment used to identify a key more easily in the dashboard. It is not interpreted by the API.
indexes
type: list
default: [] (all indices allowed)
Optional

Restrict this new API key to a list of indices or index patterns. If the list is empty, all indices are allowed.

You may specify either an exact index name, or a pattern with leading, trailing, or both wildcards (*). For example:

  • dev_* matches all indices starting with dev_
  • *_dev matches all indices ending with _dev
  • *_products_* matches all indices containing _products_

This option is useful if you want to isolate your development and production environments: you can have one API key targeting development indices and another one targeting production indices.
maxHitsPerQuery
type: integer
default: 0 (unlimited)
Optional

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

This must be a positive integer.

This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
maxQueriesPerIPPerHour
type: integer
default: 0 (no rate limit)
Optional

Maximum number of API calls per hour allowed from a given IP address or a user token. Each time an API call is performed with this key, a check is performed. If the IP—or the user-token if it’s set—at the origin of the call did more than the specified number of calls within the last hour, the API returns a 429 (Too Many Requests) status code.

This must be a positive integer.

This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.

If you are proxying the query through your servers, you must use the admin API key and set the X-Forwarded-For HTTP header with the client IP and the X-Forwarded-API-Key with the API key having rate limits.
queryParameters
type: URL-encoded query string
default: "" (no search parameters)
Optional

Force some query parameters to be applied for each query made with this API key. You can force all query parameters like: typoTolerance=strict&ignorePlurals=false&filters=rights:public.
referers
type: list
default: [] (all referers allowed)
Optional

Restrict this new API key to specific referers. If empty or blank, defaults to all referers. You can specify a pattern with either a leading or trailing wildcard (*), or both.

For example, https://algolia.com/* matches all referers starting with https://algolia.com/ and *.algolia.com matches all referers ending with .algolia.com. You can combine both, as in *algolia.com* to allow the domain algolia.com.
validity
type: integer
default: 0 (no validity limit)
Optional

Validity limit for this key in seconds. The key will automatically be removed after this period of time.

This must be a positive integer.

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "acl": ["search"], "validity":100 }' \
    "https://${APPLICATION_ID}.algolia.net/1/keys"

When the query is successful, the HTTP response is a 200 OK and returns the new API key:

Copy 
1
2
3
4

{
    "key": "107da8d0afc2d225ff9a7548caaf599f",
    "createdAt":"2013-01-18T15:33:13.556Z"
}

Update API key

A

Path: /1/keys/{key}
HTTP Verb: PUT
Required API Key: Admin

Description:

Replace every permission of an existing API key.

The request must be authenticated by the admin API key.

Parameters

This method accepts the same parameters as the add an API key method.

Any unspecified parameter resets that permission to its default value.

Errors:

  • 400: Invalid JSON

Example:

A

Copy 
1
2
3
4
5

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "acl": ["search"], "validity":100 }' \
    "https://${APPLICATION_ID}.algolia.net/1/keys/107da8d0afc2d225ff9a7548caaf599f"

When the query is successful, the HTTP response is a 200 OK and returns the key:

Copy 
1
2
3
4

{
    "key": "107da8d0afc2d225ff9a7548caaf599f",
    "updatedAt":"2013-01-18T15:33:13.556Z"
}

List API keys

A

Path: /1/keys
HTTP Verb: GET
Required API Key: Admin

Description:

List API keys, along with their associated permissions.

The request must be authenticated by the admin API key.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/keys"

When the query is successful, the HTTP response is a 200 OK and returns the list of keys:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
    "keys": [
        {
          "value": "ff96f7ec62b983bd87c4896a8e0b3508",
          "createdAt":1485285254,
          "acl": ["search", "addObject"],
          "validity": 0,
          "description": "My key description"
        },
        {
          "value": "107da8d0afc2d225ff9a7548caaf599f",
          "createdAt":1485209003,
          "indexes": ["indexName1", "indexName2"]
          "acl": ["search"],
          "validity": 0
        }
    ]
}

Get API key permissions

A

Path: /1/keys/{key}
HTTP Verb: GET
Required API Key: Any

Description:

Get the permissions of an API key. When authenticating using the admin API key, you can request information for any of your application’s API keys. When using a non-admin API key, you can only retrieve information for this specific API key.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/keys/107da8d0afc2d225ff9a7548caaf599f"

When the query is successful, the HTTP response is a 200 OK and returns the rights of the key:

Copy 
1
2
3
4
5

{
  "value": "107da8d0afc2d225ff9a7548caaf599f",
  "acl": ["search"],
  "validity": 0
}

Delete API key

A

Path: /1/keys/{key}
HTTP Verb: DELETE
Required API Key: Admin

Description:

Delete an API key.

The request must be authenticated by the admin API key.

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/keys/${API_KEY}"

When the query is successful, the HTTP response is a 200 OK and returns the date of deletion:

Copy 
1
2
3

{
    "deletedAt":"2013-01-18T15:33:13.556Z"
}

Restore API key

A

Path: /1/keys/{key}/restore
HTTP Verb: POST
Required API Key: Admin

Description:

Restore a deleted API key, along with its associated rights.

The request must be authenticated by the admin API key.

Errors:

  • 403: Invalid credentials
  • 404: The API key isn’t in the list of deleted API keys
  • 500: Builder not available

Example:

A

Copy 
1
2
3
4

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/keys/myAPIKey/restore"

When the query is successful, the HTTP response is a 200 OK and returns the creation timestamp:

Copy 
1
2
3
4

{
  "key": "1eb37de6308abdccf9b760ddacb418b4",
  "createdAt": "2017-12-16T22:21:31.871Z"
}

Add index API key

A

Path: /1/indexes/{indexName}/keys
HTTP Verb: POST

Description:

Add a new API key that can access only this index.

The request must be authenticated by the admin API key.

API keys may take some time to be propagated. You can check whether the key is already available via Retrieve an index-specific API key.

Parameters:

Parameter Description
acl
type: list
default: [] (no rights)
Optional

List of rights for the newly created key.

The following rights can be used:

  • search: allows to search the index
  • browse: allows to retrieve all index content via the browse API
  • addObject: allows to add/update an object in the index (copy/move index are also allowed with this right)
  • deleteObject: allows to delete objects from the index
  • deleteIndex: allows to delete or clear index content
  • settings: allows to get index settings
  • editSettings: allows to change index settings
  • analytics: allows to retrieve the analytics through the Analytics API
  • listIndexes: allows to list all accessible indices
  • logs: allows to get the logs
  • seeUnretrievableAttributes: disable unretrievableAttributes feature for all operation returning records
description
type: string
default: ""
Optional

A comment used to identify a key more easily in the dashboard. It is not interpreted by the API.
maxHitsPerQuery
type: integer
default: 0 (unlimited)
Optional

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

This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
maxQueriesPerIPPerHour
type: integer
default: 0 (no rate limit)
Optional

Maximum number of API calls per hour allowed from a given IP address or a user token. Each time an API call is performed with this key, a check is performed. If the IP—or the user-token if it’s set—at the origin of the call did more than the specified number of calls within the last hour, the API returns a 429 (Too Many Requests) status code.

This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.

If you are proxying the query through your servers, you must use the admin API key and set the X-Forwarded-For HTTP header with the client IP and the X-Forwarded-API-Key with the API key having rate limits.
queryParameters
type: URL-encoded query string
default: "" (no search parameters)
Optional

Force some query parameters to be applied for each query made with this API key. You can force all query parameters like: typoTolerance=strict&ignorePlurals=false&filters=rights:public.
referers
type: list
default: [] (all referers allowed)
Optional

Restrict this new API key to specific referers. If empty or blank, defaults to all referers. You can specify a pattern with either a leading or trailing wildcard (*), or both.

For example, https://algolia.com/* matches all referers starting with https://algolia.com/ and *.algolia.com matches all referers ending with .algolia.com. You can combine both, as in *algolia.com* to allow the domain algolia.com.
validity
type: integer
default: 0 (no validity limit)
Optional

Validity limit for this key in seconds. The key will automatically be removed after this period of time.

Errors:

  • 400: Invalid JSON

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "acl": ["search"], "validity":100 }' \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/keys"

Upon success, the response is 200 OK and contains the new API key:

Copy 
1
2
3
4

{
  "key": "107da8d0afc2d225ff9a7548caaf599f",
  "createdAt":"2013-01-18T15:33:13.556Z"
}

Update index API key

A

Path: /1/indexes/{indexName}/keys/{key}
HTTP Verb: PUT
Required API Key: Admin

Description:

Update rights associated to an API key specific to this index.

The request must be authenticated by the admin API key.

This endpoint will always succeed and return the passed in API key with an up to date updatedAt value regardless of whether the API key exists or not. If you want to check if an API key exists before updating it, please use the Get API Key permissions endpoint.

API keys may take some time to be propagated. You can check whether the key has already been updated via Retrieve an index-specific API key.

Parameters

The parameters are the same as in Add an index-specific API key.

Errors:

  • 400: Invalid JSON

Example:

A

Copy 
1
2
3
4
5

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "acl": ["search"], "validity":100 }' \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/keys/107da8d0afc2d225ff9a7548caaf599f"

Upon success, the response is 200 OK and contains the API Key:

Copy 
1
2
3
4

{
    "key": "107da8d0afc2d225ff9a7548caaf599f",
    "updatedAt":"2013-01-18T15:33:13.556Z"
}

List index API keys (for one index)

A

Path: /1/indexes/{indexName}/keys
HTTP Verb: GET
Required API Key: Admin

Description:

List API keys that have access to this index, along with their associated rights. The keys must be specific to this index.

The request must be authenticated by the admin API key.

Errors:

  • 404: Index does not exist

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/keys"

Upon success, the response is 200 OK and returns the list of keys:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
    "keys": [
        {
          "value": "ff96f7ec62b983bd87c4896a8e0b3508",
          "createdAt":1485285254,
          "acl": ["search", "addObject"],
          "validity": 0,
          "description": "My key description"
        },
        {
          "value": "107da8d0afc2d225ff9a7548caaf599f",
          "createdAt":1485209003,
          "acl": ["search"],
          "validity": 0
        }
    ]
}

List index API keys (for all indices)

A

Path: /1/indexes/*/keys
HTTP Verb: GET
Required API Key: Admin

Description:

List all index-specific API keys across all indices, along with their associated rights.

The request must be authenticated by the admin API key.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/*/keys"

Upon success, the response is 200 OK and returns the list of keys:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
    "keys": [
        {
          "value": "ff96f7ec62b983bd87c4896a8e0b3508",
          "createdAt":1485285254,
          "acl": ["search", "addObject"],
          "validity": 0,
          "index": "contacts",
          "description": "My key description"
        },
        {
          "value": "107da8d0afc2d225ff9a7548caaf599f",
          "createdAt":1485209003,
          "acl": ["search"],
          "validity": 0,
          "index": "contacts"
        }
    ]
}

Get index API key

A

Path: /1/indexes/{indexName}/keys/{key}
HTTP Verb: GET
Required API Key: Admin

Description:

Retrieve the details of an index-specific API key.

The request must be authenticated by the admin API key.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/keys/107da8d0afc2d225ff9a7548caaf599f"

Upon success, the response is 200 OK and contains the details of the key:

Copy 
1
2
3
4
5
6

{
  "value": "107da8d0afc2d225ff9a7548caaf599f",
  "acl": ["search"],
  "validity": 0,
  "description": "Test key"
}

Delete index API key

A

Path: /1/indexes/{indexName}/keys/{key}
HTTP Verb: DELETE
Required API Key: Admin

Description:

Delete an index-specific API key.

The request must be authenticated by the admin API key.

API keys may take some time to be propagated. You can check whether the key has already been deleted via Retrieve an index-specific API key.

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/keys/107da8d0afc2d225ff9a7548caaf599f"

Upon success, the response is a 200 OK and contains the date of deletion.

Copy 
1
2
3

{
    "deletedAt":"2013-01-18T15:33:13.556Z"
}

Rules endpoints

Quick reference

Verb Path Method

PUT

/1/indexes/{indexName}/rules/{objectID}

Save rule

POST

/1/indexes/{indexName}/rules/batch

Batch Rules

GET

/1/indexes/{indexName}/rules/{objectID}

Get Rule

DELETE

/1/indexes/{indexName}/rules/{objectID}

Delete Rule

POST

/1/indexes/{indexName}/rules/clear

Clear Rules

POST

/1/indexes/{indexName}/rules/search

Search rules

Save rule

A

Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL

Description:

Create or update a rule with the specified rule objectID.

objectID isn’t a reference to an Algolia record: it’s the unique identifier for a rule object.

Parameters:

Parameter Description
indexName
type: string
Required

Index name
objectID
type: string
Required

Unique identifier of the rule to add or update
forwardToReplicas
type: boolean
default: false
Optional

When true, the change is forwarded to all replicas of this index. When false, replicas aren’t affected.

Example:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}" \
     --data-binary '{
        "objectID": "a-rule-id",
        "conditions": [{
          "pattern": "apple",
          "anchoring": "contains"
        }],
        "consequence": {
          "params": {
            "filters": "brand:apple"
          }
        }
     }'

Upon success, the response is 200 OK, with the objectID attribute containing the added Rule’s objectID.

Copy 
1
2
3
4
5

  {
    "updatedAt": "2021-06-04T08:13:32.446Z",
    "taskID": 247425353002,
    "objectID": "rules"
  }

Batch Rules

A

Path: /1/indexes/{indexName}/rules/batch
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:

Create or update a batch of Rules.

Each Rule is created or updated, depending on whether a Rule with the same objectID already exists. You may also specify true for clearExistingRules, in which case the batch will atomically replace all the existing Rules.

Parameters:

Parameter Description
indexName
type: string
Required

Index name
forwardToReplicas
type: boolean
default: false
Optional

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.
clearExistingRules
type: boolean
default: false
Optional

When true, existing Rules are cleared before adding this batch. When false, existing Rules are kept.

Example:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/test_rest/rules/batch" \
    --data-binary '[
        {
         "objectID": "a-rule-id",
         "conditions": [{
           "pattern": "smartphone",
           "anchoring": "contains"
         }],
         "consequence": {
           "params": {
             "filters": "category:smartphone"
           }
         }
       },
       {
          "objectID": "a-second-rule-id",
          "conditions": [{
            "pattern": "apple",
            "anchoring": "contains"
          }],
          "consequence": {
            "params": {
              "filters": "brand:apple"
            }
          }
       }
    ]'

Upon success, the response is 200 OK.

Copy 
1
2
3
4

{
  "taskID": 247427180002,
  "updatedAt": "2021-06-04T08:24:55.069Z"
}

Get Rule

A

Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

Get the rule with the specified Rule objectID.

objectID isn’t a reference to an Algolia record: it’s the unique identifier for a Rules object.

Parameters:

Parameter Description
indexName
type: string
Required

Index name
objectID
type: string
Required

objectID of the Rule to retrieve

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}"

Upon success, the response is 200 OK.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

  "objectID": "ruleID",
  "conditions": [
    {
      "pattern": "smartphone",
      "anchoring": "contains"
    }
  ],
  "consequence": {
    "params": {
      "filters": "category:smartphone"
    }
  }
}

Delete Rule

A

Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: DELETE
Required API Key: any key with the editSettings ACL

Description:

Delete the rule with the specified Rule objectID.

objectID isn’t a reference to an Algolia record: it’s the unique identifier for a Rules object.

Parameters:

Parameter Description
indexName
type: string
Required

Index name
objectID
type: string
Required

Unique identifier of the rule to delete
forwardToReplicas
type: boolean
default: false
Optional

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}"

Upon success, the response is 200 OK.

Copy 
1
2
3
4

{
  "taskID": 249200944000,
  "updatedAt": "2021-06-04T08:35:58.984Z"
}

Clear Rules

A

Path: /1/indexes/{indexName}/rules/clear
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:

Delete all Rules in the index.

Parameters:

Parameter Description
indexName
type: string
Required

Index name
forwardToReplicas
type: boolean
default: false
Optional

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example:

A

Copy 
1
2
3
4

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/clear"

Upon success, the response is 200 OK.

Copy 
1
2
3
4

{
  "taskID": 249202274000,
  "updatedAt": "2021-06-04T08:44:07.888Z"
}

Search rules

A

Path: /1/indexes/{indexName}/rules/search
HTTP Verb: POST
Required API Key: any key with the settings ACL

Description:

Search for rules.

Parameters:

Parameter Description
indexName
type: string
Required

Index name

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/search" \
    --data-binary '{"query": "something"}'

Upon success, the response is 200 OK.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{
  "hits": [
    {
      "conditions": [
        {
          "pattern": "apple",
          "anchoring": "contains"
        }
      ],
      "consequence": {
        "params": {
          "filters": "brand:apple"
        }
      },
      "objectID": "a-second-rule-id",
      "_highlightResult": {
        "conditions": [
          {
            "pattern": {
              "value": "apple",
              "matchLevel": "none",
              "matchedWords": []
            }
          }
        ],
        "consequence": {
          "params": {
            "filters": {
              "value": "brand:apple",
              "matchLevel": "none",
              "matchedWords": []
            }
          }
        }
      }
    }
  ],
  "nbHits": 1,
  "page": 0,
  "nbPages": 1
}

Dictionaries endpoints

The Dictionary API enables users to customize linguistic resources provided by Algolia such as stop words, plurals, and segmentation.

The {dictionaryName} placeholder can have the following values:

  • stopwords
  • plurals
  • compounds (for decompounding and segmentation)

Quick reference

Verb Path Method

POST

/1/dictionaries/{dictionaryName}/batch

Add or delete entries in batches

GET

/1/dictionaries/{dictionaryName}/search

Search dictionary entries (GET)

POST

/1/dictionaries/{dictionaryName}/search

Search dictionary entries (POST)

PUT

/1/dictionaries/*/settings

Set dictionary settings

GET

/1/dictionaries/*/settings

Get dictionary settings

GET

/1/dictionaries/*/languages

Get available languages

Add or delete entries in batches

A

Path: /1/dictionaries/{dictionaryName}/batch
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:

Add or delete one or more dictionary entries.

Parameters:

Parameter Description
requests
type: list of request
Required

List of requests.

Each request is described by:

  • action: type of operation
  • body: arguments for the operation
clearExistingDictionaryEntries
type: bool
default: false
Optional

When true, start the batch by removing all the custom entries from the dictionary.

requests ➔ request

Parameter Description
action
type: string
Required

Actions to perform. It can be one of the following values:

  • addEntry: add entries to the dictionary.
  • deleteEntry: delete entries from the dictionary.
body
type: delete object | stopword entry | plural entry | compound entry
Required

A JSON object with the required information for the selected action. The request body depends on the action and dictionary entry type (stop word, plural, or compound).

deleteEntry ➔ delete object

Parameter Description
objectID
type: string
Required

Unique identifier of the entry to delete.

addEntry ➔ stopword entry

Parameter Description
objectID
type: string
Required

Unique identifier of the entry to add or replace in the stop words dictionary.

The addEntry action replaces any existing entry with the same objectID.
language
type: string
Required

Language ISO code supported by the dictionary (for example, “en” for English).
word
type: string
Required

The stop word to add or replace. If word already exists in the standard dictionary provided by Algolia, it’s replaced by the word you provide.
state
type: string
default: enabled
Optional

The state of the entry:

  • enabled: the current stop word is active.
  • disabled: the current stop word is inactive.

addEntry ➔ plural entry

Parameter Description
objectID
type: string
Required

Unique identifier of the entry to add or replace in the plurals dictionary.

The addEntry action replaces any existing entry with the same objectID.
language
type: string
Required

Language ISO code supported by the dictionary (for example, “en” for English).
words
type: string
Required

List of word declensions. If any of the words already exist in the standard dictionary provideed by Algolia, They’re replaced by the words you provide.

addEntry ➔ compound entry

Parameter Description
objectID
type: string
Required

Unique identifier of the entry to add or replace in the compounds dictionary.

The addEntry action replaces any existing entry with the same objectID.
language
type: string
Required

Language ISO code supported by the dictionary (for example, de for German).
word
type: string
Required

  • If decomposition is empty: adds word as a compound atom.

    For example, the atom “kino” decomposes the query “kopfkino” into “kopf” and “kino”.

  • If decomposition isn’t empty: creates a decomposition exception.

    For example, if word is hundehütte and decomposition is set to ["hund", "hütte"], “hundehütte” is decomposed into “hund” and “hütte”, discarding the linking morpheme “e”.
decomposition
type: string[]
Required
  • If decomposition is empty, word is considered as a compound atom.
  • Otherwise, decomposition contains the individual parts of word.

Errors:

  • 400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.
  • 413: Payload too large. The payload exceeds the 10 MB limit.
  • 403: Custom dictionary entries quota exceeded.

Example:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/dictionaries/stopwords/batch" \
    --data-binary '
    {
      "clearExistingDictionaryEntries": true,
      "requests": [
        {
          "action": "addEntry",
          "body": {
            "objectID": "und",
            "language": "de",
            "word": "und"
          }
        },
        {
          "action": "addEntry",
          "body": {
            "objectID": "under",
            "language": "en",
            "word": "under"
          }
        }
      ]
    }'

Search dictionary entries (GET)

A

Path: /1/dictionaries/{dictionaryName}/search
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

Search the dictionary entries.

Parameters:

Parameter Description
query
type: string
Required

Term to search in the dictionary.
page
type: integer
default: 0
Optional

Page to fetch.
hitsPerPage
type: integer
default: 20
Optional

Number of hits retrieved per page. Accepted range: [1, 1000].
language
type: string
Optional

Language ISO code supported by the dictionary (for example, “en” for English).

Errors:

  • 400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.

Example:

A

Copy 
1
2
3

curl -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     "https://${APPLICATION_ID}.algolia.net/1/dictionaries/stopwords/search?query=und"

Search dictionary entries (POST)

A

Path: /1/dictionaries/{dictionaryName}/search
HTTP Verb: POST
Required API Key: any key with the settings ACL

Description:

Search the dictionary entries.

Parameters:

Parameter Description
query
type: string
Required

Term to search in the dictionary.
page
type: integer
default: 0
Optional

Page to fetch.
hitsPerPage
type: integer
default: 20
Optional

Number of hits retrieved per page. Accepted range: [1, 1000].
language
type: string
Optional

Language ISO code supported by the dictionary (for example, “en” for English).

Errors:

  • 400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.

Example:

A

Copy 
1
2
3
4
5

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/dictionaries/stopwords/search" \
    --data-binary '{ "query": "und" }'

Set dictionary settings

A

Path: /1/dictionaries/*/settings
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL

Description:

Turn on or off standard stop words for a given language.

Parameters:

Parameter Description
stopwords
type: object
Required

Settings for the stop words dictionary.

stopwords ➔ settings

Parameter Description
disableStandardEntries
type: object
Optional

Mapping of language ISO code supported by the dictionary (for example, “en” for English) and a boolean value. If the value for a language is true, the standard stop words dictionary entries for that language are inactive.

To turn on the standard stop words dictionary entries, set the language to false.

Errors:

  • 400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.

Example:

A

Turn off the standard stopwords dictionary for Russian. Turn on the standard stopwords dictionary for French.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/dictionaries/*/settings" \
    --data-binary '
    {
      "disableStandardEntries": {
        "stopwords": {
          "ru": true,
          "fr": false
        }
      }
    }'

The settings for other languages remain unchanged.

To reset stop words settings to default values, set stopwords to null.

Copy 
1
2
3
4
5

{
  "disableStandardEntries": {
    "stopwords": null
  }
}

Get dictionary settings

A

Path: /1/dictionaries/*/settings
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

Get the languages for which standard dictionary entries are turned off.

Example:

A

Copy 
1
2
3
4
5
6
7

{
  "disableStandardEntries": {
    "stopwords": {
      "ru": "true"
    }
  }
}

Get available languages

A

Path: /1/dictionaries/*/languages
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:

List dictionaries supported per language.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/dictionaries/*/languages"

The response lists all languages as ISO codes and their available dictionaries.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "de": {
    "plurals": {
      "nbCustomEntries": 2
    },
    "stopwords": {
      "nbCustomEntries": 4
    },
    "compounds": {
      "nbCustomEntries": 1
    }
  },
  "en": {
    "plurals": {
      "nbCustomEntries": 0
    },
    "stopwords": {
      "nbCustomEntries": 0
    },
    "compounds": null
  }
}
  • German (de) supports plurals, stopwords, and compounds dictionaries
  • English (en) supports the plurals and stopwords dictionaries.
  • All unsupported dictionary types have the value null.
  • The API returns the number of custom entries in nbCustomEntries. If nbCustomEntries is 0, the dictionary only contains standard entries provided by Algolia.

MultiClusters endpoints

Limitation v0.1

For v0.1, the assignment of users to clusters won’t be automatic: if a user isn’t properly assigned, or not found, the call will be rejected.

How to get the feature

MCM needs to be enabled on your cluster. Contact the Algolia support team for more information.

Quick reference

Verb Path Method

POST

/1/clusters/mapping

Assign or Move userID

POST

/1/clusters/mapping/batch

Batch assign userIDs

GET

/1/clusters/mapping/top

Get top userID

GET

/1/clusters/mapping/${userID}

Get userID

GET

/1/clusters

List clusters

GET

/1/clusters/mapping

List userIDs

DELETE

/1/clusters/mapping/${userID}

Remove userID

POST

/1/clusters/mapping/search

Search userID

GET

/1/clusters/mapping/pending

Has pending mappings

Assign or Move userID

A

Path: /1/clusters/mapping
HTTP Verb: POST
Required API Key: Admin

Description:

Assign or Move a userID to a cluster.

The time it takes to migrate (move) a user is proportional to the amount of data linked to the userID.

Example:

A

Copy 
$
$
$
$
$
$
$

curl -X POST \
     -H "X-Algolia-User-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"cluster\": \"c1-test\"}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, and the userID is directly usable.

Copy 
1
2
3

{
  "createdAt":"2013-01-18T15:33:13.556Z"
}

Batch assign userIDs

A

Path: /1/clusters/mapping/batch
HTTP Verb: POST
Required API Key: Admin

Description:

Assign multiple userIDs to a cluster.

Example:

A

Copy 
$
$
$
$
$
$
$
$

curl -X POST \
     -H "X-Algolia-User-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"cluster\": \"c1-test\",
     \"users\":[\"einstein\", \"bohr\", \"feynman\"]}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/batch"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, and the userIDs are directly usable.

Copy 
1
2
3

{
  "createdAt":"2013-01-18T15:33:13.556Z"
}

Get top userID

A

Path: /1/clusters/mapping/top
HTTP Verb: GET
Required API Key: Admin

Description:

Get the top 10 userIDs with the highest number of records per cluster.

The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds to propagate to the different clusters.

Example:

A

Copy 
$
$
$
$

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/top"

Upon success, the response is 200 OK and contains the following array of userIDs and clusters

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "topUsers":[{
    "c1-test-1": [
      {
        "userID": "user1",
        "clusterName": "",
        "nbRecords": 42,
        "dataSize": 0
      }
    ],
    ...
  },
  …
  ]
}

Get userID

A

Path: /1/clusters/mapping/${userID}
HTTP Verb: GET
Required API Key: Admin

Description:

Returns the userID data stored in the mapping.

The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds to propagate to the different clusters.

Example:

A

Copy 
$
$
$
$

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/${USERID}"

Upon success, the response is 200 OK and contains the following userID data

Copy 
1
2
3
4
5
6

{
  "userID": "user1",
  "clusterName": "c1-test",
  "nbRecords": 42,
  "dataSize":0
}

List clusters

A

Path: /1/clusters
HTTP Verb: GET
Required API Key: Admin

Description:

List the clusters available in a multi-clusters setup for a single appID

Example:

A

Copy 
$
$
$
$

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters"

Upon success, the response is 200 OK and contains the following clusters

Copy 
1
2
3
4
5
6
7
8
9
10

{
  "clusters": [{
    "clusterName": "c1-test",
    "nbRecords": 42,
    "nbUserIDs": 0,
    "dataSize": 0
  },
  …
  ]
}

List userIDs

A

Path: /1/clusters/mapping
HTTP Verb: GET
Required API Key: Admin

Description:

List the userIDs assigned to a multi-clusters appID.

The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds to propagate to the different clusters.

Parameters:

Parameter Description
page
type: URL-encoded string
default: 0 (start from the beginning)
Optional

Page to retrieve, the userID per page is by default at 1000 userIDs

Example:

A

Copy 
$
$
$
$
$
$

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"page\": 0, \"hitsPerPage\": 20}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK and contains the following userIDs data

Copy 
1
2
3
4
5
6
7
8
9
10

{
  "userIDs":[{
    "userID": "user1",
    "clusterName":"c1-test",
    "nbRecords":42,
    "dataSize":0
  },
  …
  ]
}

Remove userID

A

Path: /1/clusters/mapping/${userID}
HTTP Verb: DELETE
Required API Key: Admin

Description:

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

Example:

A

Copy 
$
$
$
$
$

curl -X DELETE \
     -H "X-Algolia-USER-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK and a task is created to remove the userID data and mapping

Copy 
1
2
3

{
  "deletedAt": "$TIMESTAMP"
}

Search userID

A

Path: /1/clusters/mapping/search
HTTP Verb: POST
Required API Key: Admin

Description:

Search for userIDs.

The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds propagate to the different clusters.

To keep updates moving quickly, the index of userIDs isn’t built synchronously with the mapping. Instead, the index is built once every 12h, at the same time as the update of userID usage. For example, when you perform a modification like adding or moving a userID, the search will report an outdated value until the next rebuild of the mapping, which takes place every 12h.

Example:

A

Copy 
$
$
$
$
$
$

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"query\": \"user1\", \"cluster\":\"c1-test\", \"page\": 1, \"hitsPerPage\": 4}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/search"

Upon success, the response is 200 OK and contains the following userIDs data.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
"hits": [
  {
    "userID": "user9",
    "clusterName": "c11-test",
    "nbRecords": 3,
    "dataSize": 481,
    "objectID": "user9",
    "_highlightResult": {
      "userID": {
        "value": "<b>user<\/b>9",
        "matchLevel": "full",
        "fullyHighlighted": false,
        "matchedWords": [
          "user"
        ]
      },
      "clusterName": {
        "value": "c11-test",
        "matchLevel": "none",
        "matchedWords": []
      }
    }
  },
  [...]
],
"nbHits": 10,
"page": 0,
"hitsPerPage": 20,
"updatedAt": 1514902377
}

Has pending mappings

A

Path: /1/clusters/mapping/pending
HTTP Verb: GET
Required API Key: Admin

Description:

Get the status of your clusters’ migrations or user creations.

Creating a large batch of users or migrating your multi-cluster may take quite some time. This method lets you retrieve the status of the migration, so you can know when it’s done.

Example:

A

Copy 
$
$
$
$
$
$

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"getClusters\": true}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/pending"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, and the userIDs are directly usable.

Copy 
1
2
3

{
  "createdAt":"2013-01-18T15:33:13.556Z"
}

Vault endpoints

Algolia Vault allows you to restrict the access to your cluster to a specific set of sources. This restriction is applied at the network level and for non-authorized sources the cluster becomes invisible.

Make sure you authorize the IP addresses of your team members of offices that need to access the dashboard, as it’s also affected by the restricted list you setup.

By default, the firewall restriction is turned off and all sources are allowed to reach the server but they still need to provide a valid application ID and API key to access the data stored on the cluster. The first call to setup the firewall allowlist turns the restriction on. Adding the source 0.0.0.0/0 allows all sources.

To allow the Algolia Support team to access the API, add the special source ALGOLIA_SUPPORT.

The number of sources allowed is limited to 1000 sources.

How to get the feature

Vault needs to be enabled on your cluster. Contact the Algolia support team for more information.

Quick reference

Verb Path Method

GET

/1/security/sources

List allowed sources

PUT

/1/security/sources

Replace the list of allowed sources

POST

/1/security/sources/append

Add a source to the allowed sources

DELETE

/1/security/sources/{source}

Delete one allowed source

List allowed sources

A

Path: /1/security/sources
HTTP Verb: GET

Description:

This command lists all your allowed sources.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${ADMIN_API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     "https://${APPLICATION_ID}-dsn.algolia.net/1/security/sources"

When the query is successful, the HTTP response is a 200 OK and returns a list of sources with associated descriptions.

Copy 
1
2
3
4
5
6
7
8
9

[
  {
    "source": "10.0.0.1/32"
  },
  {
    "source": "192.168.0.0/16",
    "description": "Server subnet"
  }
]

Replace the list of allowed sources

A

Path: /1/security/sources
HTTP Verb: PUT

Description:

This command replaces the list of allowed sources.

Example:

A

Copy 
1
2
3
4
5
6
7
8

curl -X PUT \
     -H "X-Algolia-API-Key: ${ADMIN_API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '[
                        { "source": "10.0.0.1\/32" },
                        { "source": "192.168.0.0\/16", "description": "Server subnet" }
                    ]' \
    "https://${APPLICATION_ID}.algolia.net/1/security/sources"

When the query is successful, the HTTP response is a 200 OK and returns the update date.

Copy 
1
2
3

{
  "updatedAt": "2013-08-17T07:59:28.313Z"
}

Add a source to the allowed sources

A

Path: /1/security/sources/append
HTTP Verb: POST

Description:

This command adds an source to the list of allowed sources.

Example:

A

Copy 
1
2
3
4
5
6
7

curl -X POST \
     -H "X-Algolia-API-Key: ${ADMIN_API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{
                        "source": "10.0.0.1/32", "description": "One ip"
                    }' \
    "https://${APPLICATION_ID}.algolia.net/1/security/sources/append"

When the query is successful, the HTTP response is a 200 OK and returns the creation date.

Copy 
1
2
3

{
  "createdAt": "2013-08-17T07:59:28.313Z"
}

Delete one allowed source

A

Path: /1/security/sources/{source}
HTTP Verb: DELETE

Description:

This command deleted one allowed source.

Parameters:

Parameter Description
source
type: string
Required

Source to delete

Example:

A

Copy 
1
2
3
4

curl -X DELETE \
     -H "X-Algolia-API-Key: ${ADMIN_API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     "https://${APPLICATION_ID}.algolia.net/1/security/source/10.0.0.0%2f16"

When the query is successful, the HTTP response is a 200 OK and returns the deletion date.

Copy 
1
2
3

{
  "deletedAt": "2013-08-17T07:59:28.313Z"
}

Advanced endpoints

Quick reference

Verb Path Method

GET

/1/logs

Get logs

GET

/1/indexes/{indexName}/task/{taskID}

Get a task's status

Get logs

A

Path: /1/logs
HTTP Verb: GET
Required API Key: any key with the logs ACL

Description:

Return the lastest log entries.

This endpoint only returns logs for the targeted cluster. To fetch the logs of your Distributed Search Network (DSN), target the DSN’s endpoint directly.

  • The request must be authenticated by an API key with the logs ACL.
  • This API is counted in your operation quota but is not logged.
  • Older entries are removed regularly. You can’t access logs API request logs after the retention period has expired. The number of stored logs depends on the the retention period (seven days) and the API request limit (1,000 API requests per server).

Parameters:

Query parameters

Parameter Description
offset
type: integer
default: 0
Optional

First entry to retrieve (zero-based). Log entries are sorted by decreasing date, therefore 0 designates the most recent log entry.
length
type: integer
default: 10
Optional

Maximum number of entries to retrieve. Maximum allowed value: 1000.
indexName
type: string
default: null
Optional

Index for which log entries should be retrieved. When omitted, log entries are retrieved across all indices.
type
type: string
default: "all"
Optional

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

This parameter is useful for debugging, especially when it is difficult to locate errors among many API calls:

  • all: retrieve all logs
  • query: retrieve only search queries
  • build: retrieve only build operations
  • error: retrieve only errors

You can retrieve the logs of your last 1,000 API calls. It is designed for real-time, immediate debugging.

Example:

A

The following example requests all logs for build operations (type=build query parameter).

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     "https://${APPLICATION_ID}.algolia.net/1/logs?type=build"

When the query is successful, the HTTP response is a 200 OK and returns the logs:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
    "logs": [
        {
            "timestamp": "2013-09-17 13:10:31",
            "method": "GET",
            "answer_code": "200",
            "query_body": "",
            "answer": "{\n  \"items\": [\n    {\n      \"name\": \"cities\",\n      \"createdAt\": \"2013-09-16T07:39:29.446Z\",\n      \"updatedAt\": \"2013-09-16T07:39:29.446Z\",\n      \"entries\": 149096,\n      \"pendingTask\": false\n      }\n    ]\n  }\n",
            "url": "/1/indexes",
            "ip": "127.0.0.1",
            "query_headers": "User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8x zlib/1.2.5\nHost: localhost.algolia.com:8080\nAccept: */*\nContent-Type: application/json; charset=utf-8\nX-Algolia-API-Key: 20f***************************\nX-Algolia-Application-Id: MyApplicationID\n",
            "sha1": "26c53bd7e38ca71f4741b71994cd94a600b7ac68"
        }
    ]
}

Get a task’s status

A

Path: /1/indexes/{indexName}/task/{taskID}
HTTP Verb: GET
Required API Key: any key with the addObject ACL

Description:

Check the current status of a given task. taskID is a numeric value (up to 64bits).

The response includes two fields:

  • status (string): either published or notPublished, depending on the task’s current status
  • pendingTask (boolean): whether the index has remaining task(s) running

Interpreting the response

  • status’s value is published if the task has been processed, notPublished otherwise.
  • pendingTask is deprecated and shouldn’t be used.

Example:

A

Copy 
1
2
3
4

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/contacts/task/13235"

Upon success, the response is 200 OK and returns the status of the task:

Copy 
1
2
3
4

{
  "status": "published",
  "pendingTask": false
}
Did you find this page helpful?