Algolia Search API
Client libraries Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps. The official API clients are covered by…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Client libraries
Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps.
The official API clients are covered by Algolia's Service Level Agreement.
For more information, see Algolia's ecosystem.
Base URLs
Base URLs for the Search API:
https://{APPLICATION_ID}.algolia.nethttps://{APPLICATION_ID}-dsn.algolia.net.
If your subscription includes a Distributed Search Network,
this ensures that requests are sent to servers closest to users.
Both URLs provide high availability by distributing requests with load balancing.
All requests must use HTTPS.
Retry strategy
To guarantee high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks:
https://{APPLICATION_ID}-1.algolianet.comhttps://{APPLICATION_ID}-2.algolianet.comhttps://{APPLICATION_ID}-3.algolianet.com
These URLs use a different DNS provider than the primary URLs.
Randomize this list to ensure an even load across the three servers.
All Algolia API clients implement this retry strategy.
Authentication
Add these headers to authenticate requests:
x-algolia-application-id. Your Algolia application ID.x-algolia-api-key. An API key with the necessary permissions to make the request.
The required access control list (ACL) to make a request is listed in each endpoint's reference.
You can find your application ID and API key in the Algolia dashboard.
Request format
Depending on the endpoint, request bodies are either JSON objects or arrays of JSON objects.
Parameters
Parameters are passed as query parameters for GET and DELETE requests,
and in the request body for POST and PUT requests.
Query parameters must be URL-encoded.
Non-ASCII characters must be UTF-8 encoded.
Plus characters (+) are interpreted as spaces.
Arrays as query parameters must be one of:
- A comma-separated string:
attributesToRetrieve=title,description - A URL-encoded JSON array:
attributesToRetrieve=%5B%22title%22,%22description%22%D
Response status and errors
The Search API returns JSON responses.
Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
Successful responses return 2xx statuses. Client errors return 4xx statuses. Server errors return 5xx statuses.
Error responses have a message property with more information.
Request identifiers
Every response includes a Correlation-ID header that identifies the request in Algolia's logs.
When contacting the Algolia support team about a specific request, include this identifier in your ticket.
To tag requests with your own identifier, send a Request-ID header with exactly 11 alphanumeric characters.
Clusters that support it embed the identifier at the end of the Correlation-ID,
so all attempts of a retried operation can be found by searching for those characters.
Headers that don't match the expected format are ignored.
Don't use the Correlation-ID as a unique key: retried requests may receive the same identifier.
Version
The current version of the Search API is version 1, indicated by the /1/ in each endpoint's URL.
Endpoints 78
search
- GETSend requests to the Algolia REST API
/:pathThis method lets you send requests to the Algolia REST API. - PUTSend requests to the Algolia REST API
/:pathThis method lets you send requests to the Algolia REST API. - POSTSend requests to the Algolia REST API
/:pathThis method lets you send requests to the Algolia REST API. - DELETESend requests to the Algolia REST API
/:pathThis method lets you send requests to the Algolia REST API. - POSTSearch an index
/1/indexes/:indexName/querySearches a single index and returns matching search results as hits. This method lets you retrieve up to 1,000 hits. If you need more, use the browse… - POSTSearch multiple queries
/1/indexes/*/queriesRuns multiple search queries against one or more indices in a single API request. Use cases include: Searching different indices, such as products and… - POSTSearch for facet values
/1/indexes/:indexName/facets/:facetName/querySearches for values of a specified facet attribute. By default, facet values are sorted by decreasing count. You can adjust this with the sortFacetValueBy… - POSTBrowse for records
/1/indexes/:indexName/browseRetrieves records from an index, up to 1,000 per request. Searching returns _hits_ (records augmented with highlighting and ranking details). Browsing returns… - POSTAdd a new record (with auto-generated object ID)
/1/indexes/:indexNameAdds a record to an index or replaces it. If the record doesn't have an object ID, a new record with an auto-generated object ID is added to your index. If a… - DELETEDelete an index
/1/indexes/:indexNameDeletes an index and all its settings. Deleting an index doesn't delete its analytics data. If you try to delete a non-existing index, the operation is… - GETRetrieve a record
/1/indexes/:indexName/:objectIDRetrieves one record by its object ID. To retrieve more than one record, use the objects operation. - PUTAdd or replace a record
/1/indexes/:indexName/:objectIDIf a record with the specified object ID exists, the existing record is replaced. Otherwise, a new record is added to the index. If you want to use… - DELETEDelete a record
/1/indexes/:indexName/:objectIDDeletes a record by its object ID. To delete more than one record, use the batch operation. To delete records matching a query, use the deleteBy operation. - POSTDelete records matching a filter
/1/indexes/:indexName/deleteByQueryThis operation doesn't accept empty filters. This operation is resource-intensive. Use it only if you can't get the object IDs of the records you want to… - POSTDelete all records from an index
/1/indexes/:indexName/clearDeletes only the records from an index while keeping settings, synonyms, and rules. This operation is resource-intensive and subject to indexing rate limits. - POSTAdd or update attributes
/1/indexes/:indexName/:objectID/partialAdds new attributes to a record, or updates existing ones. If a record with the specified object ID doesn't exist, a new record is added to the index if… - POSTBatch indexing operations on one index
/1/indexes/:indexName/batchAdds, updates, or deletes records in one index with a single API request. Batching index updates reduces latency and increases data integrity. Actions are… - POSTBatch indexing operations on multiple indices
/1/indexes/*/batchAdds, updates, or deletes records in multiple indices with a single API request. Actions are applied in the order they are specified. Actions are equivalent… - POSTRetrieve records
/1/indexes/*/objectsRetrieves one or more records, potentially from different indices. Records are returned in the same order as the requests. - GETRetrieve index settings
/1/indexes/:indexName/settingsRetrieves an object with non-null index settings. - PUTUpdate index settings
/1/indexes/:indexName/settingsUpdate the specified index settings. Index settings that you don't specify are left unchanged. Specify null to reset a setting to its default value. For best… - GETRetrieve a synonym
/1/indexes/:indexName/synonyms/:objectIDRetrieves a synonym by its ID. To find the object IDs for your synonyms, use the search operation. - PUTCreate or replace a synonym
/1/indexes/:indexName/synonyms/:objectIDIf a synonym with the specified object ID doesn't exist, Algolia adds a new one. Otherwise, the existing synonym is replaced. To add multiple synonyms in a… - DELETEDelete a synonym
/1/indexes/:indexName/synonyms/:objectIDDeletes a synonym by its ID. To find the object IDs of your synonyms, use the search operation. - POSTCreate or replace synonyms
/1/indexes/:indexName/synonyms/batchIf a synonym with the objectID doesn't exist, Algolia adds a new one. Otherwise, existing synonyms are replaced. This operation is subject to indexing rate… - POSTDelete all synonyms
/1/indexes/:indexName/synonyms/clearDeletes all synonyms from the index. - POSTSearch for synonyms
/1/indexes/:indexName/synonyms/searchSearches for synonyms in your index. - GETList API keys
/1/keysLists all API keys associated with your Algolia application, including their permissions and restrictions. - POSTCreate an API key
/1/keysCreates a new API key with specific permissions and restrictions. - GETRetrieve API key permissions
/1/keys/:keyGets the permissions and restrictions of an API key. When authenticating with the admin API key, you can request information for any of your application's… - PUTUpdate an API key
/1/keys/:keyReplaces the permissions of an existing API key. Any unspecified attribute resets that attribute to its default value. - DELETEDelete an API key
/1/keys/:keyDeletes the API key. - POSTRestore an API key
/1/keys/:key/restoreRestores a deleted API key. Restoring resets the validity attribute to 0. Algolia stores up to 1,000 API keys per application. If you create more, the oldest… - GETRetrieve a rule
/1/indexes/:indexName/rules/:objectIDRetrieves a rule by its ID. To find the object ID of rules, use the search operation. - PUTCreate or replace a rule
/1/indexes/:indexName/rules/:objectIDIf a rule with the specified object ID doesn't exist, it's created. Otherwise, the existing rule is replaced. To create or update more than one rule, use the… - DELETEDelete a rule
/1/indexes/:indexName/rules/:objectIDDeletes a rule by its ID. To find the object ID for rules, use the search operation. - POSTCreate or update rules
/1/indexes/:indexName/rules/batchCreate or update multiple rules. If a rule with the specified object ID doesn't exist, Algolia creates a new one. Otherwise, existing rules are replaced. This… - POSTDelete all rules
/1/indexes/:indexName/rules/clearDeletes all rules from the index. - POSTSearch for rules
/1/indexes/:indexName/rules/searchSearches for rules in your index. - POSTAdd or delete dictionary entries
/1/dictionaries/:dictionaryName/batchAdds or deletes multiple entries from your plurals, segmentation, or stop word dictionaries. - POSTSearch dictionary entries
/1/dictionaries/:dictionaryName/searchSearches for standard and custom dictionary entries. - GETRetrieve dictionary settings
/1/dictionaries/*/settingsRetrieves the languages for which standard dictionary entries are turned off. - PUTUpdate dictionary settings
/1/dictionaries/*/settingsTurns standard stop word dictionary entries on or off for a given language. - GETList available languages
/1/dictionaries/*/languagesLists supported languages with their supported dictionary types and number of custom entries. - GETList user IDs
/1/clusters/mappingDeprecated. Lists the userIDs assigned to a multi-cluster application. Since it can take a few seconds to get the data from the different clusters, the… - POSTAssign or move a user ID
/1/clusters/mappingDeprecated. Assigns or moves a user ID to a cluster. The time it takes to move a user is proportional to the amount of data linked to the user ID. - POSTAssign multiple userIDs
/1/clusters/mapping/batchDeprecated. Assigns multiple user IDs to a cluster. You can't move users with this operation. - GETGet top user IDs
/1/clusters/mapping/topDeprecated. Get the IDs of the 10 users with the highest number of records per cluster. Since it can take a few seconds to get the data from the different… - GETRetrieve user ID
/1/clusters/mapping/:userIDDeprecated. Returns the user ID data stored in the mapping. Since it can take a few seconds to get the data from the different clusters, the response isn't… - DELETEDelete user ID
/1/clusters/mapping/:userIDDeprecated. Deletes a user ID and its associated data from the clusters. - GETList clusters
/1/clustersDeprecated. Lists the available clusters in a multi-cluster setup. - POSTSearch for user IDs
/1/clusters/mapping/searchDeprecated. Since it can take a few seconds to get the data from the different clusters, the response isn't real-time. To ensure rapid updates, the user IDs… - GETGet migration and user mapping status
/1/clusters/mapping/pendingDeprecated. To determine when the time-consuming process of creating a large batch of users or migrating users from one cluster to another is complete, this… - GETList allowed sources
/1/security/sourcesRetrieves all allowed IP addresses with access to your application. - PUTReplace allowed sources
/1/security/sourcesReplaces the list of allowed sources. - POSTAdd a source
/1/security/sources/appendAdds a source to the list of allowed sources. - DELETEDelete a source
/1/security/sources/:sourceDeletes a source from the list of allowed sources. - GETRetrieve log entries
/1/logsThe request must be authenticated by an API key with the logs ACL. Logs are held for the last seven days. Up to 1,000 API requests per server are logged. This… - GETCheck application task status
/1/task/:taskIDChecks the status of a given application task. - GETCheck task status
/1/indexes/:indexName/task/:taskIDChecks the status of a given task. Indexing tasks are asynchronous. When you add, update, or delete records or indices, a task is created on a queue and… - POSTCopy or move an index
/1/indexes/:indexName/operationCopies or moves (renames) an index within the same Algolia application. Notes: Existing destination indices are overwritten, except for their analytics data.… - GETList indices
/1/indexesLists all indices in the current Algolia application. The request follows any index restrictions of the API key you use to make the request. - GETWait for an API key operation
/waitForApiKey?key=string&operation=addWaits for an API key to be added, updated, or deleted. - GETWait for operation to complete
/waitForTask?indexName=string&taskID=0Wait for a task to complete to ensure synchronized index updates. All Algolia write operations are asynchronous. When you make a request for a write… - GETWait for application-level operation to complete
/waitForAppTask?taskID=0Wait for a application-level task to complete. - GETGet all records from an index
/browseObjects?indexName=string&browseParams={"query":"","similarQuery":"comedy drama crime Macy Buscemi","filters":"(category:Book OR category:Ebook) AND _tags:published","facetFilters":[["category:Book","category:-Movie"],"author:John Doe"],"optionalFilters":["category:Book","author:John Doe"],"numericFilters":[["inStock = 1","deliveryDate < 1441755506"],"price < 1000"],"tagFilters":[["Book","Movie"],"SciFi"],"sumOrFiltersScores":false,"restrictSearchableAttributes":["title","author"],"facets":["*"],"facetingAfterDistinct":false,"page":0,"offset":0,"length":0,"aroundLatLng":"40.71,-74.01","aroundLatLngViaIP":false,"aroundRadius":1,"aroundPrecision":10,"minimumAroundRadius":1,"insideBoundingBox":"string","insidePolygon":[[47.3165,4.9665,47.3424,5.0201,47.32,4.9],[40.9234,2.1185,38.643,1.9916,39.2587,2.0104]],"naturalLanguages":[],"ruleContexts":["mobile"],"personalizationImpact":100,"userToken":"test-user-123","getRankingInfo":false,"synonyms":true,"clickAnalytics":false,"analytics":true,"analyticsTags":[],"percentileComputation":true,"enableABTest":true,"attributesToRetrieve":["author","title","content"],"ranking":["typo","geo","words","filters","proximity","attribute","exact","custom"],"relevancyStrictness":90,"attributesToHighlight":["author","title","conten","content"],"attributesToSnippet":["content:80","description"],"highlightPreTag":"<em>","highlightPostTag":"</em>","snippetEllipsisText":"…","restrictHighlightAndSnippetArrays":false,"hitsPerPage":20,"minWordSizefor1Typo":4,"minWordSizefor2Typos":8,"typoTolerance":true,"allowTyposOnNumericTokens":true,"disableTypoToleranceOnAttributes":["sku"],"ignorePlurals":["ca","es"],"removeStopWords":["ca","es"],"queryLanguages":["es"],"decompoundQuery":true,"enableRules":true,"enablePersonalization":false,"queryType":"prefixLast","removeWordsIfNoResults":"firstWords","mode":"keywordSearch","semanticSearch":{"eventSources":["string"]},"advancedSyntax":false,"optionalWords":"string","disableExactOnAttributes":["description"],"exactOnSingleWordQuery":"attribute","alternativesAsExact":["ignorePlurals","singleWordSynonym"],"advancedSyntaxFeatures":["exactPhrase","excludeWords"],"distinct":1,"replaceSynonymsInHighlight":false,"minProximity":1,"responseFields":["*"],"maxValuesPerFacet":100,"sortFacetValuesBy":"count","attributeCriteriaComputedByMinProximity":false,"attributeCriteriaComputedBy":"best","renderingContent":{"facetOrdering":{"facets":{"order":null},"values":{"additionalProp1":null}},"redirect":{"url":"string"},"widgets":{"banners":[],"resultCard":{"enabled":true}}},"enableReRanking":true,"reRankingApplyFilter":[],"cursor":"jMDY3M2MwM2QwMWUxMmQwYWI0ZTN"}You can use the browse method to get records from an index—for example, to export your index as a backup. To export all records, use an empty query. Use… - GETCreate secured API keys
/generateSecuredApiKey?parentApiKey=string&restrictions={"searchParams":{"query":"","similarQuery":"comedy drama crime Macy Buscemi","filters":"(category:Book OR category:Ebook) AND _tags:published","facetFilters":[["category:Book","category:-Movie"],"author:John Doe"],"optionalFilters":["category:Book","author:John Doe"],"numericFilters":[["inStock = 1","deliveryDate < 1441755506"],"price < 1000"],"tagFilters":[["Book","Movie"],"SciFi"],"sumOrFiltersScores":false,"restrictSearchableAttributes":["title","author"],"facets":["*"],"facetingAfterDistinct":false,"page":0,"offset":0,"length":0,"aroundLatLng":"40.71,-74.01","aroundLatLngViaIP":false,"aroundRadius":1,"aroundPrecision":10,"minimumAroundRadius":1,"insideBoundingBox":"string","insidePolygon":[[47.3165,4.9665,47.3424,5.0201,47.32,4.9],[40.9234,2.1185,38.643,1.9916,39.2587,2.0104]],"naturalLanguages":[],"ruleContexts":["mobile"],"personalizationImpact":100,"userToken":"test-user-123","getRankingInfo":false,"synonyms":true,"clickAnalytics":false,"analytics":true,"analyticsTags":[],"percentileComputation":true,"enableABTest":true,"attributesToRetrieve":["author","title","content"],"ranking":["typo","geo","words","filters","proximity","attribute","exact","custom"],"relevancyStrictness":90,"attributesToHighlight":["author","title","conten","content"],"attributesToSnippet":["content:80","description"],"highlightPreTag":"<em>","highlightPostTag":"</em>","snippetEllipsisText":"…","restrictHighlightAndSnippetArrays":false,"hitsPerPage":20,"minWordSizefor1Typo":4,"minWordSizefor2Typos":8,"typoTolerance":true,"allowTyposOnNumericTokens":true,"disableTypoToleranceOnAttributes":["sku"],"ignorePlurals":["ca","es"],"removeStopWords":["ca","es"],"queryLanguages":["es"],"decompoundQuery":true,"enableRules":true,"enablePersonalization":false,"queryType":"prefixLast","removeWordsIfNoResults":"firstWords","mode":"keywordSearch","semanticSearch":{"eventSources":["string"]},"advancedSyntax":false,"optionalWords":"string","disableExactOnAttributes":["description"],"exactOnSingleWordQuery":"attribute","alternativesAsExact":["ignorePlurals","singleWordSynonym"],"advancedSyntaxFeatures":["exactPhrase","excludeWords"],"distinct":1,"replaceSynonymsInHighlight":false,"minProximity":1,"responseFields":["*"],"maxValuesPerFacet":100,"sortFacetValuesBy":"count","attributeCriteriaComputedByMinProximity":false,"attributeCriteriaComputedBy":"best","renderingContent":{"facetOrdering":{"facets":{"order":null},"values":{"additionalProp1":null}},"redirect":{"url":"string"},"widgets":{"banners":[],"resultCard":{"enabled":true}}},"enableReRanking":true,"reRankingApplyFilter":[]},"filters":"string","validUntil":0,"restrictIndices":["string"],"restrictSources":"192.168.1.0/24","userToken":"string"}Generates a secured API key without any requests to Algolia's servers. Secured API keys are API keys that you generate on your server without any API request… - GETCopies the given `sourceIndexName` records, rules and synonyms to an other Algolia application for the given `destinationIndexName`
/accountCopyIndex?sourceIndexName=string&destinationAppID=string&destinationApiKey=string&destinationIndexName=stringCopies the given sourceIndexName records, rules and synonyms to an other Algolia application for the given destinationIndexName. - GETReplace all records in an index
/replaceAllObjects?indexName=string&objects={}This method replaces all records in an index without interrupting ongoing searches. It combines batch and copy/move index operations: 1. Copy settings,… - GETReplace all records in an index
/replaceAllObjectsWithTransformation?indexName=string&objects={}Replace all records in your index with a new set of records by using the Transformation pipeline in the Push connector… - GETReplace all records in an index
/chunkedBatch?indexName=string&objects={}Helper: Chunks the given objects list in subset of 1000 elements max in order to make it fit in batch requests. - GETSaves the given array of objects in the given index
/saveObjects?indexName=string&objects={}Helper: Saves the given array of objects in the given index. The chunkedBatch helper splits this into batch requests with at most 1,000 objects each. - GETSave objects to an Algolia index by leveraging the Transformation pipeline setup using the Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push)
/saveObjectsWithTransformation?indexName=string&objects={}Helper: Similar to the saveObjects method but requires a Push connector… - POSTDeletes every records for the given objectIDs
/deleteObjects?indexName=string&objectIDs=stringHelper: Deletes every records for the given objectIDs. The chunkedBatch helper splits this into batch requests with at most 1,000 objectIDs each. - POSTReplaces object content of all the given objects according to their respective `objectID` field
/partialUpdateObjects?indexName=string&objects={}Helper: Replaces object content of all the given objects according to their respective objectID field. The chunkedBatch helper splits this into batch requests… - POSTSave objects to an Algolia index by leveraging the Transformation pipeline setup using the Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push)
/partialUpdateObjectsWithTransformation?indexName=string&objects={}Helper: Similar to the partialUpdateObjects method but requires a Push connector… - GETCheck if an index exists or not
/indexExists?indexName=stringYou can initialize an index with any name. The index is created on Algolia's servers when you add objects or set settings. To prevent accidentally creating… - GETSwitch the API key used to authenticate requests
/setClientApiKey?apiKey=stringSwitch the API key used to authenticate requests.
API details
- Base URL
https://{appId}.algolia.nethttps://{appId}-1.algolianet.comhttps://{appId}-2.algolianet.comhttps://{appId}-3.algolianet.comhttps://{appId}-dsn.algolia.net- Authentication
- An API key in the x-algolia-application-id header
An API key in the x-algolia-api-key header - Operations
- 78 operations on 60 pathsGET 32POST 30PUT 8DELETE 8
9 marked deprecated - Main resources
- search 78
- Response formats
application/json- Description format
- OpenAPI 3.0.2, API version
1.0.0 - Links
- OpenAPI document
How to test the Algolia Search API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Algolia Search API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the x-algolia-application-id header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Send requests to the Algolia REST API” (GET /:path), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Algolia Search API?
Client libraries Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps. The official API clients are covered by… It is listed under Developer tools and has 78 endpoints.
Who publishes the Algolia Search API?
It is listed from Algolia's public API description (an OpenAPI document), not published by Algolia on Swastik Codes. Anyone who controls algolia.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Algolia Search API?
Its description lists 5 base URLs: https://{appId}.algolia.net, https://{appId}-1.algolianet.com, https://{appId}-2.algolianet.com, https://{appId}-3.algolianet.com, https://{appId}-dsn.algolia.net. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Algolia Search API?
It accepts 2 methods: an API key in the x-algolia-application-id header; an API key in the x-algolia-api-key header.
How many endpoints does the Algolia Search API have?
78 operations on 60 paths (32 GET, 30 POST, 8 PUT, 8 DELETE). The largest groups are search.
Is forking the Algolia Search API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.