REST API

The REST API lets your interact directly with Algolia platforms from anything that can send an HTTP request.

We have also developed API clients for the most common programming languages and platforms. These clients are a wrapper on top of our REST API to ease development, they are released

Quick Reference

All API access is over HTTPS, and accessed via the https://{Application-ID}.algolia.io domain. Application-ID variable can be found in your admin interface.

The relative path prefix /1/ indicates that we are currently using version 1 of the API.

Indexes

URL HTTP VERB Functionality
/1/indexes
GET
List Indexes
/1/indexes/
{indexName}
GET
Query an index
/1/indexes/
{indexName}
/query
POST
Query an index (alternative)
/1/indexes/*/queries
POST
Query multiple indexes
/1/indexes/
{indexName}
DELETE
Delete an index
/1/indexes/
{indexName}
/clear
POST
Remove all content of an index
/1/indexes/
{indexName}
POST
Add an object without ID
/1/indexes/
{indexName}
/
{objectID}
PUT
Add/Update an object by ID
/1/indexes/
{indexName}
/
{objectID}
/partial
POST
Partially update an object by ID
/1/indexes/
{indexName}
/
{objectID}
GET
Get an object by ID
/1/indexes/*/objects
POST
Get several objects by ID
/1/indexes/
{indexName}
/
{objectID}
DELETE
Delete an object by ID
/1/indexes/
{indexName}
/batch
POST
Batch write operations
/1/indexes/
{indexName}
/settings
GET
Get index settings
/1/indexes/
{indexName}
/browse
GET
Browse all index content
/1/indexes/
{indexName}
/settings
PUT
Change index settings
/1/indexes/
{indexName}
/operation
POST
Copy/Move an index
/1/indexes/
{indexName}
/task/
{taskID}
GET
Get task status
/1/indexes/
{indexName}
/keys
POST
Add index specific API key
/1/indexes/
{indexName}
/keys/
{key}
PUT
Update index specific API key
/1/indexes/
{indexName}
/keys
GET
List index specific API Keys
/1/indexes/*/keys
GET
List index specific API Keys for all indexes
/1/indexes/
{indexName}
/keys/
{key}
GET
Get the rights of an index specific API key
/1/indexes/
{indexName}
/keys/
{key}
DELETE
Delete index specific API key

Keys

URL HTTP VERB Functionality
/1/keys
POST
Add a global API key
/1/keys/
{key}
PUT
Update a global API key
/1/keys
GET
List global API Keys
/1/keys/
{key}
GET
Get the rights of a global API key
/1/keys/
{key}
DELETE
Delete a global API key

Logs

URL HTTP VERB Functionality
/1/logs
GET
Get last logs

Request Format

For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json.

Authentication is done via HTTP headers. The X-Algolia-Application-Id header identifies which application you are accessing, and the X-Algolia-API-Key header authenticates the endpoint (you can pass the admin key or any key that you can create with the API).

export APPLICATION_ID="your application id"
export API_KEY="your API key"

For Javascript usage, Algolia supports cross-origin resource sharing, so that you can use these headers in conjunction with XMLHttpRequest.

Request from browser with secure restriction

You may have a single index containing per-user data. In that case, all records should be tagged with their associated user_id in order to add a tagFilters=user_42 filter at query time to retrieve only what a user has access to.

It will result in a security breach if you are performing the query directly from browser since the user is able to modify the tagFilters you've set modifying the JavaScript code. To keep sending the query from the browser (recommended for optimal latency) and target secured records, you can generate secured API keys from your backend and use them in your public JavaScript code (the backend will automatically apply the tag restriction and user will not be able to change them).

To do that you have to pass the list of tag restrictions you want to use in the X-Algolia-TagFilters header (for example X-Algolia-TagFilters: user_42) and set the X-Algolia-API-Key header to a secure API Key.

Those 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 secret for HMAC SHA-256
  • a list of tags defining the security filters (the content of X-Algolia-TagFilters header).
  • and an optional token identifying your user if you want to use this token instead of IP for rate limits. In that case you also need to pass the token identifying your user in the X-Algolia-UserToken header.

Response Format

The response format for all requests is a JSON object.

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 the field
message
which you can inspect to use for debugging. For example, trying to add an object with an invalid key will return the message:

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

Indexes API

List indexes

Path: /1/indexes
HTTP Verb:
GET
Description: This command lists all your existing indexes.

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     "https://${APPLICATION_ID}.algolia.io/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 and a
pendingTask
flag that indicates if it has remaining update task(s) running.

{
    "items": [
        {
            "name": "contacts",
            "createdAt": "2013-08-15T19:49:47.714Z",
            "updatedAt": "2013-08-17T07:59:28.313Z",
            "entries": 2436442,
            "pendingTask": false
        }
    ]
}

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Query an Index

Path: /1/indexes/
{indexName}
HTTP Verb:
GET
Description: Return objects that match the query.

Query parameters

Full Text Search parameters

Name Type Description
query string The instant-search query string, all words of the query are interpreted as prefixes (for example "John Mc" will match "John Mccamey" and "Johnathan Mccamey"). If no query parameter is set, retrieves all objects.
queryType string Selects how the query words are interpreted:
  • prefixAll: all query words are interpreted as prefixes,
  • prefixLast: only the last word is interpreted as a prefix (default behavior),
  • prefixNone: no query word is interpreted as a prefix. This option is not recommended.
typoTolerance string This setting has four different options:
  • true: activate the typo-tolerance (default value).
  • false: disable the typo-tolerance
  • min: keep only results with the lowest number of typo. For example if one result match without typos, then all results with typos will be hidden.
  • strict: if there is a match without typo, then all results with 2 typos or more will be removed. This option is useful if you want to avoid as much as possible false positive.
minWordSizefor1Typo integer The minimum number of characters in a query word to accept one typo in this word. Defaults to 4.
minWordSizefor2Typos integer The minimum number of characters in a query word to accept two typos in this word. Defaults to 8.
allowTyposOnNumericTokens boolean If set to false, disable typo-tolerance on numeric tokens (=numbers) in the query word. For example the query "304" will match with "30450", but not with "40450" that would have been the case with typo-tolerance enabled. Can be very useful on serial numbers and zip codes searches. Default to false.
ignorePlurals boolean If set to true, simple plural forms won't be considered as typos (for example car/cars will be considered as equal). Default to false.
restrictSearchableAttributes string List of attributes you want to use for textual search (must be a subset of the attributesToIndex index setting). Attributes are separated with a comma (for example "name,address" ), you can also use a JSON string array encoding (for example encodeURIComponent("[\"name\",\"address\"]") ). By default, all attributes specified in attributesToIndex settings are used to search.
advancedSyntax boolean Enable the advanced query syntax. Defaults to 0 (false).
  • Phrase query: a phrase query defines a particular sequence of terms. A phrase query is build by Algolia's query parser for words surrounded by ". For example, "search engine" will retrieve records having search next to engine only. Typo-tolerance is disabled on phrase queries.
  • Prohibit operator: The prohibit operator excludes records that contain the term after the - symbol. For example search -engine will retrieve records containing search but not engine.
analytics boolean If set to false, this query will not be taken into account for the Analytics. Default to true.
analyticsTags comma-separated string list If set, tag your query with the specified identifiers. Tags can then be used in the Analytics to analyze a subset of searches only.
synonyms boolean If set to false, this query will not use synonyms defined in configuration. Default to true.
replaceSynonymsInHighlight boolean If set to false, words matched via synonyms expansion will not be replaced by the matched synonym in the highlighted result. Default to true.
optionalWords string Specify a list of words that should be considered as optional when found in the query. The list of words is comma separated. This list will be appended to the one defined in your index settings.
removeWordsIfNoResults string Configure the way query words are removed when the query doesn't retrieve any results. This option can be used to avoid having an empty result page. There is three different options:
  • lastWords: when a query does not return any result, the last word will be added as optionalWords (the process is repeated with the n-1 word, n-2 word, ... until there is results). This option is particularly useful on e-commerce websites
  • firstWords: when a query does not return any result, the first word will be added as optionalWords (the process is repeated with the second word, third word, ... until there is results). This option is useful on address search
  • none: No specific processing is done when a query does not return any result.
(Default to None)

Pagination parameters

Name Type Description
page integer Pagination parameter used to select the page to retrieve. Page is zero-based and defaults to 0. Thus, to retrieve the 10th page you need to set page=9
hitsPerPage integer Pagination parameter used to select the number of hits per page. Defaults to 20.

Parameters to control results content

Name Type Description
attributesToRetrieve string List of object attributes you want to retrieve (let you minimize the answer size). Attributes are separated with a comma (for example "name,address" ), you can also use a JSON string array encoding (for example encodeURIComponent("[\"name\",\"address\"]") ). By default, all attributes are retrieved. You can also use * to retrieve all values when an attributesToRetrieve setting is specified for your index.
attributesToHighlight string List of attributes you want to highlight according to the query. Attributes are separated by a comma. You can also use a JSON string array encoding (for example encodeURIComponent("[\"name\",\"address\"]") ). If an attribute has no match for the query, the raw value is returned. By default all indexed text attributes are highlighted. You can use * if you want to highlight all textual attributes. Numerical attributes are not highlighted. A matchLevel is returned for each highlighted attribute and can contain:
  • full:
    if all the query terms were found in the attribute,
  • partial:
    if only some of the query terms were found,
  • none:
    if none of the query terms were found.
attributesToSnippet string List of attributes to snippet alongside the number of words to return (syntax is'attributeName:nbWords').Attributes are separated by a comma (Example:attributesToSnippet=name:10,content:10). You can also use a JSON string array encoding (Example:encodeURIComponent("[\"name:10\",\"content:10\"]")) By default no snippet is computed.
getRankingInfo integer If set to 1, the result hits will contain ranking information in
_rankingInfo
attribute.

Numeric search parameters

Name Type Description
numericFilters string The list of numeric filters you want to apply separated by a comma. The syntax of one filter is AttributeName followed by Operator followed by Value .
Supported operators are: < <= = > >= != .

You can easily perform range queries via the : operator (equivalent to combining >= and <= operators), for example numericFilters=price:10 to 1000.

You can also mix OR and AND operators. The OR operator is defined with a parenthesis syntax. For example (code=1 AND (price:[0-100] OR price:[1000-2000])) translates in encodeURIComponent("code=1,(price:0 to 10,price:1000 to 2000)").

You can also use a JSON string array encoding. For example: encodeURIComponent("[\"price>100\",\"code=1\"]")

Category search parameter

Name Type Description
tagFilters string Filter the query by a set of tags. You can AND tags by separating them by commas. To OR tags, you must add parentheses. For example:tagFilters=tag1,(tag2,tag3)means tag1 AND (tag2 OR tag3) . At indexing, tags should be added in the
_tags
attribute of objects (for example{"_tags":["tag1","tag2"]}). You can also use a JSON string array encoding, for exampleencodeURIComponent("[\"tag1\",[\"tag2\",\"tag3\"]]")means tag1 AND (tag2 OR tag3) . Negations are supported via the - operator, prefixing the value. For example:tagFilters=tag1,-tag2.

Distinct parameter

Name Type Description
distinct boolean Enable the distinct feature (disabled by default) if the attributeForDistinct index setting is set. This feature is similar to the SQL "distinct" keyword: when enabled in a query with the distinct=1 parameter, all hits containing a duplicate value for the attributeForDistinct attribute are removed from results. For example, if the chosen attribute is show_name and several hits have the same value for show_name, then only the best one is kept and others are removed.

This feature is disabled if the query string is empty and there isn't any tagFilters, nor any facetFilters, nor any numericFilters parameters.

Faceting parameters

Name Type Description
facets string List of object attributes that you want to use for faceting. Attributes are separated with a comma (for example "category,author" ). You can also use a JSON string array encoding (for example encodeURIComponent("[\"category\",\"author\"]") ). Only attributes that have been added in attributesForFaceting index setting can be used in this parameter. You can also use * to perform faceting on all attributes specified in attributesForFaceting.
facetFilters string Filter the query by a list of facets. Facets are separated by commas and each facet is encoded as attributeName:value. To OR facets, you must add parentheses. For example:facetFilters=(category:Book,category:Movie),author:John%20Doe. You can also use a JSON string array encoding (for example encodeURIComponent("[[\"category:Book\",\"category:Movie\"],\"author:John Doe\"]") ). Negations are supported via the - operator, prefixing the facet value. For example: encodeURIComponent("[\"category:Book\",\"category:-Movie\",\"author:John Doe\"]") .
maxValuesPerFacet integer Limit the number of facet values returned for each facet. For example:maxValuesPerFacet=10will retrieve max 10 values per facet.

Geo-search parameters

Name Type Description
aroundLatLng string Search for entries around a given latitude/longitude (specified as two floats separated by a comma, for examplearoundLatLng=47.316669,5.016670). You can specify the maximum distance in meters with the aroundRadius parameter. At indexing, you should specify the geoloc of an object with the
_geoloc
attribute (in the form_geoloc":{"lat":48.853409, "lng":2.348800}).
aroundLatLngViaIP boolean Same than aroundLatLng but using IP geolocation instead of manually specified latitude/longitude.
aroundRadius integer Control the radius associated with a aroundLatLng query. In meter.
aroundPrecision integer Control the precision of a aroundLatLng query. In meter. For example if you setaroundPrecision=100, two objects that are separated by less than 100 meters will be considered as identical by the
geo
ranking parameter.
insideBoundingBox string Search for entries inside a given area defined by the two extreme points of a rectangle (defined by 4 floats: p1Lat,p1Lng,p2Lat, p2Lng, for exampleinsideBoundingBox=47.3165,4.9665,47.3424,5.0201). At indexing, you should specify geoloc of an object with the
_geoloc
attribute (in the form_geoloc":{"lat":48.853409, "lng":2.348800}).
All parameters' defaults can be changed with the change settings API.

Example:

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

Note: You can also query an index via a POST method. This alternative method has a constant URL and allows web browser to cache OPTION requests of cross-origin resource sharing (CORS). The GET method has a different URL per query and thus force the browser to perform on OPTION request for each query without any way to cache them.

The POST body must contain a JSON object with a
params
attribute that contains URL parameters of the equivalent GET query:

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}.algolia.io/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:

{
    "hits": [
        {
            "name": "George Clooney",
            "objectID": "2051967",
            "_highlightResult": {
                "name": {
                    "value": "<em>George</em> <em>Clo</em>oney",
                    "matchLevel": "full"
                }
            },
            "_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",
    "params": "query=george%20clo&hitsPerPage=2&getRankingInfo=1"
}

Errors:

Error code Reason
400 Bad request argument
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index does not exist

Multiple queries

Path: /1/indexes/*/queries
HTTP Verb:
POST
Description: This method allows to query multiple indexes with one API call.

The POST body must contain the set of queries inside the
requests
attribute, results will be received in the same order as the queries in the
results
attribute.

Each query is described by a
indexName
attribute to specify the index on which query will be applied and a
params
attribute that specify the query. Syntax of
params
is the same that arguments of search query. You must also url encode params.

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\" }
                    }" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/*/queries"
When queries are successful, the HTTP response is a 200 OK and returns all results:

{
  "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"
    }
  ]
}

Errors:

Error code Reason
400 Bad request argument
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index does not exist

Delete an index

Path: /1/indexes/
{indexName}
HTTP Verb:
DELETE
Description: This method deletes an existing index.

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/contacts"
When delete is successful, the HTTP response is a 200 OK and returns the delete date:

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Clear Index

Path: /1/indexes/
{indexName}
/clear
HTTP Verb:
POST
Description: This method deletes the index content. Settings and index specific API keys are kept untouched.

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/clear"
When delete is successful, the HTTP response is a 200 OK and returns the delete date:

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Add one object with automatic ID

Path: /1/indexes/
{indexName}
HTTP Verb:
POST
Description: This method adds one object in the index with automatic assignation of objectID.

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.io/1/indexes/contacts"
The HTTP response is a 201 Created with the
objectID
attribute containing the ID when the add is taken into account but not yet executed. You can check the status of the execution via the
taskID
attribute and the get task command.

{ 
  "createdAt":"2013-01-18T15:33:13.556Z", 
  "taskID": 678, 
  "objectID": "6891" 
}

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Add or replace an object by ID

Path: /1/indexes/
{indexName}
/
{objectID}
HTTP Verb:
PUT
Description: This method adds or replaces an object (if the object does not exist, it will be created). 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 partial update instead.

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.io/1/indexes/contacts/myID"
The HTTP response is a 200 OK when the update is taken into account but not yet executed. You can check the status of the execution via the
taskID
attribute and the get task command.

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Partially update an object

Path: /1/indexes/
{indexName}
/
{objectID}
/partial
HTTP Verb:
POST
Description: This method updates part of an object (if the object does not exist, it will be created. You can avoid an automatic creation of the object by passing createIfNotExists=false as query argument).

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.io/1/indexes/contacts/myID/partial"
The HTTP response is a 200 OK when the update is taken into account but not yet executed. You can check the status of the execution via the
taskID
attribute and the get task command.

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Get an object

Path: /1/indexes/
{indexName}
/
{objectID}
HTTP Verb:
GET
Description: This method returns one object from the index.

This method has one optional parameter:

Name Type Description
attribute string This parameter lets you specify the list of attributes you want to retrieve (Attributes' names are case sensitive and comma separated).

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

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index or object does not exist

Retrieve several objects

Path: /1/indexes/*/objects
HTTP Verb:
POST
Description: This method allows to retrieve several objects with one API call.

The POST body must contain the set of queries inside the
requests
attribute, results will be received in the same order as the requests in the
results
attribute.

Each object is described by a
indexName
attribute to specify the index and a
objectID
attribute that specify the unique identifier of object to retrieve.

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \"requests\": [
                      { \"indexName\": \"index1\", \"objectID\": \"obj1\" },
                      { \"indexName\": \"index1\", \"objectID\": \"obj2\" }
                    }" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/*/objects"
If all objects are found, the HTTP response is a 200 OK and returns all results:

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

  ]
}

Errors:

Error code Reason
400 Bad request argument
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index does not exist

Delete an object

Path: /1/indexes/
{indexName}
/
{objectID}
HTTP Verb:
DELETE
Description: This method deletes an existing object from the index

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/contacts/myID"
The HTTP response is a 200 OK when the delete is taken into account but not yet executed. You can check the status of the execution via the
taskID
attribute and the get task command.

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Batch write operations

Path: /1/indexes/
{indexName}
/batch
HTTP Verb:
POST
Description: To reduce the amount of time spent on network round trips, you can create, update, or delete several objects in one call, using the batch endpoint (all operations are done in the given order).

Algolia Search accepts two formats of batches.

In the first format, you have just to give the HTTP method, the path of the command and the body. As you are doing a set of modification on the same index, the
indexName
component of path will be ignored.

{
  "requests"  : [ 
    { 
      "method": "POST", 
      "path": "/1/indexes/contacts", 
      "body": { 
                "name": "Betty Jane Mccamey", 
                "company": "Vita Foods Inc.", 
                "email": "betty@mccamey.com" 
              }
    },
    {
        "method": "POST",
        "path": "/1/indexes/contacts",
        "body": { 
                  "name": "Gayla Geimer", 
                  "company": "Ortman Mccain Co", 
                  "email": "gayla@geimer.com" 
                }
      }
  ]
}

Notes: A batch request MUST target a single index. If you need to populate several indexes, please consider using a batch request per index.

In the second format, you can specify the action via a
action
keyword and the target object.

There is six different actions supported:

  • addObject:
    Add an object.Equivalent to the add object without ID API.
  • updateObject:
    Add or replace an existing object by ID. You need to set the
    objectID
    attribute to indicate the object to update. Equivalent to the add/update an object by ID API.
  • partialUpdateObject:
    Replaces partially an object. You need to set the
    objectID
    attribute to indicate the object to update. Equivalent to the partial update an object by ID API.
  • partialUpdateObjectNoCreate:
    Same as
    partialUpdateObject
    except that the object is not created if the object designed by
    objectID
    does not exist.
  • deleteObject:
    Deletes an object. You need to set the
    objectID
    attribute to indicate the object to delete. Equivalent to the delete an object API.
  • clear:
    Remove the index content, but keep settings and index specific API keys untouched. Equivalent to the clear index API.

{
  "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 batchFile.json, the following curl command will apply it:

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.io/1/indexes/contacts/batch"
The HTTP response is a 200 OK when the batch is taken into account but not yet executed. You can check the status of the execution via the
taskID
attribute and the get task command. The result contains a set of results

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Browse all index content

Path: /1/indexes/
{indexName}
/browse
HTTP Verb:
GET
Description: This method allows to retrieve all index content (for backup or for analysis).

The list of attributes in the setting object are:

Name Type Description
page integer Pagination parameter used to select the page to retrieve. Page is zero-based and defaults to 0. Thus, to retrieve the 10th page you need to set page=9
hitsPerPage integer Pagination parameter used to select the number of hits per page. Defaults to 1000.
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/contacts/browse"

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

{
  "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": ""
}

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index does not exist

Get index settings

Path: /1/indexes/
{indexName}
/settings
HTTP Verb:
GET
Description: This method retrieve index settings.

List of attributes in the setting object

Indexing parameters

Name Type Description
attributesToIndex string array The list of fields you want to index. If set to null, all textual attributes of your objects are indexed, but you should update it to get optimal results. This parameter has two important uses:
  • Limit the attributes to index. For example if you store a binary image in base64, you want to store it and be able to retrieve it but you don't want to search in the base64 string.
  • Control part of the ranking (see the ranking parameter for full explanation). Matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list. In one attribute, matching text at the beginning of the attribute will be considered more important than text after, you can disable this behavior if you add your attribute inside unordered(AttributeName), for example attributesToIndex:["title", "unordered(text)"].

All numerical attributes are automatically indexed as numerical filters. If you don't need filtering on some of your numerical attributes, please consider sending them as strings to speed up the indexing.
You can decide to have the same priority for several attributes by passing them in the same string using comma as separator. For example title and alternative_title have the same priority in this example: attributesToIndex:["title,alternative_title", "text"]

attributesForFaceting string array The list of fields you want to use for faceting. All strings in the attribute selected for faceting are extracted and added as a facet. By default, no attribute is used for faceting.
attributeForDistinct string The attribute name used for the Distinct feature. This feature is similar to the SQL "distinct" keyword: when enabled in query with the distinct=1 parameter, all hits containing a duplicate value for this attribute are removed from results. For example, if the chosen attribute is show_name and several hits have the same value for show_name, then only the best one is kept and others are removed.

This feature is disabled if the query string is empty and there isn't any tagFilters, nor any facetFilters, nor any numericFilters parameters.

ranking string array Controls the way results are sorted. We have nine available criteria:
  • typo: sort according to number of typos,
  • geo: sort according to decreasing distance when performing a geo-location based search,
  • words: sort according to the number of query words matched by decreasing order. This parameter is useful when you use optionalWords query parameter to have results with the most matched words first.
  • proximity: sort according to the proximity of query words in hits,
  • attribute: sort according to the order of attributes defined by attributesToIndex,
  • exact:
    • if the user query contains one word: sort objects having an attribute that is exactly the query word before others. For example if you search for the "V" TV show, you want to find it with the "V" query and avoid to have all popular TV show starting by the v letter before it.
    • if the user query contains multiple words: sort according to the number of words that matched exactly (and not as a prefix).
  • custom: sort according to a user defined formula set in customRanking attribute.
  • asc(attributeName): sort according to a numeric attribute by ascending order. attributeName can be the name of any numeric attribute of your records (integer, a double or boolean).
  • desc(attributeName): sort according to a numeric attribute by descending order. attributeName can be the name of any numeric attribute of your records (integer, a double or boolean).
The standard order is ["typo", "geo", "words", proximity", "attribute", "exact", "custom"].
customRanking string array Lets you specify part of the ranking. The syntax of this condition is an array of strings containing attributes prefixed by asc (ascending order) or desc (descending order) operator. For example "customRanking": ["desc(population)", "asc(name)"]
separatorsToIndex string Specify the separators (punctuation characters) to index. By default, separators are not indexed. Use "+#" to be able to search Google+ or C#.
slaves string array The list of indexes on which you want to replicate all write operations. In order to get response times in milliseconds, we pre-compute part of the ranking during indexing. If you want to use different ranking configurations depending of the use-case, you need to create one index per ranking configuration. This option enables you to perform write operations only on this index, and to automatically update slave indexes with the same operations.
unretrievableAttributes string array List of attributes that cannot be retrieved at query time. This feature allows you to have an attribute that is used for indexing and/or ranking but which cannot be retrieved. Default to null.
allowCompressionOfIntegerArray boolean Allows compression of big integer arrays. We recommended to store the list of user ID or rights as an integer array and enable this setting. When enabled the integer array are reordered to reach a better compression ratio. Default to false.

Query expansion

Name Type Description
synonyms array of strings array An array of array of words considered as equal. For example, you may want to retrieve your black ipad record when your users are searching for dark ipad, even if the dark word is not part of the record: so you need to configure dark as a synonym of black. For example "synomyms": [ [ "black", "dark" ], [ "small", "little", "mini" ], ... ].
placeholders hash(string, array of strings) This is an advanced use case to define a token substitutable by a list of words without having the original token searchable. It is defined by a hash associating placeholders to lists of substitutable words. For example "placeholders": { "<streetnumber>": ["1", "2", "3", ..., "9999"]} placeholder to be able to match all street numbers (we use the < > tag syntax to define placeholders in an attribute). For example:
  • Push a record with the placeholder: { "name" : "Apple Store", "address" : "<streetnumber> Opera street, Paris" }
  • Configure the placeholder in your index settings: "placeholders": { "<streetnumber>" : ["1", "2", "3", "4", "5", ... ], ... }.
disableTypoToleranceOn string array Specify a list of words on which the automatic typo tolerance will be disabled.
altCorrections object array Specify alternative corrections that you want to consider. Each alternative correction is described by an object containing three attributes:
  • word the word to correct
  • correction the corrected word
  • nbTypos the number of typos (1 or 2) that will be considered for the ranking algorithm (1 typo is better than 2 typos)
For example "altCorrections": [ { "word" : "foot", "correction": "feet", "nbTypos": 1},
{ "word": "feet", "correction": "foot", "nbTypos": 1}]
.

The synonyms and placeholders features only support single-word expansions.

Default query parameters (can be overridden at query-time)

Name Type Description
minWordSizefor1Typo integer The minimum number of characters to accept one typo (default = 4).
minWordSizefor2Typos integer The minimum number of characters to accept two typos (default = 8).
hitsPerPage integer The number of hits per page (default = 10).
attributesToRetrieve string array Default list of attributes to retrieve in objects. If set to null, all attributes are retrieved.
attributesToHighlight string array Default list of attributes to highlight. If set to null, all indexed attributes are highlighted.
attributesToSnippet string array Default list of attributes to snippet alongside the number of words to return (syntax is 'attributeName:nbWords'). If set to null, no snippet is computed.
queryType string Select how the query words are interpreted, it can be one of the following value:
  • prefixAll : all query words are interpreted as prefixes,
  • prefixLast : only the last word is interpreted as a prefix (default behavior),
  • prefixNone : no query word is interpreted as a prefix. This option is not recommended.
highlightPreTag string Specify the string that is inserted before the highlighted parts in the query result (default to "<em>").
highlightPostTag string Specify the string that is inserted after the highlighted parts in the query result (default to "</em>").
optionalWords array of string Specify a list of words that should be considered as optional when found in the query.
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/contacts/settings"

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index does not exist

Change index settings

Path: /1/indexes/
{indexName}
/settings
HTTP Verb:
PUT
Description: This method updates part of index settings, the list of attributes and their behavior are listed in the get index settings API.

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{
      \"hitsPerPage\": 50,
      \"attributesToIndex\": [\"name\", \"email\", \"address\"],
      \"customRanking\": [\"desc(population)\", \"asc(name)\"]
     }" \
    "https://${APPLICATION_ID}.algolia.io/1/indexes/contacts/settings"
The HTTP response is a 200 OK when the update is taken into account but not yet executed. You can check the status of the execution via the
taskID
attribute and the get task command.

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Copy/Move an index

Path: /1/indexes/
{indexName}
/operation
HTTP Verb:
POST
Description: This method copy or move an existing index. If the destination index already exists, its specific API keys will be preserved and the source index specific API keys will be added.

The post JSON Object can contain two attributes:

Name Type Description
operation string Specify the type of operation: move or copy.
destination string Specify the name of the destination index

Here is an example to copy index1 into index2:

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.io/1/indexes/index1/operation"

The HTTP response is a 200 OK when the update is taken into account but not yet executed. You can check the status of the execution via the taskID attribute and the get task command.

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Get task status

Path: /1/indexes/
{indexName}
/task/
{task}
HTTP Verb:
GET
Description: This method gets the status of a given task (published or notPublished). Returns also a pendingTask flag that indicates if the index has remaining task(s) running.

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

When the query is successful, the HTTP response is a 200 OK and returns a the status of the task:

{
  "status": "published",
  "pendingTask": false
}

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Add index specific API Key

Path: /1/indexes/
{indexName}
/keys
HTTP Verb:
POST
Description: This method add a new key that can access to this index.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

The post JSON Object can contains two attributes:

Name Type Description
validity integer (optional) Specify a validity for this key in seconds (the key will automatically be removed after this period of time). Defaults to 0 (no validity limit).
maxQueriesPerIPPerHour integer (optional) Specify the maximum number of API calls allowed from an IP address per hour. 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 this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
Note: If you are sending 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.
maxHitsPerQuery integer (optional) Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
acl string array Contains the list of rights for this key. Here is the complete list of ACL that can be used for a key:
  • search: allow to search
  • browse: allow to retrieve all index content via the browse API
  • addObject: allows to add/update an object in the index
  • deleteObject: allows to delete an existing object
  • deleteIndex: allows to delete index content
  • settings: allows to get index settings
  • editSettings: allows to change index settings
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.io/1/indexes/contacts/keys"

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

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Update index specific API Key

Path: /1/indexes/
{indexName}
/keys/
{key}
HTTP Verb:
PUT
Description: This method update a key that can access to this index.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

The post JSON Object can contains two attributes:

Name Type Description
validity integer (optional) Specify a validity for this key in seconds (the key will automatically be removed after this period of time). Defaults to 0 (no validity limit).
maxQueriesPerIPPerHour integer (optional) Specify the maximum number of API calls allowed from an IP address per hour. 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 this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
Note: If you are sending 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.
maxHitsPerQuery integer (optional) Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
acl string array Contains the list of rights for this key. Here is the complete list of ACL that can be used for a key:
  • search: allow to search
  • browse: allow to retrieve all index content via the browse API
  • addObject: allows to add/update an object in the index
  • deleteObject: allows to delete an existing object
  • deleteIndex: allows to delete index content
  • settings: allows to get index settings
  • editSettings: allows to change index settings
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.io/1/indexes/contacts/keys"

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

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

List index specific API keys

Path: /1/indexes/
{indexName}
/keys
HTTP Verb:
GET
Description: This method Lists API keys that have access to this index with their rights. These keys have been created with the add index specific key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index does not exist

List index specific API keys for all indexes

Path: /1/indexes/*/keys
HTTP Verb:
GET
Description: This method Lists API keys that have access to one index with their rights. These keys have been created with the add index specific key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

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

{ 
    "keys": [
        { 
          "value": "ff96f7ec62b983bd87c4896a8e0b3508", 
          "acl": ["search", "addObject"], 
          "validity": 0,
          "index": "contacts"
        },
        { 
          "value": "107da8d0afc2d225ff9a7548caaf599f", 
          "acl": ["search"], 
          "validity": 0,
          "index": "contacts"
        }
    ]
}

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Get the rights of an index specific API key

Path: /1/indexes/
{indexName}
/keys/
{key}
HTTP Verb:
GET
Description: This method returns the rights of a given index specific API key that has been created with the add index specific key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid
404 Index or key does not exist

Delete an index specific API key

Path: /1/indexes/
{indexName}
/keys/
{key}
HTTP Verb:
DELETE
Description: This method delete an index specific API key that have been created with the add index specific key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

When the query is successful, the HTTP response is a 200 OK and returns the date aof deletion. You can check the status of the execution via the

taskID
attribute and the get task command.

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Keys API

Add global API Key

Path: /1/keys
HTTP Verb:
POST
Description: This method add a new global API key.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

The post JSON Object can contains two attributes:

Name Type Description
validity integer (optional) Specify a validity for this key in seconds (the key will automatically be removed after this period of time). Defaults to 0 (no validity limit).
maxQueriesPerIPPerHour integer (optional) Specify the maximum number of API calls allowed from an IP address per hour. 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 this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
Note: If you are sending 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.
maxHitsPerQuery integer (optional) Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
acl string array Contains the list of rights for this key. Here is the complete list of ACL that can be used for a key:
  • search: allow to search
  • browse: allow to retrieve all index content via the browse API
  • addObject: allows to add/update an object in the index
  • deleteObject: allows to delete an existing object
  • deleteIndex: allows to delete index content
  • settings: allows to get index settings
  • editSettings: allows to change index settings
indexes string array Restrict this new API key to specific index names. This option is useful if you want to isolate your development and production environments: you can have one API key targeting all development indices and another one that target all production indices. You can target all indices starting by a prefix or finishing by a suffix with the '*' character (for example "dev_*" matches all indices starting by "dev_" and "*_dev" matches all indices finishing by "_dev"). If the list is empty or not set, the API Key will be valid for all indices.
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.io/1/keys"

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

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Update a global API Key

Path: /1/keys/
{key}
HTTP Verb:
PUT
Description: This method update a global API key.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

The post JSON Object can contains:

Name Type Description
validity integer (optional) Specify a validity for this key in seconds (the key will automatically be removed after this period of time). Defaults to 0 (no validity limit).
maxQueriesPerIPPerHour integer (optional) Specify the maximum number of API calls allowed from an IP address per hour. 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 this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
Note: If you are sending 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.
maxHitsPerQuery integer (optional) Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
acl string array Contains the list of rights for this key. Here is the complete list of ACL that can be used for a key:
  • search: allow to search
  • browse: allow to retrieve all index content via the browse API
  • addObject: allows to add/update an object in the index
  • deleteObject: allows to delete an existing object
  • deleteIndex: allows to delete index content
  • settings: allows to get index settings
  • editSettings: allows to change index settings
indexes string array Restrict this new API key to specific index names. This option is useful if you want to isolate your development and production environments: you can have one API key targeting all development indices and another one that target all production indices. You can target all indices starting by a prefix or finishing by a suffix with the '*' character (for example "dev_*" matches all indices starting by "dev_" and "*_dev" matches all indices finishing by "_dev"). If the list is empty or not set, the API Key will be valid for all indices.
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.io/1/keys"

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

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

Errors:

Error code Reason
400 Invalid JSON
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

List global API keys

Path: /1/keys
HTTP Verb:
GET
Description: This method Lists global API keys with their rights. These keys have been created with the add global key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Get the rights of a global API key

Path: /1/keys/
{key}
HTTP Verb:
GET
Description: This method returns the rights of a given global API key that has been created with the add global Key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Delete a global API key

Path: /1/keys/
{key}
HTTP Verb:
DELETE
Description: This method deletes a global API key that has been created with the add global Key API.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key.

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

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

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

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Logs API

Get last logs

Path: /1/logs
HTTP Verb:
GET
Description: Return last logs.
Note: The
X-Algolia-API-KEY
used in the header must be the admin key. This API is counted in your number of API calls but is not logged.

The url has two optionnal parameters:

Name Type Description
offset integer (optional) Specify the first entry to retrieve (0-based, 0 is the most recent log entry). Default to 0.
length integer (optional) Specify the maximum number of entries to retrieve starting at offset. Default to 10. Maximum allowed value: 1000.
onlyErrors boolean (optional) If set to true, the answer contains only API calls with error. This parameter is useful for debugging, especially when it is difficult to locate errors among many correct API calls.
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.io/1/logs"

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

{
    "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"
        }
    ]
}

Errors:

Error code Reason
403
X-Algolia-API-Key
or
X-Algolia-Application-ID
is invalid

Analytics beta

Unlike the Search API, the Analytics API must be reached via https://analytics.algolia.com/1. The Analytics API allows you to analyze your query logs.

Note: Some analytics queries can take up to several minutes.

Get popular searches

Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/popular
HTTP Verb:
GET
Description: Return popular queries for a set of indices.
Note: The
X-Algolia-API-KEY
must be the admin API key.

The endpoint has several parameters:

Name Type Description
size integer The number of popular queries to retrieve. Optional. Default is 100. Maximum is 10,000.
startAt integer The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").
endAt integer The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").
tags comma-separated list The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter. Optional.
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/popular?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
  "lastSearchAt": "2014-10-05T09:00:00.000Z",
  "searchCount": 28043,
  "topSearches": [
    {
      "avgHitCount": 3542,
      "avgHitCountWithoutTypos": 2942,
      "count": 297,
      "query": "rust"
    },
    {
      "avgHitCount": 617,
      "avgHitCountWithoutTypos": 617,
      "count": 261,
      "query": "blekko"
    },
    {
      "avgHitCount": 45,
      "avgHitCountWithoutTypos": 45,
      "count": 257,
      "query": "castar"
    },
    {
      "avgHitCount": 19248,
      "avgHitCountWithoutTypos": 2190,
      "count": 226,
      "query": "scala"
    },
    // [...]
  ]
}

Errors:

Error code Reason
403 Invalid credentials
500 Internal error

Get searches with 0 results

Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/noresults
HTTP Verb:
GET
Description: Return queries matching 0 records for a set of indices.
Note: The
X-Algolia-API-KEY
must be the admin API key.

The endpoint has several parameters:

Name Type Description
size integer The number of popular queries to retrieve. Optional. Default is 100. Maximum is 10,000.
startAt integer The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").
endAt integer The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").
tags comma-separated list The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter. Optional.
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/noresults?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
  "searchCount": 28170,
  "lastSearchAt": "2014-10-05T10:00:00.000Z",
  "topSearchesNoResuls": [
    {
      "query": "journalims",
      "count": 8
    },
    {
      "query": "segate",
      "count": 8
    },
    {
      "query": "ello buddy",
      "count": 7
    },
    {
      "query": "bootstrap angulardashboard",
      "count": 6
    },
    // [...]
  ]
}

Errors:

Error code Reason
403 Invalid credentials
500 Internal error
azalead