PHP
API Reference
/
REST API
/
Search REST API
Apr. 06, 2021
Search REST API
The Search API is the core of Algolia. Around it, we’ve built a complete search ecosystem, including eleven API clients, six front-end libraries, platform and framework integrations, a full-featured dashboard, and more.
Using Algolia
This page documents the Algolia Search REST API. However, we strongly recommend using our official API clients, libraries, and integrations to build your search implementation.
We’ve developed API clients, integrations, and libraries for the most common programming languages and platforms. These advanced wrappers handle errors, and enforce the best search practices and optimal use of the Algolia search engine. Everything you can do with the REST API can be done using our clients and libraries. They’re all open source, and the code is available on GitHub.
If you want to learn more about what we offer, check out our introduction to Algolia.
You should only use the Search REST API to develop new API clients: there’s no SLA if you use the REST API directly.
API clients
Front-end libraries
InstantSearch.js
React InstantSearch
Vue InstantSearch
Angular InstantSearch
InstantSearch iOS
InstantSearch Android
Frameworks
Platforms
Hosts
The REST API lets your 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 our
Distributed Search Network (if you subscribed that option).
In order to guarantee a very high availability, we recommend to 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 is hosted on another DNS provider, for better redundancy.) It is best to
shuffle (randomize) the list of fallback hosts at init time in order to ensure load balancing across clients.
All our standard API clients implement this retry strategy.
The Application-ID variable can be found in your dashboard.
The relative path prefix /1/ indicates that we are currently using version 1 of the API.
Format
The entire API uses JSON encoded as UTF-8.
The body of POST and PUT requests must be either a JSON object or a JSON array (depending on the particular endpoint)
and their Content-Type header should be set to application/json; charset=UTF-8.
The body of responses is always a JSON object, and their content type is always application/json; charset=UTF-8.
Parameters
Unless otherwise stated, parameters must be passed:
- in the URL’s query string for GET and DELETE requests;
- in the request’s 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 is 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, of course); example:
attributesToRetrieve=%5B%22title%22,%22description%22%5D.
Arrays passed in the body must always be regular JSON arrays.
Authentication
Basics
Authentication is done via HTTP headers:
X-Algolia-Application-Ididentifies which application you are accessing;X-Algolia-API-Keyauthenticates the endpoint (you can pass any API key created with the API).
For JavaScript usage, Algolia supports Cross-Origin Resource Sharing (CORS), so that you can use these headers in conjunction with XMLHttpRequest.
Secured API keys
You may have a single index containing per-user data. In that case, you may wish to restrict access to the records
of one particular user.
Typically, all your records would be tagged with their associated user_id, and you would add a filter at query time
like filters=user_id:${requested_id} to retrieve only what the querying user has access to.
Adding that filter directly from the frontend (browser or mobile application) will result in a security breach, because the user would be able to modify the filters you’ve set, e.g. by modifying the JavaScript code.
In order to keep sending the query from the browser (which is recommended for optimal latency) but only target secured records, you can generate secured API keys from your backend and use them in your frontend code. The backend will then automatically enforce the security filters contained in the key; the user will not be able to alter them.
A secured API key is used like any other API key via the X-Algolia-API-Key request header.
Generate a secured API key
Secured API keys are generated by hashing (HMAC SHA-256) the following criteria together:
-
a private API key (can be any API Key that is not the admin API Key), used as the secret for HMAC SHA-256;
-
a URL-encoded list of query parameters defining the security filters.
The result of the hashing is concatenated to the URL-encoded query parameters, and this content is encoded in Base64 to generate the final secured API key.
All our backend API clients contain helpers to generate secured API keys. It is highly recommended that you use them instead of generating secured API keys manually.
Restriction parameters
The query parameters used during the generation of a secured API key can contain any of the default query parameters. In addition to these parameters, you can also specify parameters to restrict the indices or the TTL:
| Name | Type | Description |
|---|---|---|
userToken |
string | An identifier used by the rate-limit system to differentiate users using the same IP address. |
validUntil |
number | Expiration date of the API key (as a Unix timestamp). |
restrictIndices |
string (comma-separated list) | 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 ( For example, Note: the parameter is intentionally misspelled, in conformity with the RFC 1945. 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. {:.alert .alert-warning} |
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.
Encryption / Firewall / Whitelisting
Encryption at rest
Vault provides encryption at rest of the data in the servers. There’s nothing to do on the customer side and is enabled by default.
Disabling the firewall
You can disable the firewall (so Vault only provides the encryption at rest in this case), by passing the IP address 0.0.0.0/0 in the firewall configuration.
Whitelisting
with Algolia Vault, you will be able to whitelist one or more IPs and restrict the access to only those IPs.
Limits on the number of IPs for the firewall
You can only use up to 1000 IPs in the whitelist of the firewall.
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/ |
|
|
GET |
/1/indexes/ |
|
|
POST |
/1/indexes/*/queries |
|
|
POST |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
GET |
/1/indexes/ |
Search index (POST)
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:
params
|
type: URL-encoded string
default: "" (no search parameters)
Optional
Search parameters |
Errors:
400: Bad request or request argument404: Index does not exist
Example:
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",
"parsed_query": "george clo",
"params": "query=george%20clo&hitsPerPage=2&getRankingInfo=1"
}
Search index (GET)
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 argument404: Index does not exist
Example:
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
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:
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:
|
strategy
|
type: string
default: "none"
Optional
Allows optimizing execution of the queries by potentially skipping some of them. The following values are allowed:
Let’s illustrate
|
Errors:
400: Bad request argument404: Index does not exist
Example:
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
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 is not supported. The page and hitsPerPage parameters will be ignored.
By default, maximum 10 values are returned. This can be adjusted via maxFacetHits.
Parameters:
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
Maximum number of facet hits to return. For performance reasons, the maximum allowed number of returned values is 100. Any value outside the range [1, 100] will be rejected. |
Errors:
400: AttributefacetNameis not inattributesForFaceting, or not with thesearchable()specifier404: IndexindexNamedoes not exist
Example:
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 facethighlighted(string): Highlighted facet valuecount(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)
Path: /1/indexes/{indexName}/browse
HTTP Verb: POST
Required API Key: any key with the browse ACL
Description:
This method allows you to retrieve all index content (for backup, SEO or analytics purpose). It can retrieve up to 1,000 records per call and supports full text search and filters. You can use the same query parameters as for a search query.
For performance reasons, some features are not supported, including:
- the
distinctquery parameter (used for grouping or de-duplication) - sorting by typos, proximity, words or geo distance (only the custom ranking is applied)
The first call may specify search parameters via the params parameter.
When there is more content to be browsed, the response contains a cursor field. This cursor has to be passed to the
subsequent call to browse in order to get the next page of results. When the end of the index has been reached,
the cursor field is absent from the response.
Parameters:
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:
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": "filters=price%3C500"}' \
"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
{
"cursor": "jMDY3M2MwM2QwMWUxMmQwYWI0ZTN",
"hits":[
{
"name": "Betty Jane Mccamey",
"company": "Vita Foods Inc.",
"email": "betty@mccamey.com",
"objectID": "6891Y2usk0"
}
],
"page": 0,
"nbHits": 1,
"nbPages": 1,
"hitsPerPage": 1000,
"processingTimeMS": 1,
"query": "",
"params": "cursor=&filters=price%3c500"
}
Browse index (GET)
Path: /1/indexes/{indexName}/browse
HTTP Verb: GET
Required API Key: any key with the browse ACL
Description:
This is an alternative method to Browse all index content, allowing you to specify parameters via GET instead of POST.
Example:
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/ |
|
|
PUT |
/1/indexes/ |
|
|
DELETE |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
POST |
/1/indexes/*/batch |
|
|
POST |
/1/indexes/*/objects |
|
|
GET |
/1/indexes/ |
Add object (without ID)
Path: /1/indexes/{indexName}
HTTP Verb: POST
Required API Key: any key with the addObject ACL
Description:
Add an object to the index, automatically assigning it an object ID.
Errors:
400: InvalidindexNameor JSON
Example:
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 '{
"name": "Betty Jane Mccamey",
"company": "Vita Foods Inc.",
"email": "betty@mccamey.com" }' \
"https://${APPLICATION_ID}.algolia.net/1/indexes/contacts"
Upon success, the response is 201 Created, with the objectID attribute containing the ID assigned to the added object.
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
{
"createdAt":"2013-01-18T15:33:13.556Z",
"taskID": 678,
"objectID": "6891"
}
Add/update object (with ID)
Path: /1/indexes/{indexName}/{objectID}
HTTP Verb: PUT
Required API Key: any key with the addObject ACL
Description:
Add or replace an object with a given object ID. If the object does not exist, it will be created. If it already exists, it will be replaced.
Be careful: when an object already exists for the specified object ID, the whole object is replaced: existing attributes that are not replaced are deleted.
If you want to update only part of an object, use a partial update instead.
Errors:
400: InvalidindexNameor JSON
Example:
Copy
1
2
3
4
5
6
7
8
curl -X PUT \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--data-binary '{ \
"name": "Betty Jane Mccamey", \
"company": "Vita Foods Inc.", \
"email": "betty@mccamey.com" }' \
"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
5
{
"updatedAt":"2013-01-18T15:33:13.556Z",
"taskID": 679,
"objectID": "myID"
}
Delete object
Path: /1/indexes/{indexName}/{objectID}
HTTP Verb: DELETE
Required API Key: any key with the deleteObject ACL
Description:
Delete an existing object from an index.
Example:
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
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:
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
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: InvalidindexName
Example:
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 object
Path: /1/indexes/{indexName}/{objectID}/partial
HTTP Verb: POST
Required API Key: any key with the addObject ACL
Description:
Partially update an object.
This creates a brand new record if it doesn’t already exist (and the createIfNotExists parameter isn’t set to false).
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
For convenience, we provide five different built-in operations to update an attribute without pushing its entire value. These operations can be helpful if you don’t have access to your initial data.
Increment: increment a numeric attributeDecrement: decrement a numeric attributeAdd: append a number or string element to an array attributeRemove: remove all matching number or string elements from an array attribute made of numbers or stringsAddUnique: add a number or string element to an array attribute made of numbers or strings only if it’s not already presentIncrementFrom: 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 anIncrementFromvalue of 2 for theversionattribute, 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 anIncrementFromvalue 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 anIncrementSetvalue of 2 for theversionattribute, 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 anIncrementSetvalue that’s greater than 0.
For Remove and AddUnique: the operation will be silently ignored if the array attribute contains any nested object or array.
You can specify an operation by providing an object with two following properties:
_operation: the operation to apply on the attributevalue: the right-hand side argument to the operation (e.g., 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 incorrect 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:
createIfNotExists
|
type: boolean
default: true
Optional
When true, a partial update on a nonexistent object will create the object, assuming an empty object as the basis. When false, a partial update on a nonexistent object will be ignored. |
Errors:
400: InvalidindexNameor JSON
Example:
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
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 an object without ID. -
updateObject: Add or replace an existing object. You must set theobjectIDattribute to indicate the object to update. Equivalent to Add/update an object by ID. -
partialUpdateObject: Partially update an object. You must set theobjectIDattribute to indicate the object to update. Equivalent to Partially update an object. -
partialUpdateObjectNoCreate: Same aspartialUpdateObject, except that the object is not created if the object designated byobjectIDdoes not exist. -
deleteObject: Delete an object. You must set theobjectIDattribute 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:
requests
|
type: list
Required
List of operations to batch. Each operation is described by:
|
Example:
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](#get-a-tasks-status) command.
A typical response is:
Copy
1
2
3
4
{
"taskID": 792,
"objectIDs": ["6891", "6892"]
}
Batch write operations (multiple indices)
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 (e.g. if you have one index per user).
Parameters:
requests
|
type: list
Required
List of operations to batch. Each operation is described by:
|
Errors:
400: Invalid JSON
Example:
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
Path: /1/indexes/*/objects
HTTP Verb: POST
Required API Key: any key with the search ACL
Description:
Retrieve one or more objects, potentially from different indices, in a single API call.
The POST 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 objectobjectID(string): ID of the object within that indexattributesToRetrieve(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 argument404: Index does not exist
Example:
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
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:
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.
Attributes listed in |
Errors:
404: Index or object does not exist
Example:
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/ |
|
|
PUT |
/1/indexes/ |
Get settings
Path: /1/indexes/{indexName}/settings
HTTP Verb: GET
Required API Key: any key with the settings ACL
Description:
Retrieve index settings.
You can find the list of settings in the Settings Parameters page.
Errors:
404: Index does not exist
Example:
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
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:
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:
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/ |
|
|
POST |
/1/indexes/ |
|
|
GET |
/1/indexes |
Delete index
Path: /1/indexes/{indexName}
HTTP Verb: DELETE
Required API Key: any key with the deleteIndex ACL
Description:
Delete an existing index.
Example:
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/myIndex"
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
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:
operation
|
type: string
Required
Type of operation to perform: |
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: |
Errors:
400: Invalid JSON
Example:
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/index1/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
Path: /1/indexes
HTTP Verb: GET
Required API Key: any key with the listIndexes ACL
Description:
List existing indexes.
Parameters:
page
|
type: integer
default: null
Optional
Requested page (zero-based). When specified, will retrieve a specific page; the page size is implicitly set to 100.
When |
Example:
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
Backward compatibility
Synonyms were originally set via the index settings, and a Get settings call would return all synonyms as part of the settings JSON data.
This behavior has been kept to maintain backward compatibility. If you do not want synonyms to be included in your settings, add getVersion=2 to your request as a query parameter:
GET /1/indexes/{indexName}/settings?getVersion=2
Until you switch to this new Synonyms API, you can still manage your synonyms via the index settings.
Quick Reference
| Verb | Path | Method |
|---|---|---|
|
PUT |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
GET |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
DELETE |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
Save synonym
Path: /1/indexes/{indexName}/synonyms/{objectID}
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL
Description:
Create a new synonym object or update the existing synonym object with the given object ID.
objectID must be a unique value that identifies the synonym object.
If there is already a synonym object with this objectID in your index, it will be replaced.
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 on synonyms, please read our Synonyms guide.
Parameters:
forwardToReplicas
|
type: boolean
default: false
Optional
(URL parameter) Replicate the new/updated synonym set to all replica indices. |
Example:
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 '{ "objectID": "1", "type": "synonym", "synonyms": [ "iphone", "ephone", "aphone", "yphone", "apple phone"] }' \
"https://${APPLICATION_ID}.algolia.net/1/indexes/{indexName}/synonyms/{objectID}"
Batch synonyms
Path: /1/indexes/{indexName}/synonyms/batch
HTTP Verb: POST
Required API Key: any key with the editSettings ACL
Description:
Create/update multiple synonym objects at once, potentially replacing the entire list of synonyms
if replaceExistingSynonyms is true.
You should always use replaceExistingSynonyms to atomically replace all your synonyms on a production index.
This is the only way to ensure your index always has a list of synonyms to use during the indexing of the new list.
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": "1",
"type": "synonym",
"synonyms": [ "iphone", "ephone", "aphone", "yphone", "apple phone"]
},
{
"objectID": "2",
"type": "onewaysynonym",
"input": "iphone",
"synonyms": [ "ephone", "aphone", "yphone", "apple phone"]
}
]
Parameters:
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. |
Example:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--data-binary '[{
"objectID": "1",
"type": "synonym",
"synonyms": ["iphone", "ephone", "aphone", "yphone", "apple phone"]
},{
"objectID": "2",
"type": "onewaysynonym",
"input": "iphone",
"synonyms": ["ephone", "aphone", "yphone", "apple phone"]
}] ' \
"https://${APPLICATION_ID}.algolia.net/1/indexes/{indexName}/synonyms/batch"
Get synonym
Path: /1/indexes/{indexName}/synonyms/{objectID}
HTTP Verb: GET
Required API Key: any key with the editSettings ACL
Description:
Fetch a synonym object identified by its objectID.
Clear all synonyms
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:
forwardToReplicas
|
type: boolean
default: false
Optional
(URL parameter) Clear synonyms on the replica indices as well. |
Example:
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
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:
forwardToReplicas
|
type: boolean
default: false
Optional
(URL parameter) delete the synonyms set in all replica indices as well |
Example:
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
Path: /1/indexes/{indexName}/synonyms/search
HTTP Verb: POST
Required API Key: any key with the editSettings ACL
Description:
Search or browse all synonyms, optionally filtering them by type.
Parameters:
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: |
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 |
|
|
PUT |
/1/keys/ |
|
|
GET |
/1/keys |
|
|
GET |
/1/keys/ |
|
|
DELETE |
/1/keys/ |
|
|
POST |
/1/keys/ |
|
|
POST |
/1/indexes/ |
|
|
PUT |
/1/indexes/ |
|
|
GET |
/1/indexes/ |
|
|
GET |
/1/indexes/*/keys |
|
|
GET |
/1/indexes/ |
|
|
DELETE |
/1/indexes/ |
Add API Key
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:
acl
|
type: list
default: [] (no rights)
Optional
List of rights for the newly created key. The following rights can be used:
|
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 a leading and/or a trailing wildcard (
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 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. Each time an API call is performed with this key, a check is performed. If the IP at the origin of the call did more than the specified number of calls within the last hour, a 429 (Too Many Requests) status code is returned. 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 |
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: |
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 ( For example, |
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. |
Example:
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
Path: /1/keys/{key}
HTTP Verb: PUT
Required API Key: Admin
Description:
Update an 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.
Errors:
400: Invalid JSON
Example:
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/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
Path: /1/keys
HTTP Verb: GET
Required API Key: Admin
Description:
List API keys, along with their associated rights.
The request must be authenticated by the admin API key.
Example:
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
Path: /1/keys/{key}
HTTP Verb: GET
Required API Key: Any
Description:
Retrieve the details of a API key.
The request must be authenticated by the admin API key.
Example:
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
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:
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/107da8d0afc2d225ff9a7548caaf599f"
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
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 credentials404: The API key isn’t in the list of deleted API keys500: Builder not available
Example:
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
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:
acl
|
type: list
default: [] (no rights)
Optional
List of rights for the newly created key. The following rights can be used:
|
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. Each time an API call is performed with this key, a check is performed. If the IP at the origin of the call did more than the specified number of calls within the last hour, a 429 (Too Many Requests) status code is returned. 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 |
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: |
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 ( For example, |
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:
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
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 wether the API key exists or not. If you want to check if an API key exists prior to 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:
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)
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:
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)
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:
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
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:
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
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:
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/ |
|
|
POST |
/1/indexes/ |
|
|
GET |
/1/indexes/ |
|
|
DELETE |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
|
|
POST |
/1/indexes/ |
Save rule
Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL
Description:
Create or update the Rule with the specified objectID.
Parameters:
indexName
|
type: string
Required
Index name |
objectID
|
type: string
Required
|
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:
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"
}
}
}'
Batch Rules
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:
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 |
Example:
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"
}
}
}
]'
Get Rule
Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: GET
Required API Key: any key with the settings ACL
Description:
Retrieve the Rule with the specified objectID.
Parameters:
indexName
|
type: string
Required
Index name |
objectID
|
type: string
Required
objectID of the Rule to retrieve |
Example:
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}"
Delete Rule
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 objectID.
Parameters:
indexName
|
type: string
Required
Index name |
objectID
|
type: string
Required
objectID 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:
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}"
Clear Rules
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:
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:
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"
Search rules
Path: /1/indexes/{indexName}/rules/search
HTTP Verb: POST
Required API Key: any key with the settings ACL
Description:
Search for rules.
Parameters:
indexName
|
type: string
Required
Index name |
Example:
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"}'
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:
stopwordspluralscompounds(for decompounding and segmentation)
Quick Reference
| Verb | Path | Method |
|---|---|---|
|
POST |
/1/dictionaries/ |
|
|
GET |
/1/dictionaries/ |
|
|
POST |
/1/dictionaries/ |
|
|
PUT |
/1/dictionaries/*/settings |
|
|
GET |
/1/dictionaries/*/settings |
|
|
GET |
/1/dictionaries/*/languages |
Batch entries
Path: /1/dictionaries/{dictionaryName}/batch
HTTP Verb: POST
Description:
Send a batch of dictionary entries.
Parameters:
requests
|
type: list of
Required
List of operations to batch. Each operation is described by:
|
clearExistingDictionaryEntries
|
type: bool
default: false
Optional
When |
requests ➔ request
action
|
type: string
Required
Actions to perform. It can be one of the following values:
|
||
body
|
type: object
Required
The JSON object containing the information you need for the selected action. For example,
Copy
The request body depends on the |
deleteEntry ➔ delete object
objectID
|
type: string
Required
Unique identifier of the entry to add or override. |
addEntry ➔ stopword record
objectID
|
type: string
Required
Unique identifier of the entry to add or override. |
language
|
type: string
Required
Language ISO code supported by the dictionary (e.g., “en” for English). |
word
|
type: string
Required
The stop word being added or modified. When |
state
|
type: string
default: enabled
Optional
The state of the entry:
|
addEntry ➔ plural record
objectID
|
type: string
Required
Unique identifier of the entry to add or override. |
language
|
type: string
Required
Language ISO code supported by the dictionary (e.g., “en” for English). |
words
|
type: string
Required
List of word declensions. The entry overrides existing entries when any of these words are defined in the standard dictionary provided by Algolia. |
addEntry ➔ compound record
objectID
|
type: string
Required
Unique identifier of the entry to add or override. |
language
|
type: string
Required
Language ISO code supported by the dictionary (e.g., |
word
|
type: string
Required
|
decomposition
|
type: string array
Required
|
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 10MB limit.403: Custom dictionary entries quota exceeded.
Example:
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 entries
Path: /1/dictionaries/{dictionaryName}/search
HTTP Verb: GET
Description:
Search the dictionary entries.
Parameters:
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 (e.g., “en” for English). |
Errors:
400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.
Search entries
Path: /1/dictionaries/{dictionaryName}/search
HTTP Verb: POST
Description:
Search the dictionary entries.
Parameters:
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 (e.g., “en” for English). |
Errors:
400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.
Set dictionary settings
Path: /1/dictionaries/*/settings
HTTP Verb: PUT
Description:
Set dictionary settings.
Parameters:
stopwords
|
type: object
Required
Settings for the stop word dictionary. |
stopwords ➔ settings
disableStandardEntries
|
type: key/value mapping
Optional
Map of language ISO code supported by the dictionary (e.g., “en” for English) to a boolean value. When set to Changes are set for the given languages only. To re-enable standard entries, set the language to |
Errors:
400: Bad request. The provided JSON schema contains errors (missing mandatory keys or unexpected keys). Dictionary being queried is unknown.
Example:
The following disables the standard Russian entries ru, and enable standard French entries fr.
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
}
}
}'
Other languages remain untouched.
To reset stop words settings to default values, set stopwords to null.
Copy
1
2
3
4
5
{
"disableStandardEntries": {
"stopwords": null
}
}
Get dictionary settings
Path: /1/dictionaries/*/settings
HTTP Verb: GET
Description:
Retrieve dictionaries settings.
Example:
The API stores languages whose standard entries are disabled. Fetch settings does not return false values.
Copy
1
2
3
4
5
6
7
{
"disableStandardEntries": {
"stopwords": {
"ru": "true"
}
}
}
Available languages
Path: /1/dictionaries/*/languages
HTTP Verb: GET
Description:
List dictionaries supported per language.
Example:
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 language ISO codes and contains 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
}
}
- The German
desupportsplurals,stopwordsandcompoundsdictionaries. - The English
ensupports thepluralsandstopwordsdictionaries. Thecompoundsdictionary isn’t supported and has the valuenull. - All unsupported dictionary types have the value
null. - The API returns the number of user customizations in
nbCustomEntries. WhennbCustomEntriesis set to0, the user didn’t customize the dictionary. The dictionary is still supported with standard, Algolia-provided entries.
MultiClusters Endpoints
Limitation v0.1
For v0.1, the assignment of users to clusters won’t be automatic: if a user is not properly assigned, or not found, the call will be rejected.
How to get the feature
MCM needs to be enabled on your cluster. You can contact support@algolia.com for more information.
Quick Reference
| Verb | Path | Method |
|---|---|---|
|
POST |
/1/clusters/mapping |
|
|
POST |
/1/clusters/mapping/batch |
|
|
GET |
/1/clusters/mapping/top |
|
|
GET |
/1/clusters/mapping/ |
|
|
GET |
/1/clusters |
|
|
GET |
/1/clusters/mapping |
|
|
DELETE |
/1/clusters/mapping/ |
|
|
POST |
/1/clusters/mapping/search |
|
|
GET |
/1/clusters/mapping/pending |
Assign or Move userID
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:
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
Path: /1/clusters/mapping/batch
HTTP Verb: POST
Required API Key: Admin
Description:
Assign multiple userIDs to a cluster.
Example:
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
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:
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
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:
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
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:
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
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:
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:
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
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:
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
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:
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
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:
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-authorised sources the cluster becomes invisible.
Make sure you authorize the IP addresses of people/offices that need to access the dashboard, as it is also affected by the restricted list you setup.
By default, the firewall restriction is disabled and all the sources are allowed to reach the server
but they still need to provide valid application ID and api key to access the data stored on the cluster.
The first call to setup the firewall whitelist will enable it, it’s possible to allow all the source by adding the source 0.0.0.0/0.
It’s possible to add a special source ALGOLIA_SUPPORT to allow the support team of algolia to access the api.
The number of sources allowed is limited to 1000 sources for performance reason.
How to get the feature
Vault needs to be enabled on your cluster. You can contact support@algolia.com for more information.
Quick Reference
| Verb | Path | Method |
|---|---|---|
|
GET |
/1/security/sources |
|
|
PUT |
/1/security/sources |
|
|
POST |
/1/security/sources/append |
|
|
DELETE |
/1/security/sources/ |
List allowed sources
Path: /1/security/sources
HTTP Verb: GET
Description:
This command lists all your allowed sources.
Example:
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
Path: /1/security/sources
HTTP Verb: PUT
Description:
This command replaces the list of allowed sources.
Example:
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
Path: /1/security/sources/append
HTTP Verb: POST
Description:
This command adds an source to the list of allowed sources.
Example:
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
Path: /1/security/sources/{source}
HTTP Verb: DELETE
Description:
This command deleted one allowed source.
Parameters:
source
|
type: string
Required
Source to delete |
Example:
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 |
/1/indexes/ |
Get logs
Path: /1/logs
HTTP Verb: GET
Required API Key: any key with the logs ACL
Description:
Return the lastest log entries.
Please note that 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.
All logs have a seven-day retention period. After that, they’re no longer accessible from the API.
Parameters:
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:
You can retrieve the logs of your last 1,000 API calls. It is designed for real-time, immediate debugging. |
Example:
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"
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
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): eitherpublishedornotPublished, depending on the task’s current statuspendingTask(boolean): whether the index has remaining task(s) running
Interpreting the response
notPublishedistrueif the task hasn’t been processed yet,falseotherwise.pendingTaskis deprecated and shouldn’t be used.
Example:
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
}
