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 wrappers on top of our REST API to ease the development, they are open-source and available on GitHub.

Quick Reference

All API access is over HTTPS, and accessed via the https://{Application-ID}.algolia.net domain for all write operations and https://{Application-ID}-dsn.algolia.net domain for all read operations to use our Distributed Search Network option. 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.

In order to guarantee a very high-availability, we recommend to implement a retry strategy on : https://{Application-ID}-1.algolianet.com, then https://{Application-ID}-2.algolianet.com, then https://{Application-ID}-3.algolianet.com for all API calls (the domain is different because hosted on another DNS provider). All our standard API clients implement this retry strategy.

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

Clear 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

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

GET

Get an object

/1/indexes/*/objects

POST

Retrieve Several Objects

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

DELETE

Delete an object by ID

/1/indexes/{indexName}/batch

POST

Batch write operations

/1/indexes/{indexName}/browse

GET

Browse all index content

/1/indexes/{indexName}/settings

GET

Get index settings

/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 an index specific API key

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

PUT

Update an 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 an 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}-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 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,
            "lastBuildTimeS": 0,
            "dataSize": 224152664
        }
    ]
}

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.

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.

minProximity

integer

Configure the precision of the proximity ranking criterion. By default, the minimum (and best) proximity value distance between 2 matching words is 1. Setting it to 2 (or 3) would allow 1 (or 2) words to be found between the matching words without degrading the proximity ranking value.

Considering the query “javascript framework”, if you set minProximity=2 the records “JavaScript framework” and “JavaScript charting framework” will get the same proximity score, even if the second one contains a word between the 2 matching words. Default to 1.

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 are four 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

  • allOptional: When a query does not return any result, a second trial will be made with all words as optional (which is equivalent to transforming the AND operand between query terms in a OR operand)

  • 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 example: encodeURIComponent("[\"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 theattributeForDistinct 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.

NOTE: 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=10 will 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 example: aroundLatLng=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. Defined in meters, the value needs to be greather than 100m.

aroundPrecision

integer

Control the precision of a aroundLatLng query. In meter. For example if you set aroundPrecision=100, two objects that are in the range 0-99m will be considered as identic in the ranking for the .variable geo ranking parameter (same for 100-199, 200-299, … ranges).

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 example: insideBoundingBox=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}-dsn.algolia.net/1/indexes/imdb?query=george%20clo&hitsPerPage=2&getRankingInfo=1"

Query an Index (alternative)

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

{
    "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",
    "parsed_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

Query multiple indexes

  • 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}-dsn.algolia.net/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": "[email protected]",
          "objectID": "6891Y2usk0",
          "_highlightResult": {
              "name": {"value": "Betty <b>Jan</b>e Mccamey", "matchLevel": "full"},
              "company": {"value": "Vita Foods Inc.", "matchLevel": "none"},
              "email": {"value": "[email protected]", "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": "[email protected]",
          "objectID": "ap78784310"
          "_highlightResult": {
            "name": {"value": "Gayla Geimer <b>Dan</b>", "matchLevel": "full" },
            "company": {"value": "Ortman Mccain Co", "matchLevel": "none" },
            "email": {"highlighted": "[email protected]", "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.net/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.net/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 an object without 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\": \"[email protected]\" }" \
    "https://${APPLICATION_ID}.algolia.net/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/Update 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\": \"[email protected]\" }" \
    "https://${APPLICATION_ID}.algolia.net/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\": \"[email protected]\" }" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/myID/partial"

In addition, there is 5 different operations supported to update an attribute without pushing it’s value:

  • Increment: Increment a numeric-based attribute

  • Decrement: Decrement a numeric-based attribute

  • Add: Append an element to an array-based attribute

  • Remove: Remove the first element from an array-based attribute

  • AddUnique: Add an element to an array based-attribute if it doesn’t exist

{
  "_tags": {
    "_operation": "AddUnique",
    "value": "public"
  }
}

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

attributes

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

{
  "name": "Betty Jane Mccamey",
  "email": "[email protected]",
  "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}-dsn.algolia.net/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": "[email protected]",
      "objectID": "obj1"
    },
    {
      "name": "Stacey Blow",
      "email": "[email protected]"
      "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.net/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).

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": "[email protected]"
              }
    },
    {
        "action": "addObject",
        "body": {
                  "name": "Gayla Geimer",
                  "company": "Ortman Mccain Co",
                  "email": "[email protected]"
                }
      }
  ]
}

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.net/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"]
}

If you have one index per user, you may want to perform a batch operations across several indices:

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

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.net/1/indexes/*/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": {
      "contacts": 792,
      "public_contacts": 793
    },
  "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 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 than for a search query.

For performance reasons, some features are not supported, including:

  • the distinct query parameter (used for grouping or de-duplication)

  • the sort by typos

  • the sort by proximity

  • the sort by words

  • the sort by geo distance

To retrieve the next page, you need to pass to the list of query parameters the cursor returned in the previous response. When the browsing reaches the end of the index, the cursor attribute isn’t in the response anymore.

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?cursor=&numericFilters=price%3c500"

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

{
  "cursor": "jMDY3M2MwM2QwMWUxMmQwYWI0ZTN",
  "hits":[
    {
      "name": "Betty Jane Mccamey",
      "company": "Vita Foods Inc.",
      "email": "[email protected]",
      "objectID": "6891Y2usk0"
    }
  ],
  "page": 0,
  "nbHits": 1,
  "nbPages": 1,
  "hitsPerPage": 1000,
  "processingTimeMS": 1,
  "query": "",
  "params": "cursor=&numericFilters=price%3c500"
}

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)"].

NOTE: 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"]

numericAttributesToIndex

string array

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. If you only need to filter on a numeric value with the operator =, you can speed up the indexing by specifying the attribute with equalOnly(AttributeName). The other operators will be disabled.

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.

NOTE: 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. This setting will be bypassed if the query is done with the ADMIN API key. 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 string 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" ], ... ]. Synonym feature also supports multi-words expression like "synonyms": [ ["NY", "New York"] ].

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”: { “": ["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}].

NOTE: 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.

minProximity

integer

Configure the precision of the proximity ranking criterion. By default, the minimum (and best) proximity value distance between 2 matching words is 1. Setting it to 2 (or 3) would allow 1 (or 2) words to be found between the matching words without degrading the proximity ranking value.

Considering the query “javascript framework”, if you set minProximity=2 the records “JavaScript framework” and “JavaScript charting framework” will get the same proximity score, even if the second one contains a word between the 2 matching words. Default to 1.

highlightPreTag

string

Specify the string that is inserted before the highlighted parts in the query result (default to “”).

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}-dsn.algolia.net/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.net/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.net/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}-dsn.algolia.net/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 an 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 contain the following attributes:

Name

Type

Description

description

string

Used to identify a key.

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.

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

  • analytics: allows to retrieve the analytics through the analytics API

  • listIndexes: allows to list all accessible indexes

referers

string array

Restrict this new API key to specific referers. You can target all referers starting with a prefix or ending with a suffix using the ‘*’ character. For example, “algolia.com/*” matches all referers starting with “algolia.com/” and “*.algolia.com” matches all referers ending with “.algolia.com”. Defaults to all referers if empty or blan

queryParameters

string

Force some query parameters to be applied foreach query made with this api key. You can force all query parameters like: “typoTolerance=strict&ignorePlurals=false&facetFilters=rights:public”. The parameters use the url string format.

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).

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.

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"

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 an 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.

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"

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.net/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.net/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.net/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.net/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 a 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 contain the following 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

  • analytics: allows to retrieve the analytics through the analytics API

  • listIndexes: allows to list all accessible indexes

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.

referers

string array

Restrict this new API key to specific referers. You can target all referers starting with a prefix or ending with a suffix using the ‘*’ character. For example, “algolia.com/*” matches all referers starting with “algolia.com/” and “*.algolia.com” matches all referers ending with “.algolia.com”. Defaults to all referers if empty or blank.

queryParameters

string

Force some query parameters to be applied foreach query made with this api key. You can force all query parameters like: “typoTolerance=strict&ignorePlurals=false&facetFilters=rights:public”. The parameters use the url string format.

description

string

Used to identify a key.

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:

{
    "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.

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 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.net/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.net/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.net/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.

type

string (optional)

Specify the type of logs to retrieve. This parameter is useful for debugging, especially when it is difficult to locate errors among many API calls:

  • all (default): Retrieve all logs

  • query: Retrieve only the queries

  • build: Retrieve only the build operations

  • error: Retrieve only the errors

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 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 API

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.

  • 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.

country

string

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value. Optional.

refinements

boolean

If enabled, returns the most used refinements for each search. (default=false)

csv

boolean

If enabled, returns the answer using CSV instead of JSON. (default=false)

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": "castar",
      "topRefinements" : [
        {
            "tag" : "comment",
            "count" : 296
        },
        {
            "tag" : "job",
            "count" : 296
        },
        {
            "count" : 296,
            "tag" : "poll"
        },
        {
            "count" : 296,
            "tag" : "story"
        }
      ]
    },
    {
      "avgHitCount": 617,
      "avgHitCountWithoutTypos": 617,
      "count": 261,
      "query": "spacex"
      "topRefinements" : [
        {
          "count" : 99,
          "tag" : "comment"
        },
        {
          "count" : 99,
          "tag" : "job"
        },
        {
          "tag" : "poll",
          "count" : 99
        },
        {
          "count" : 99,
          "tag" : "story"
        }
      ],
    },
    // [...]
  ]
}

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.

country

string

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value. Optional.

refinements

boolean

If enabled, returns the most used refinements for each search. (default=false)

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/countries
  • HTTP Verb: GET
  • Description: Return popular countries 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.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/countries?startAt=${startAt}&endAt=${endAt}"

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

{
   "searchCount" : 15753,
   "lastSearchAt" : "2015-02-11T14:00:00.000Z",
   "countryCount" : {
      "DE" : 914,
      "US" : 8101,
      "GB" : 932,
      // [...]
   }

}

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Searches with 0, <5 and <10 Hits

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/hits
  • HTTP Verb: GET
  • Description: Return searches matching 0, <5 and <10 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.

country

string

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/hits?startAt=${startAt}&endAt=${endAt}"

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

{
   "searchCount" : 15731,
   "lastSearchAt" : "2015-02-11T14:00:00.000Z",
   "topSearchesLowHitsWithoutTypos" : {
      "0 hit" : [
         {
            "query" : "calendar node",
            "refinements" : {
               "key" : "tag",
               "value" : "story"
            },
            "avgHitCount" : 1,
            "count" : 2
         },
         // [...]
      ],
      "< 5 hits" : [
         {
            "query" : "voltera",
            "refinements" : {
               "key" : "tag",
               "value" : "story"
            },
            "avgHitCount" : 3,
            "count" : 18
         },
         // [...]
      ],
      "< 10 hits" : [
         {
            "query" : "voltera",
            "refinements" : {
               "value" : "story",
               "key" : "tag"
            },
            "avgHitCount" : 3,
            "count" : 25
         },
         // [...]
      ]
   }
}

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Searches with 0, <5 and <10 Hits Including Typos

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/hitswithtypo
  • HTTP Verb: GET
  • Description: Return searches matching 0, <5 and <10 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.

country

string

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/hitswithtypo?startAt=${startAt}&endAt=${endAt}"

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

{
   "searchCount" : 15748,
   "lastSearchAt" : "2015-02-11T14:00:00.000Z",
   "topSearchesLowHits" : {
      "0 hit" : [
         {
            "query" : "calendar node",
            "refinements" : [
               {
                  "value" : "story",
                  "key" : "tag"
               }
            ],
            "avgHitCount" : 1,
            "count" : 2
         },
         // [...]
      ],
      "< 5 hits" : [
         {
            "query" : "occupy gpl",
            "refinements" : [
               {
                  "value" : "story",
                  "key" : "tag"
               }
            ],
            "avgHitCount" : 4,
            "count" : 3
         },
         // [...]
      ],
      "< 10 hits" : [
         {
            "query" : "jeb bush",
            "refinements" : [
               {
                  "value" : "story",
                  "key" : "tag"
               }
            ],
            "avgHitCount" : 3,
            "count" : 9
         },
         // [...]
      ]
   }
}

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Top IPs

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/ips
  • HTTP Verb: GET
  • Description: Return the top IP addresses 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.

country

string

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/ips?startAt=${startAt}&endAt=${endAt}"

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

{
   "searchCount" : 16168,
   "userCount" : 4737,
   "lastSearchAt" : "2015-02-11T15:00:00.000Z",
   "topIPs" : [
      {
         "ip" : "19.44.30.155",
         "count" : 211
      },
      {
         "count" : 39,
         "ip" : "78.198.213.24"
      },
      {
         "ip" : "26.52.27.103",
         "count" : 33
      }
   ]
}

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error