Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

Algolia Cloud API V1

The API runs over HTTPS. It is accessed via a https://api${ZONE}.algolia.com domain. https://api.algolia.com is the default domain but only acts as a proxy to the correct one. You should use the target that we have sent to you when registered. We support automatic synchronization between different datacenters and we automaticaly route the trafic to the datacenter close to you.

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

Any API call that creates or updates an index is an asynchronous task. You can check the status of a task using the /1/indexes/{indexName}/task/{taskID} API.

Indexes Resources

GET

/1/indexes

Lists your indexes. Returns also a pendingTask flag per index that indicates if it has remaining task(s) running.

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{ 
    "items": [
        { "name": "contacts", "createdAt": "2013-01-18T15:33:13.556Z" },
        { "name": "notes", "createdAt": "2013-01-18T15:33:13.556Z" }
    ]
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

DELETE

/1/indexes/{indexName}

Deletes an existing index. Example: DELETE /1/indexes/contacts

Response

200 (OK)
{
    "deletedAt": "2013-01-18T15:33:13.556Z"
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${IndexName} does not exist" }

GET

/1/indexes/{indexName}{?page,hitsPerPage,query,callback,attributes,attributesToHighlight,minWordSizeForApprox1,minWordSizeForApprox2,getRankingInfo,aroundLatLng,aroundRadius,insideBoundingBox,tags}

Queries the index. If no query parameter is set, retrieves all objects.

All parameters are optional, here are their descriptions:

  • query: 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").
  • page and hitsPerPage parameters are used for pagination. hitsPerPage defaults to 10, but anything from 1 to 1000 is a valid value. page is zero-based and defaults to 0. Thus, to retrieve the 10th page with 100 hits per page you can set page=9&nbHitsPerPage=100.
  • attributes: the list of object attributes you want to retrieve (let you minimize the answer size). Attributes are separated with a comma (for example "name,address"). By default, all attributes are retrieved.
  • attributesToHighlight: the list of attributes you want to highlight according to the query. The syntax is the same as the attributes parameter syntax. If an attribute has no match for the query, the raw value is returned. By default all indexed attributes are highlighted. Numerical attributes cannot be 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, or "none" if none of the query terms were found.
  • attributesToSnippet: the 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"). By default no snippet is computed.
  • minWordSizeForApprox1: the minimum number of characters in a query word to accept one typo in this word. Defaults to 3.
  • minWordSizeForApprox2: the minimum number of characters in a query word to accept two typos in this word. Defaults to 7.
  • getRankingInfo: if set to 1, the result hits will contain ranking information in _rankingInfo attribute.
  • aroundLatLng: 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 and the precision for ranking with aroundPrecision (for example if you set aroundPrecision=100, two objects that are distant of less than 100m will be considered as identical for "geo" ranking parameter). At indexing, you should specify geoloc of an object with the _geoloc attribute (in the form "_geoloc":{"lat":48.853409, "lng":2.348800}}).
  • insideBoundingBox: 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}}).
  • tags: 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, tags=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"]} )
  • queryType: select how the query words are interpreted:
    • prefixAll: all query words are interpreted as prefixes (default behavior).
    • prefixLast: only the last word is interpreted as a prefix. This option is recommended if you have a lot of content to speedup the processing.
    • prefixNone: no query word is interpreted as a prefix. This option is not recommended.

All parameters' defaults can be changed with the /1/indexes/{indexName}/settings API.

Note: to allow geo-search (aroundLatLng and insideBoundingBox, entries must contains a specific attribute _geoloc, for example: "_geoloc":{ "lat":48.853409, "lng":2.348800}

Example: GET /1/indexes/contacts?page=9&nbHitsPerPage=50&getRankingInfo=1&query=jan

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{
    "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"} },
          "_rankingInfo": { nbTypos: 0}
        },
        { "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" } },
          "_rankingInfo": { nbTypos: 1}
        }
    ],
    "page":10,
    "nbPages":11,
    "nbHits":1892,
    "hitsPerPage:":50
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

POST

/1/indexes/{indexName}/query

Query an Index.

This method is the same as GET /1/indexes/{indexName} but is useful to avoid cross-origin resource sharing (CORS) queries when using the javascript client inside a web browser.

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

Response

201 (Created)
{
    "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"} }
        },
        { "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,
    "nbPages":1,
    "nbHits":2,
    "hitsPerPage:":50
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

POST

/1/indexes/*/queries

Query multiple Indexes.

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.

Response

201 (Created)
{
    "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,
            "nbPages":1,
            "nbHits":1,
            "hitsPerPage:":50
        },
        {   "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,
            "nbPages":1,
            "nbHits":1,
            "hitsPerPage:":50
        }
    ]
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

POST

/1/indexes/{indexName}

Adds one object in the index. Attributes' names are case-sensitive.

Example: POST /1/indexes/contacts

Response

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

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

GET

/1/indexes/{indexName}/{objectID}{?attributes}

Returns one object from the index.

attributes optional parameter that lets you specify the list of attributes you want to retrieve (Attributes' names are case sensitive).

Example: GET /1/indexes/contacts/6891Y2usk0

Response

200 (OK)
{ "name": "Betty Jane Mccamey", "company": "Vita Foods Inc.", "email": "betty@mccamey.com", "objectID": "6891Y2usk0" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} or {objectID} does not exist" }

PUT

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

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 POST /1/indexes/{indexName}/{objectID}/partial instead.

Example: PUT /1/indexes/contacts/6891

Response

200 (OK)
{ "updatedAt":"2013-01-18T15:33:13.556Z", "taskID": 680, "objectID": "6891Y2usk0"  }

Response

400 (Bad Request)
Content-Type: application/json; charset=utf-8
{ "message" : "Parse error at column 10, position 30" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} or ${objectID} does not exist" }

POST

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

Updates part of an object (if the object does not exist, it will be created)

Example: POST /1/indexes/contacts/6891/partial

Response

200 (OK)
{ "updatedAt":"2013-01-18T15:33:13.556Z", "taskID": 680, "objectID": "6891"  }

Response

400 (Bad Request)
Content-Type: application/json; charset=utf-8
{ "message" : "Parse error at column 10, position 30" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} or ${objectID} does not exist" }

DELETE

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

Deletes an existing object from the index.

Example: DELETE /1/indexes/contacts/6891Y2usk0

Response

200 (OK)
{ "taskID": 678, "deletedAt": "2013-01-18T15:33:13.556Z" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} or ${objectID} does not exist" }

POST

/1/indexes/{indexName}/batch

Batch write operations: To reduce the amount of time spent on network round trips, you can create, update, or delete several objects in one call, using the batch endpoint (all operations are done in the given order).

Algolia Search accepts two formats of batches: In the first format, you have just to give the HTTP method, the path of the command and the body. As you are doing a set of modification on the same index, the {indexName} component of path will be ignored.

{
  "requests": [ 
    { "method":"POST", 
      "path":"/1/indexes/...", 
      "body": { ... }
    }, ...]
}

In the second format, you can specify the action via a keyword in the list (addObj, deleteObj, updateObj, partialUpdateObj, delete, changeSettings) and the target object.

{ 
  "requests": [ 
    {"action":"addObject", 
     "body":{ ...}
    }, ...]
} 

This second format support six different actions:

  • addObject: Adds an object, equivalent to POST /1/indexes/{indexName}
  • updateObject: Replaces an object (objectID needs to be set), equivalent to PUT /1/indexes/{indexName}/{objectID}
  • partialUpdateObject: Replaces partially an object (objectID needs to be set), equivalent to POST /1/indexes/{indexName}/{objectID}/partial
  • deleteObject: Deletes an object (objectID needs to be set), equivalent to DELETE /1/indexes/{indexName}/{objectID}
  • delete: Deletes all index content, equivalent to DELETE /1/indexes/{indexName}
  • changeSettings: Changeq some index settings, equivalent to PUT /1/indexes/{indexName}/settings

Example: POST /1/indexes/contacts/batch

Response

200 (OK)
{ "taskID": 792,
  "objectIDs": ["6891Y2usk0", "ap78784310"]
}

Response

400 (Bad Request)
Content-Type: application/json; charset=utf-8
{ "message" : "Parse error at column 10, position 30" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

PUT

/1/indexes/{indexName}/settings

Changes index settings.

Settings include:

  • minWordSizeForApprox1: the minimum number of characters to accept one typo (default = 3).
  • minWordSizeForApprox2: the minimum number of characters to accept two typos (default = 7).
  • hitsPerPage: the number of hits per page (default = 10).
  • attributesToRetrieve: (array of strings) default list of attributes to retrieve in objects. By default all attributes are retrieved.
  • attributesToHighlight: (array of strings) default list of attributes to highlight. By default all indexed attributes are highlighted
  • attributesToSnippet: (array of strings) default list of attributes to snippet alongside the number of words to return (syntax is 'attributeName:nbWords'). By default no snippet is computed.
  • attributesToIndex: (array of strings) the list of fields you want to index. By default 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.
  • ranking: (array of string) controls the way results are sorted. We have four available criteria:
    • typo: sort according to number of typos,
    • geo: sort according to decreassing distance when performing a geo-location based search,
    • proximity: sort according to the proximity of query words in hits,
    • attribute: sort according to the order of attributes defined by attributesToIndex,
    • exact: sort according to the number of words that are matched identical to query word (and not as a prefix),
    • custom:sort according to a user defined formula set in customRanking attribute. The standard order is ["typo", "geo", "proximity", "attribute", "exact", "custom"].
  • customRanking: 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)"]
  • queryType: select how the query words are interpreted:
    • prefixAll: all query words are interpreted as prefixes (default behavior),
    • prefixLast: only the last word is interpreted as a prefix. This option is recommended if you have a lot of content to speedup the processing,
    • prefixNone: no query word is interpreted as a prefix. This option is not recommended.

Note: Changes to the "attributesToIndex", "ranking" and "customRanking" settings can take some time depending on the size of your index.

Example: POST /1/indexes/contacts/settings

Response

200 (OK)
Content-Type: application/json
{ "taskID": 879 }

Response

400 (Bad Request)
Content-Type: application/json; charset=utf-8
{ "message" : "Parse error at column 10, position 30" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

GET

/1/indexes/{indexName}/settings

Gets index settings.

Example: GET /1/indexes/contacts/settings

Response

200 (OK)
Content-Type: application/json
{ 
    "minWordSizefor1Typo": 3,
    "minWordSizefor2Typos": 7,
    "hitsPerPage": 50,
    "attributesToIndex": ["name", "email", "address"],
    "customRanking": ["desc(population)", "asc(name)"],
    "ranking": ["typo", "geo", "proximity", "userRanking"]
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "${indexName} does not exist" }

GET

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

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.

Example: GET /1/indexes/{indexName}/task/768

Response

200 (OK)
Content-Type: application/json
{ "status": "published"}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

Response

404 (Not Found)
Content-Type: application/json; charset=utf-8
{ "message": "Task does not exist" }

POST

/1/indexes/{indexName}/keys

Add a new key that can access to this index.

The X-Algolia-API-KEY used in the header must be the admin key.

The validity parameter allow to specify a validity for this key in seconds (key will automatically be removed after this period of time).

Here is the complete list of ACL that can be used for a key:

  • search: allow to search (https and http)
  • addObject: allows to add/update an object in the index (https only)
  • deleteObject : allows to delete an existing object (https only)
  • deleteIndex : allows to delete index content (https only)
  • settings : allows to get index settings (https only)
  • editSettings : allows to change index settings (https only)

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{ 
    "key": "107da8d0afc2d225ff9a7548caaf599f",
    "createdAt":"2013-01-18T15:33:13.556Z"
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

GET

/1/indexes/{indexName}/keys/{API-KEY}

Get ACL of an existing key associated to this index.

The X-Algolia-API-KEY used in the header must be the admin key.

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{
    "value":"107da8d0afc2d225ff9a7548caaf599f",
    "acl":["search", "addObject", "updateObject", "deleteObject", "deleteIndex"],
    "validity":100
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

DELETE

/1/indexes/{indexName}/keys/{API-KEY}

Delete an existing key associated to this index.

The X-Algolia-API-KEY used in the header must be the admin key.

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{
    "deletedAt":"2013-01-18T15:33:13.556Z"
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

API Keys Resources

GET

/1/keys

Lists keys that have access to all indexes.

You can also create API Keys associated to one index.

The X-Algolia-API-KEY used in the header must be the admin key).

The validity attribute contains the validity of key in second or 0 is the key does not expire.

Here is the complete list of ACL:

  • search: allow to search (https and http)
  • addObject: allows to add/update an object in the index (https only)
  • deleteObject : allows to delete an existing object (https only)
  • deleteIndex : allows to delete index content (https only)
  • settings : allows to get index settings (https only)
  • editSettings : allows to change index settings (https only)

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{ 
    "keys": [
        { "value": "ff96f7ec62b983bd87c4896a8e0b3508", "acl": ["search", "addObject" ], "validity":0 },
        { "value": "c6b158ccb1648651ccbee93ecc82966f", "acl": ["search"], "validity":0 }
    ]
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

POST

/1/keys

Add a new key that have access to all indexes.

The X-Algolia-API-KEY used in the header must be the admin key.

The validity parameter allow to specify a validity for this key in seconds (key will automatically be removed after this period of time).

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{ 
    "key": "107da8d0afc2d225ff9a7548caaf599f",
    "createdAt":"2013-01-18T15:33:13.556Z"
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

GET

/1/keys/{API-KEY}

Get ACL of a key that hava access to all indexes.

The X-Algolia-API-KEY used in the header must be the admin key.

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{
    "value":"107da8d0afc2d225ff9a7548caaf599f",
    "acl":["search", "addObject", "updateObject", "deleteObject", "deleteIndex"],
    "validity":100
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }

DELETE

/1/keys/{API-KEY}

Delete an existing key that have access to all indexes.

The X-Algolia-API-KEY used in the header must be the admin key.

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{
    "deletedAt":"2013-01-18T15:33:13.556Z"
}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{ "message": "Invalid Application-Id or API-Key" }