Tutorials > Search

Search REST API

Last updated 03 July 2017

Introduction

Important

We’ve developed API clients for the most common programming languages and platforms. These clients are advanced wrappers on top of our REST API itself and have been made in order to help you integrating the service within your apps: for both indexing and search. Everything that can be done using the REST API can be done using those clients.

Using our API clients is recommended to get the best from our service, they are all open-source and available on Github. You should only use our REST API to develop new API clients.

Click on one of the links below to access the client or integration’s code and documentation

Server side API Clients

PHP

Ruby

JavaScript

Python

Java

Scala

Client side API Clients

JavaScript

iOS

Android

Frameworks

Rails

Symfony

Django

Laravel

Note: SLA on both Indexing and Search are guaranteed only if you use those Official API clients. Learn more

Quick Reference

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

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

In order to guarantee a very high availability, we recommend to implement a retry strategy for all API calls on the following fallback hosts: {Application-ID}-1.algolianet.com, {Application-ID}-2.algolianet.com, {Application-ID}-3.algolianet.com. (Note that the domain is different because it is hosted on another DNS provider, for better redundancy.) It is best to shuffle (randomize) the list of fallback hosts at init time in order to ensure load balancing across clients. All our standard API clients implement this retry strategy.

The Application-ID variable can be found in your dashboard.

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

Indices API

Path	Verb	Method
/1/indexes	GET	List indices
/1/indexes/`{indexName}`/query	POST	Search an index
/1/indexes/`{indexName}`	GET	Search an index (alternative)
/1/indexes/*/queries	POST	Search multiple indices
/1/indexes/`{indexName}`	DELETE	Delete an index
/1/indexes/`{indexName}`/clear	POST	Clear 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
/1/indexes/`{indexName}`/`{objectID}`	GET	Retrieve an object
/1/indexes/*/objects	POST	Retrieve multiple objects
/1/indexes/`{indexName}`/`{objectID}`	DELETE	Delete an object
/1/indexes/`{indexName}`/batch	POST	Batch write operations
/1/indexes/*/batch	POST	Batch write operations (multiple indices)
/1/indexes/`{indexName}`/browse	POST	Browse all index content
/1/indexes/`{indexName}`/browse	GET	Browse all index content (alternative)
/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 a task's 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 indices)
/1/indexes/`{indexName}`/keys/`{key}`	GET	Retrieve an index-specific API key
/1/indexes/`{indexName}`/keys/`{key}`	DELETE	Delete an index-specific API key
/1/indexes/`{indexName}`/facets/`{facetName}`/query	POST	Search for facet values

Synonyms API

Path	Verb	Method
/1/indexes/`{indexName}`/synonyms/`{objectID}`	PUT	Create/update a synonym
/1/indexes/`{indexName}`/synonyms/batch	POST	Batch synonyms
/1/indexes/`{indexName}`/synonyms/`{objectID}`	GET	Get a synonym
/1/indexes/`{indexName}`/synonyms/clear	POST	Delete all synonyms
/1/indexes/`{indexName}`/synonyms/`{objectID}`	DELETE	Delete one synonyms set
/1/indexes/`{indexName}`/synonyms/search	POST	Search synonyms

Keys API

Path	Verb	Method
/1/keys	POST	Add an API key
/1/keys/`{key}`	PUT	Update an API key
/1/keys	GET	List API keys
/1/keys/`{key}`	GET	Get a API key
/1/keys/`{key}`	DELETE	Delete an API Key

Logs API

Path	Verb	Method
/1/logs	GET	Get latest logs

Format

The entire API uses JSON encoded as UTF-8.

The body of POST and PUT requests must be either a JSON object or a JSON array (depending on the particular endpoint) and their Content-Type header should be set to application/json; charset=UTF-8.

The body of responses is always a JSON object, and their content type is always application/json; charset=UTF-8.

Parameters

Unless otherwise stated, parameters must be passed:

in the URL’s query string for GET and DELETE requests;
in the request’s body for PUT and POST requests.

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

Arrays

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

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

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

Authentication

Basics

Authentication is done via HTTP headers:

X-Algolia-Application-Id identifies which application you are accessing;
X-Algolia-API-Key authenticates the endpoint (you can pass any API key created with the API).

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

Secured API keys

You may have a single index containing per-user data. In that case, you may wish to restrict access to the records of one particular user. Typically, all your records would be tagged with their associated user_id, and you would add a filter at query time like filters=user_id:${requested_id} to retrieve only what the querying user has access to.

Adding that filter directly from the frontend (browser or mobile application) will result in a security breach, because the user would be able to modify the filters you’ve set, e.g. by modifying the JavaScript code.

In order to keep sending the query from the browser (which is recommended for optimal latency) but only target secured records, you can generate secured API keys from your backend and use them in your frontend code. The backend will then automatically enforce the security filters contained in the key; the user will not be able to alter them.

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

Generate a secured API key

Secured API keys are generated by hashing (HMAC SHA-256) the following criteria together:

a private API key (can be any API Key that is not the admin API Key), used as the secret for HMAC SHA-256;
a URL-encoded list of query parameters defining the security filters.

The result of the hashing is concatenated to the URL-encoded query parameters, and this content is encoded in Base64 to generate the final secured API key.

All our backend API clients contain helpers to generate secured API keys. It is highly recommended that you use them instead of generating secured API keys manually.

Restriction parameters

The query parameters used during the generation of a secured API key can contain any of the default query parameters. In addition to these parameters, you can also specify parameters to restrict the indices or the TTL:

Name	Type	Description
`userToken`	string	An identifier that will be used by the rate-limit system to differentiate users behind the same IP.
`validUntil`	integer	Unix timestamp used to define the expiration date of the API key.
`restrictIndices`	comma-separated string list	List of index names allowed for the secured API key
`referers`	string array	Restrict this new API key to specific referers. If empty or blank, defaults to all referers. You can specify a pattern with either a leading or trailing wildcard (``), or both. For example, `https://algolia.com/` matches all referers starting with `https://algolia.com/` and `.algolia.com` matches all referers ending with `.algolia.com`. You can combine both, as in `algolia.com*` to allow the domain `algolia.com`.
`restrictSources`	string	IPv4 network allowed for the secured API key

Error handling

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

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

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

Indices API

Edit this method

List indices

Path	/1/indexes
HTTP Verb	GET

Description

List existing indexes.

Parameters

page

type	integer
mandatory	no
default	`null`
description	Requested page (zero-based). When specified, will retrieve a specific page; the page size is implicitly set to 100. When `null`, will retrieve all indices (no pagination).

Edit this example

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"

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,
            "dataSize": 224152664,
            "fileSize": 269450853,
            "lastBuildTimeS": 0,
            "numberOfPendingTask": 0,
            "pendingTask": false
        }
    ],
    "nbPages": 1
}

Edit this method

Search an index

Path	/1/indexes/`{indexName}`/query
HTTP Verb	POST

Description

Return objects that match the query.

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

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

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

Parameters

params

type	URL-encoded string
mandatory	no
default	`""` (no search parameters)
description	Search parameters

Edit this example

Example

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

Errors

Error Code	Reason
400	Bad request argument
404	Index does not exist

Edit this method

Search an index (alternative)

Path	/1/indexes/`{indexName}`
HTTP Verb	GET

Description

You can also query an index with a GET request.

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

Parameters

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

Edit this example

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"

Errors

Error Code	Reason
400	Bad request argument
404	Index does not exist

Edit this method

Search multiple indices

Path	/1/indexes/*/queries
HTTP Verb	POST

Description

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

Parameters

requests

type array of objects

mandatory yes

description

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

Each query is described by the following attributes:

indexName: index targeted by the query;
params: URL-encoded list of search parameters.

strategy

type	string
mandatory	no
default	`"none"`
description	Allows optimizing execution of the queries by potentially skipping some of them. The following values are allowed: `none`: Execute all queries. `stopIfEnoughMatches`: Execute queries one by one, but stop as soon as one query matches at least as many hits as its `hitsPerPage` parameter. More formally: query N is executed only if all of queries 0 through N-1 had strictly less hits than their requested number of hits per page. Let’s illustrate `stopIfEnoughMatches`: Let’s say you send 3 queries with `hitsPerPage` set to 50, 5 and 20 (respectively). There are different possible scenarios: Run query #1 50+ hits are found: skip to step 4 otherwise: continue with query #2 Run query #2 5+ hits where found: skip to step 4 otherwise: continue with query #3 Run query #3 This is the last query, so we don’t care about its outcome Return results Return actual results for queries that were processed Return empty hits for queries that were skipped, along with a `processed` attribute set to `false`

Edit this example

Example

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

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

{
  "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
404	Index does not exist

Edit this method

Delete an index

Path	/1/indexes/`{indexName}`
HTTP Verb	DELETE

Description

Delete an existing index.

Edit this example

Example

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
}

Edit this method

Clear an index

Path	/1/indexes/`{indexName}`/clear
HTTP Verb	POST

Description

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

Edit this example

Example

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

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

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

Errors

Error Code	Reason
400	Invalid `indexName`

Edit this method

Add an object without ID

Path	/1/indexes/`{indexName}`
HTTP Verb	POST

Description

Add an object to the index, automatically assigning it an object ID.

Edit this example

Example

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

Upon success, the response is 201 Created, with the objectID attribute containing the ID assigned to the added object.

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

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

Errors

Error Code	Reason
400	Invalid `indexName` or JSON

Edit this method

Add/update an object by ID

Path	/1/indexes/`{indexName}`/`{objectID}`
HTTP Verb	PUT

Description

Add or replace an object with a given object ID. If the object does not exist, it will be created. If it already exists, it will be replaced.

Be careful: when an object already exists for the specified object ID, the whole object is replaced: existing attributes that are not replaced are deleted.

If you want to update only part of an object, use a partial update instead.

Edit this example

Example

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

Upon success, the response is 200 OK.

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

Errors

Error Code	Reason
400	Invalid `indexName` or JSON

Edit this method

Partially update an object

Path	/1/indexes/`{indexName}`/`{objectID}`/partial
HTTP Verb	POST

Description

Update part of an object. If the object does not already exist, it will be created (unless createIfNotExists is specified as false).

You can pass any first-level attribute you want to add or replace in the record.

Nested attributes cannot be individually updated. If you specify a nested attribute, it will be treated as a replacement of its first-level ancestor.

In addition, there are 5 different operations supported to update an attribute without pushing its entire value:

Increment: Increment a numeric-based attribute
Decrement: Decrement a numeric-based attribute
Add: Append a number or string element to an array-based attribute
Remove: Remove all matching number or string elements from an array-based attribute
AddUnique: Add a number or string element to an array-based attribute only if it’s not already present

You specify an operation by providing an object with two attributes:

_operation: the operation to apply on the attribute (see above);
value: the right-hand side argument to the operation (e.g. increment/decrement step, or value to add/remove).

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

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

Parameters

createIfNotExists

type	boolean
mandatory	no
default	`true`
description	When true, a partial update on a nonexistent object will create the object, assuming an empty object as the basis. When false, a partial update on a nonexistent object will be ignored.

Edit this example

Example

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

Upon success, the response is 200 OK.

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

Errors

Error Code	Reason
400	Invalid `indexName` or JSON

Edit this method

Retrieve an object

Path	/1/indexes/`{indexName}`/`{objectID}`
HTTP Verb	GET

Description

Retrieve one object from the index.

Parameters

attributesToRetrieve

type	array of strings
mandatory	no
default	all retrievable attributes
formerly known as	`attributes`
description	List of attributes to retrieve. If not specified, all retrievable attributes are returned. `objectID` is always retrieved, even when not specified. Attributes listed in `unretrievableAttributes` will not be retrieved even if requested, unless the request is authenticated with the admin API key.

Edit this example

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/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
404	Index or object does not exist

Edit this method

Retrieve multiple objects

Path	/1/indexes/*/objects
HTTP Verb	POST

Description

Retrieve multiple objects, potentially from different indices, in a single API call.

The POST body must contain:

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

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

Edit this example

Example

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": "betty@mccamey.com",
      "objectID": "obj1"
    },
    {
      "name": "Stacey Blow",
      "email": "stacey@blow.com"
      "objectID": "obj2"
    }
  ]
}

Errors

Error Code	Reason
400	Bad request argument
404	Index does not exist

Edit this method

Delete an object

Path	/1/indexes/`{indexName}`/`{objectID}`
HTTP Verb	DELETE

Description

Delete an existing object from an index.

Edit this example

Example

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

Upon success, the response is 200 OK.

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

Edit this method

Batch write operations

Path	/1/indexes/`{indexName}`/batch
HTTP Verb	POST

Description

Perform multiple write operations in a single API call.

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

The following actions are supported:

addObject: Add an object. Equivalent to Add an object without ID.
updateObject: Add or replace an existing object. You must set the objectID attribute to indicate the object to update. Equivalent to Add/update an object by ID.
partialUpdateObject: Partially update an object. You must set the objectID attribute to indicate the object to update. Equivalent to Partially update an object.
partialUpdateObjectNoCreate: Same as partialUpdateObject, except that the object is not created if the object designed by objectID does not exist.
deleteObject: Delete an object. You must set the objectID attribute to indicate the object to delete. Equivalent to Delete an object.
delete: Delete the index. Equivalent to Delete an index.
clear: Remove the index’s content, but keep settings and index-specific API keys untouched. Equivalent to Clear an index.

Parameters

requests

type array of objects

mandatory yes

description

List of operations to batch.

Each operation is described by:

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

Edit this example

Example

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

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

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

Upon success, the response is 200 OK.

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

A typical response is:

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

Edit this method

Batch write operations (multiple indices)

Path	/1/indexes/*/batch
HTTP Verb	POST

Description

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

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

Parameters

requests

type array of objects

mandatory yes

description

List of operations to batch.

Each operation is described by:

indexName (string): name of the index targeted by this operation
action (string): type of operation
body (object): arguments to the operation (depends on the type of the operation)

Edit this example

Example

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

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

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

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

Upon success, the response is 200 OK.

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

A typical response is:

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

Errors

Error Code	Reason
400	Invalid JSON

Edit this method

Browse all index content

Path	/1/indexes/`{indexName}`/browse
HTTP Verb	POST

Description

This method allows you to retrieve all index content (for backup, SEO or analytics purpose). It can retrieve up to 1,000 records per call and supports full text search and filters. You can use the same query parameters as for a search query.

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

the distinct query parameter (used for grouping or de-duplication)
sorting by typos, proximity, words or geo distance (only the custom ranking is applied)

The first call may specify search parameters via the params parameter.

When there is more content to be browsed, the response contains a cursor field. This cursor has to be passed to the subsequent call to browse in order to get the next page of results. When the end of the index has been reached, the cursor field is absent from the response.

Parameters

params

type	URL-encoded string
mandatory	no
default	`""` (no search parameters)
description	Search parameters used to filter the index content. If not specified, all objects are returned. Can only be used on the first call.

cursor

type	string
mandatory	yes (on subsequent calls)
description	Cursor indicating the location to resume browsing from. Must match the value returned by the previous call.

Edit this example

Example

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{"params": "filters=price%3C500"}' \
    "https://${APPLICATION_ID}-dsn.algolia.net/1/indexes/contacts/browse"

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

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

Errors

Error Code	Reason
404	Index does not exist

Edit this method

Browse all index content (alternative)

Path	/1/indexes/`{indexName}`/browse
HTTP Verb	GET

Description

This is an alternative method to Browse all index content, allowing you to specify parameters via GET instead of POST.

Edit this example

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/contacts/browse?params=filters%3Dprice%3C500"

Edit this method

Get index settings

Path	/1/indexes/`{indexName}`/settings
HTTP Verb	GET

Description

Retrieve index settings.

You can find the list of settings in the Settings Parameters section.

Edit this example

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/contacts/settings"

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

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

Errors

Error Code	Reason
403	Index does not exist

Edit this method

Change index settings

Path	/1/indexes/`{indexName}`/settings
HTTP Verb	PUT

Description

Update some index settings.

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

The supported settings are documented in the Settings Parameters section.

Parameters

forwardToReplicas

type	boolean
mandatory	no
default	`false`
formerly known as	`forwardToSlaves`
description	(URL parameter) If this parameter is added to the URL, the change is also propagated to replicas of this index.

Edit this example

Example

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

Upon success, the response is 200 OK.

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

Errors

Error Code	Reason
400	Invalid JSON

Edit this method

Copy/move an index

Path	/1/indexes/`{indexName}`/operation
HTTP Verb	POST

Description

Copy or move an existing index.

If the destination index already exists, its index-specific API keys will be preserved, and the source index-specific API keys will be added.

Parameters

operation

type	string
mandatory	yes
description	Type of operation to perform: `move` or `copy`.

destination

type	string
mandatory	yes
description	Name of the destination index.

Edit this example

Example

Here is an example to copy index1 to 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"

Upon success, the response is 200 OK.

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

Errors

Error Code	Reason
400	Invalid JSON

Edit this method

Get a task’s status

Path	/1/indexes/`{indexName}`/task/`{taskID}`
HTTP Verb	GET

Description

Check the current status of a given task.

The response includes two fields:

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

Edit this example

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/contacts/task/13235"

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

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

Edit this method

Add an index-specific API key

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

Description

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

The request must be authenticated by the admin API key.

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

Parameters

acl

type	array of strings
mandatory	no
default	`[]` (no rights)
description	List of rights for the newly created key. The following rights can be used: `search`: allows to search the index `browse`: allows to retrieve all index content via the browse API `addObject`: allows to add/update an object in the index (copy/move index are also allowed with this right) `deleteObject`: allows to delete objects from the index `deleteIndex`: allows to delete or clear index content `settings`: allows to get index settings `editSettings`: allows to change index settings `analytics`: allows to retrieve the analytics through the Analytics API `listIndexes`: allows to list all accessible indices

description

type	string
mandatory	no
default	`""`
description	A comment used to identify a key more easily in the dashboard. It is not interpreted by the API.

maxHitsPerQuery

type	integer
mandatory	no
default	0 (unlimited)
description	Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced. This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.

maxQueriesPerIPPerHour

type	integer
mandatory	no
default	0 (no rate limit)
description	Maximum number of API calls per hour allowed from a given IP address. Each time an API call is performed with this key, a check is performed. If the IP at the origin of the call did more than the specified number of calls within the last hour, a 429 (Too Many Requests) status code is returned. This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index. If you are proxying the query through your servers, you must use the admin API key and set the `X-Forwarded-For` HTTP header with the client IP and the `X-Forwarded-API-Key` with the API key having rate limits.

queryParameters

type	URL-encoded query string
mandatory	no
default	`""` (no search parameters)
description	Force some query parameters to be applied for each query made with this API key. You can force all query parameters like: `typoTolerance=strict&ignorePlurals=false&filters=rights:public`.

referers

type	array of strings
mandatory	no
default	`[]` (all referers allowed)
description	Restrict this new API key to specific referers. If empty or blank, defaults to all referers. You can specify a pattern with either a leading or trailing wildcard (``), or both. For example, `https://algolia.com/` matches all referers starting with `https://algolia.com/` and `.algolia.com` matches all referers ending with `.algolia.com`. You can combine both, as in `algolia.com*` to allow the domain `algolia.com`.

validity

type	integer
mandatory	no
default	0 (no validity limit)
description	Validity limit for this key in seconds. The key will automatically be removed after this period of time.

Edit this example

Example

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

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

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

Errors

Error Code	Reason
400	Invalid JSON

Edit this method

Update an index-specific API key

Path	/1/indexes/`{indexName}`/keys/`{key}`
HTTP Verb	PUT

Description

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

The request must be authenticated by the admin API key.

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

Parameters

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

Edit this example

Example

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

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

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

Errors

Error Code	Reason
400	Invalid JSON

Edit this method

List index-specific API keys

Path	/1/indexes/`{indexName}`/keys
HTTP Verb	GET

Description

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

The request must be authenticated by the admin API key.

Edit this example

Example

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

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

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

Errors

Error Code	Reason
404	Index does not exist

Edit this method

List index-specific API keys (for all indices)

Path	/1/indexes/*/keys
HTTP Verb	GET

Description

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

The request must be authenticated by the admin API key.

Edit this example

Example

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

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

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

Edit this method

Retrieve an index-specific API key

Path	/1/indexes/`{indexName}`/keys/`{key}`
HTTP Verb	GET

Description

Retrieve the details of an index-specific API key.

The request must be authenticated by the admin API key.

Edit this example

Example

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

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

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

Edit this method

Delete an index-specific API key

Path	/1/indexes/`{indexName}`/keys/`{key}`
HTTP Verb	DELETE

Description

Delete an index-specific API key.

The request must be authenticated by the admin API key.

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

Edit this example

Example

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

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

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

Edit this method

Path	/1/indexes/`{indexName}`/facets/`{facetName}`/query
HTTP Verb	POST

Description

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

Pagination is not supported. The page and hitsPerPage parameters will be ignored. By default, maximum 10 values are returned. This can be adjusted via maxFacetHits.

Parameters

type	URL-encoded query string
mandatory	no
default	`""`
description	Search parameters. You may use this parameter to specify parameters specific to this endpoint. You may also specify any number of other regular search parameters. They will apply to objects in the index.

type	string
mandatory	no
default	`""`
description	Text to search inside the facet’s values.

type	integer
mandatory	no
default	10
description	Maximum number of facet hits to return. For performance reasons, the maximum allowed number of returned values is 100. Any value outside the range [1, 100] will be rejected.

Edit this example

Example

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

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

The response body contains the following fields:

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

Values are sorting by decreasing frequency.

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

Errors

Error Code	Reason
400	Attribute `facetName` is not in `attributesForFaceting`, or not with the `searchable()` specifier
404	Index `indexName` does not exist

Search Parameters

query
search The text to search for in the index.

attributesToRetrieve `settings` `search`	List of object attributes you want to retrieve.
restrictSearchableAttributes `search`	List of attributes to be considered for textual search.

filters `search`	Filter the query with numeric, facet and/or tag filters.
facets `search`	Facets to retrieve.
maxValuesPerFacet `settings` `search`	Maximum number of facet values returned for each facet.
facetFilters `search`	Filter hits by facet value.
facetingAfterDistinct `search`	Force faceting to be applied after de-duplication.

attributesToHighlight `settings` `search`	List of attributes to highlight.
attributesToSnippet `settings` `search`	List of attributes to snippet, with an optional maximum number of words to snippet.
highlightPreTag `settings` `search`	String inserted before highlighted parts in highlight and snippet results.
highlightPostTag `settings` `search`	String inserted after highlighted parts in highlight and snippet results.
snippetEllipsisText `settings` `search`	String used as an ellipsis indicator when a snippet is truncated.
restrictHighlightAndSnippetArrays `settings` `search`	Restrict arrays in highlight and snippet results to items that matched the query.

page `search`	Number of the page to retrieve.
hitsPerPage `settings` `search`	Maximum number of hits per page.
offset `search`	Offset of the first hit to return (zero-based).
length `search`	Maximum number of hits to return. (1000 is the maximum)

minWordSizefor1Typo `settings` `search`	Minimum number of characters a word in the query string must contain to accept matches with one typo.
minWordSizefor2Typos `settings` `search`	Minimum number of characters a word in the query string must contain to accept matches with two typos.
typoTolerance `settings` `search`	Controls whether typo tolerance is enabled and how it is applied:
allowTyposOnNumericTokens `settings` `search`	Whether to allow typos on numbers ("numeric tokens") in the query string.
ignorePlurals `settings` `search`	Consider singular and plurals forms a match without typo.
disableTypoToleranceOnAttributes `settings` `search`	List of attributes on which you want to disable typo tolerance

aroundLatLng `search`	Search for entries around a given location.
aroundLatLngViaIP `search`	Search for entries around a given location automatically computed from the requester's IP address.
aroundRadius `search`	Maximum radius for geo search (in meters).
aroundPrecision `search`	Precision of geo search (in meters).
minimumAroundRadius `search`	Minimum radius (in meters) used for a geo search when <%= parameter_link('aroundRadius') -%> is not set.
insideBoundingBox `search`	Search inside a rectangular area (in geo coordinates).
insidePolygon `search`	Search inside a polygon (in geo coordinates).

queryType `search` `settings`	Controls if and how query words are interpreted as prefixes.
removeWordsIfNoResults `settings` `search`	Selects a strategy to remove words from the query when it doesn't match any hits.
advancedSyntax `settings` `search`	Enables the advanced query syntax.
optionalWords `settings` `search`	List of words that should be considered as optional when found in the query.
removeStopWords `settings` `search`	Remove stop words from the query before executing it.
disableExactOnAttributes `settings` `search`	List of attributes on which you want to disable computation of the `exact` ranking criterion
exactOnSingleWordQuery `settings` `search`	Controls how the `exact` ranking criterion is computed when the query contains only one word.
alternativesAsExact `setting` `search`	List of alternatives that should be considered an exact match by the `exact` ranking criterion.

distinct `settings` `search`	Controls de-duplication of results.
getRankingInfo `search`	Enables detailed ranking information.
numericFilters `search`	Filter hits based on values of numeric attributes.
tagFilters `search`	Filter hits by tags.
analytics `search`	Whether the current query will be taken into account in the Analytics.
analyticsTags `search`	List of tags to apply to the query in the Analytics.
synonyms `search`	Whether to take into account synonyms defined for the targeted index.
replaceSynonymsInHighlight `settings` `search`	Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.
minProximity `settings` `search`	Precision of the `proximity` ranking criterion.
responseFields `settings` `search`	Choose which fields the response will contain. Applies to search and browse queries.
maxFacetHits `settings` `search`	Maximum number of facet hits to return during a search for facet values.
percentileComputation `search`	Whether to include the query in processing time percentile computation.

Settings Parameters

searchableAttributes `settings`	List of attributes eligible for textual search.
attributesForFaceting `settings`	List of attributes you want to use for faceting.
unretrievableAttributes `settings`	List of attributes that cannot be retrieved at query time.
attributesToRetrieve `settings` `search`	List of object attributes you want to retrieve.

ranking `settings`	Controls the way results are sorted.
customRanking `settings`	Specifies the `custom` ranking criterion.
replicas `settings`	List of indices to which you want to replicate all write operations.

maxValuesPerFacet
settings search Maximum number of facet values returned for each facet.

attributesToHighlight `settings` `search`	List of attributes to highlight.
attributesToSnippet `settings` `search`	List of attributes to snippet, with an optional maximum number of words to snippet.
highlightPreTag `settings` `search`	String inserted before highlighted parts in highlight and snippet results.
highlightPostTag `settings` `search`	String inserted after highlighted parts in highlight and snippet results.
snippetEllipsisText `settings` `search`	String used as an ellipsis indicator when a snippet is truncated.
restrictHighlightAndSnippetArrays `settings` `search`	Restrict arrays in highlight and snippet results to items that matched the query.

hitsPerPage `settings` `search`	Maximum number of hits per page.
paginationLimitedTo `settings`	Maximum number of hits accessible via pagination.

minWordSizefor1Typo `settings` `search`	Minimum number of characters a word in the query string must contain to accept matches with one typo.
minWordSizefor2Typos `settings` `search`	Minimum number of characters a word in the query string must contain to accept matches with two typos.
typoTolerance `settings` `search`	Controls whether typo tolerance is enabled and how it is applied:
allowTyposOnNumericTokens `settings` `search`	Whether to allow typos on numbers ("numeric tokens") in the query string.
ignorePlurals `settings` `search`	Consider singular and plurals forms a match without typo.
disableTypoToleranceOnAttributes `settings` `search`	List of attributes on which you want to disable typo tolerance
disableTypoToleranceOnWords `settings`	List of words on which typo tolerance will be disabled.
separatorsToIndex `settings`	Separators (punctuation characters) to index.

queryType `search` `settings`	Controls if and how query words are interpreted as prefixes.
removeWordsIfNoResults `settings` `search`	Selects a strategy to remove words from the query when it doesn't match any hits.
advancedSyntax `settings` `search`	Enables the advanced query syntax.
optionalWords `settings` `search`	List of words that should be considered as optional when found in the query.
removeStopWords `settings` `search`	Remove stop words from the query before executing it.
disablePrefixOnAttributes `settings`	List of attributes on which you want to disable prefix matching
disableExactOnAttributes `settings` `search`	List of attributes on which you want to disable computation of the `exact` ranking criterion
exactOnSingleWordQuery `settings` `search`	Controls how the `exact` ranking criterion is computed when the query contains only one word.

numericAttributesForFiltering `settings`	List of numeric attributes that can be used as numerical filters.
allowCompressionOfIntegerArray `settings`	Enables compression of large integer arrays.

attributeForDistinct `settings`	Name of the de-duplication attribute for the <%= parameter_link('distinct') -%> feature.
distinct `settings` `search`	Controls de-duplication of results.
replaceSynonymsInHighlight `settings` `search`	Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.
minProximity `settings` `search`	Precision of the `proximity` ranking criterion.
responseFields `settings` `search`	Choose which fields the response will contain. Applies to search and browse queries.
maxFacetHits `settings` `search`	Maximum number of facet hits to return during a search for facet values.

Synonyms API

Synonyms are used to provide the engine with words or expressions that should be considered equal with respect to textual relevance.

Our synonyms API has been designed to manage as easily as possible a large set of synonyms for an index and its replicas. This API allows you to search, create and delete synonyms in the same way you would handle index records.

Backward compatibility

Synonyms were originally set via the index settings, and a Get settings call would return all synonyms as part of the settings JSON data.

This behavior has been kept to maintain backward compatibility. If you do not want synonyms to be included in your settings, add getVersion=2 to your request as a query parameter:

GET /1/indexes/{indexName}/settings?getVersion=2

Until you switch to this new Synonyms API, you can still manage your synonyms via the index settings.

Edit this method

Create/update a synonym

Path	/1/indexes/`{indexName}`/synonyms/`{objectID}`
HTTP Verb	PUT

Description

Create a new synonym object or update the existing synonym object with the given object ID.

objectID must be a unique value that identifies the synonym object. If there is already a synonym object with this objectID in your index, it will be replaced.

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

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

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

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

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

Example:

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

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

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

Example:

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

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

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

Example:

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

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

placeholder (string): Token to be put inside records.
replacements (array of strings): List of query words that will match the token.

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

For more information on synonyms, please read our Synonyms guide.

Parameters

forwardToReplicas

type	boolean
mandatory	no
default	`false`
description	(URL parameter) Replicate the new/updated synonym set to all replica indices.

Edit this example

Example

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

Edit this method

Batch synonyms

Path	/1/indexes/`{indexName}`/synonyms/batch
HTTP Verb	POST

Description

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

You should always use replaceExistingSynonyms to atomically replace all your synonyms on a production index. This is the only way to ensure your index always has a list of synonyms to use during the indexing of the new list.

The POST body must be a JSON array of synonym objects. The syntax of each object is the same as in Create/update a synonym. Example:

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

Parameters

forwardToReplicas

type	boolean
mandatory	no
default	`false`
description	(URL parameter) Replicate the new/updated synonyms to all replica indices.

replaceExistingSynonyms

type	boolean
mandatory	no
default	`false`
description	(URL parameter) Replace all synonyms of the index with the ones sent with this request.

Edit this example

Example

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

Edit this method

Get a synonym

Path	/1/indexes/`{indexName}`/synonyms/`{objectID}`
HTTP Verb	GET

Description

Fetch a synonym object identified by its objectID.

Edit this example

Example

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

Upon success, the response is 200 OK and contains the synonym object:

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

If the synonyms could not be found, the response is 404 Not Found:

{"message":"Synonym set does not exist","status":404}

Edit this method

Delete all synonyms

Path	/1/indexes/`{indexName}`/synonyms/clear
HTTP Verb	POST

Description

Delete all synonyms from the index.

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

Parameters

forwardToReplicas

type	boolean
mandatory	no
default	`false`
description	(URL parameter) Clear synonyms on the replica indices as well.

Edit this example

Example

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

Edit this method

Delete one synonyms set

Path	/1/indexes/`{indexName}`/synonyms/`{objectID}`
HTTP Verb	DELETE

Description

Delete a single synonyms set, identified by the given objectID

Parameters

forwardToReplicas

type	boolean
mandatory	no
default	false
description	(URL parameter) delete the synonyms set in all replica indices as well

Edit this example

Example

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

Edit this method

Search synonyms

Path	/1/indexes/`{indexName}`/synonyms/search
HTTP Verb	POST

Description

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

Parameters

query

type	string
mandatory	no
default	`""`
description	Search for specific synonyms matching this string. Use an empty string (default) to browse all synonyms.

type

type	string
mandatory	no
default	`""`
description	Only search for specific types of synonyms. Multiple types can be specified using a comma-separated list. Possible values are: `synonym`, `onewaysynonym`, `altcorrection1`, `altcorrection2`, `placeholder`.

page

type	integer
mandatory	no
default	0
description	Number of the page to retrieve (zero-based).

hitsPerPage

type	integer
mandatory	no
default	100
description	Maximum number of synonym objects to retrieve.

Edit this example

Example

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary '{ "query": "iphone", "type": "synonym,onewaysynonym", "page": 0, "hitsPerPage": 10 }' \
     "https://${APPLICATION_ID}.algolia.net/1/indexes/{indexName}/synonyms/search"

Keys API

Edit this method

Add an API key

Path	/1/keys
HTTP Verb	POST

Description

Create a new API key.

The request must be authenticated by the admin API key.

Parameters

acl

type	array of strings
mandatory	no
default	`[]` (no rights)
description	List of rights for the newly created key. The following rights can be used: `search`: allows to search the index `browse`: allows to retrieve all index content via the browse API `addObject`: allows to add/update an object in the index (copy/move index are also allowed with this right) `deleteObject`: allows to delete objects from the index `deleteIndex`: allows to delete or clear index content `settings`: allows to get index settings `editSettings`: allows to change index settings `analytics`: allows to retrieve the analytics through the Analytics API `listIndexes`: allows to list all accessible indices

description

type	string
mandatory	no
default	`""`
description	A comment used to identify a key more easily in the dashboard. It is not interpreted by the API.

indexes

type	array of strings
mandatory	no
default	`[]` (all indices allowed)
description	Restrict this new API key to a list of indices or index patterns. If the list is empty, all indices are allowed. You may specify either an exact index name, or a pattern with a leading and/or a trailing wildcard (``). For example: `dev_` matches all indices starting with `dev_` `_dev` matches all indices ending with `_dev` `_products_*` matches all indices containing `_products_` This option is useful if you want to isolate your development and production environments: you can have one API key targeting development indices and another one targeting production indices.

maxHitsPerQuery

type	integer
mandatory	no
default	0 (unlimited)
description	Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced. This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.

maxQueriesPerIPPerHour

type	integer
mandatory	no
default	0 (no rate limit)
description	Maximum number of API calls per hour allowed from a given IP address. Each time an API call is performed with this key, a check is performed. If the IP at the origin of the call did more than the specified number of calls within the last hour, a 429 (Too Many Requests) status code is returned. This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index. If you are proxying the query through your servers, you must use the admin API key and set the `X-Forwarded-For` HTTP header with the client IP and the `X-Forwarded-API-Key` with the API key having rate limits.

queryParameters

type	URL-encoded query string
mandatory	no
default	`""` (no search parameters)
description	Force some query parameters to be applied for each query made with this API key. You can force all query parameters like: `typoTolerance=strict&ignorePlurals=false&filters=rights:public`.

referers

type	array of strings
mandatory	no
default	`[]` (all referers allowed)
description	Restrict this new API key to specific referers. If empty or blank, defaults to all referers. You can specify a pattern with either a leading or trailing wildcard (``), or both. For example, `https://algolia.com/` matches all referers starting with `https://algolia.com/` and `.algolia.com` matches all referers ending with `.algolia.com`. You can combine both, as in `algolia.com*` to allow the domain `algolia.com`.

validity

type	integer
mandatory	no
default	0 (no validity limit)
description	Validity limit for this key in seconds. The key will automatically be removed after this period of time.

Edit this example

Example

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

Edit this method

Update an API key

Path	/1/keys/`{key}`
HTTP Verb	PUT

Description

Update an API key.

The request must be authenticated by the admin API key.

Parameters

This method accepts the same parameters as the Add an API Key method.

Edit this example

Example

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

Edit this method

List API keys

Path	/1/keys
HTTP Verb	GET

Description

List API keys, along with their associated rights.

The request must be authenticated by the admin API key.

Edit this example

Example

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

Edit this method

Get a API key

Path	/1/keys/`{key}`
HTTP Verb	GET

Description

Retrieve the details of a API key.

The request must be authenticated by the admin API key.

Edit this example

Example

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
}

Edit this method

Delete an API Key

Path	/1/keys/`{key}`
HTTP Verb	DELETE

Description

Delete an API key.

The request must be authenticated by the admin API key.

Edit this example

Example

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

Logs API

Edit this method

Get latest logs

Path	/1/logs
HTTP Verb	GET

Description

Return the lastest log entries.

The request must be authenticated by the admin API key.

This API is counted in your operation quota but is not logged.

Parameters

offset

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

length

type	integer
mandatory	no
default	10
description	Maximum number of entries to retrieve. Maximum allowed value: 1000.

indexName

type	string
mandatory	no
default	`null`
description	Index for which log entries should be retrieved. When omitted, log entries are retrieved across all indices.

type

type	string
mandatory	no
default	`"all"`
description	Type of log entries to retrieve. When omitted, all log entries are retrieved. This parameter is useful for debugging, especially when it is difficult to locate errors among many API calls: `all`: retrieve all logs `query`: retrieve only search queries `build`: retrieve only build operations `error`: retrieve only errors

Edit this example

Example

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

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

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

Did you find this page helpful?

We're always looking for advice to help improve our documentation!
Please let us know what's working (or what's not!).
We're constantly iterating thanks to the feedback we receive.