Algolia Composition API
Composes multiple search sources into one curated result set - smart groups, curated queries and composition rules - so a single request returns a merchandised, multi-source response.
This API exposes 20 operations across 13 paths, and defines 186 schemas. It is described by OpenAPI 3.2.0, at version 1.0.0.
Requests are made against 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.
20 operations
13 paths
186 schemas
3 DELETE7 GET7 POST3 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Algolia Composition API declares
2 security schemes
for authenticating requests.
An API key is passed in the header as x-algolia-application-id (appId).
An API key is passed in the header as x-algolia-api-key (apiKey).
By default, every request must be authenticated.
appId— Your Algolia application ID.apiKey— Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions.…
Paths & Operations 20
Across 13 paths, the API surfaces 20 operations — 3 DELETE, 7 GET, 7 POST, 3 PUT. Each is listed below with its method, path, parameters, and response codes.
composition 20
GET
/{path}
Send requests to the Algolia REST API
POST
/{path}
Send requests to the Algolia REST API
PUT
/{path}
Send requests to the Algolia REST API
DELETE
/{path}
Send requests to the Algolia REST API
POST
/1/compositions/{compositionID}/run
Run a Composition
POST
/1/compositions/{compositionID}/facets/{facetName}/query
Search for facet values
GET
/1/compositions
List compositions
GET
/1/compositions/{compositionID}
Retrieve a composition
PUT
/1/compositions/{compositionID}
Update and insert (upsert) a composition
DELETE
/1/compositions/{compositionID}
Delete a composition
POST
/1/compositions/*/batch
Batch action to multiple compositions
POST
/1/compositions/{compositionID}/sortingStrategy
Set or update the "sortingStrategy" configuration for an existing composition
GET
/1/compositions/{compositionID}/rules/{objectID}
Retrieve a rule
PUT
/1/compositions/{compositionID}/rules/{objectID}
Add or update a composition rule
DELETE
/1/compositions/{compositionID}/rules/{objectID}
Delete a Composition Rule
POST
/1/compositions/{compositionID}/rules/batch
Create or update or delete composition rules
POST
/1/compositions/{compositionID}/rules/search
Search for composition rules
GET
/1/compositions/{compositionID}/task/{taskID}
Check task status
GET
/setClientApiKey
Switch the API key used to authenticate requests
GET
/waitForCompositionTask
Wait for operation to complete
Schemas 186
The contract defines 186 schemas that model the data the API accepts and returns. The most detailed are baseInjectionQueryParameters (44 properties), params (30 properties), baseSearchResponse (26 properties), rankingInfo (13 properties). Each schema is shown below with its type and property counts.
filters
string
Filter expression to only include items that match the filter criteria in the response. You can use these filter expressions: - Numeric filters. , where is one…
feedID
string
The ID of the feed.
facetOrdering
object
Order of facet names and facet values in your UI.
2 properties
externalInjectedItem
object
Contains a list of objects to inject from an external source.
1 property
1 required
aroundLatLngViaIP
boolean
Whether to obtain the coordinates from the request's IP address.
anchoring
string
Which part of the search query the pattern should match: - startsWith. The pattern must match the beginning of the query. - endsWith. The pattern must match th…
externalOrdering
Ordering to apply on the injected items coming from the external source. 'default' means the items will be ordered as they are in the index (natural relevance)…
resultsInjectedItemInfoResponse
object
2 properties
1 required
widgets
object
Widgets returned from any rules that are applied to the current search.
1 property
maxValuesPerFacet
integer
Maximum number of facet values to return for each facet.
SingleResultSet_page
integer
The current page of the results.
rankingInfo
object
Object with detailed information about the record's ranking.
13 properties
5 required
hitMetadata
object
An object that contains the extra key-value pairs provided in the injectedItem definition.
1 property
IndexSettings_advancedSyntaxFeatures
array
Advanced search syntax features you want to support - exactPhrase. Phrases in quotes must match exactly. For example, sparkly blue "iPhone case" only returns r…
analytics
boolean
Whether this search will be included in Analytics.
highlightedValue
string
Highlighted attribute value, including HTML tags.
optionalFilters
Filters to promote or demote records in the search results. Optional filters work like facet filters, but they don't exclude records from the search results. R…
aroundRadius
Maximum radius for a search around a central location. This parameter works in combination with the aroundLatLng and aroundLatLngViaIP parameters. By default,…
parameters_page
integer
Requested page of the API response. Algolia uses page and hitsPerPage to control how search results are displayed ([paginated](https://www.algolia.com/doc/guid…
ignorePlurals
Treat singular, plurals, and other forms of declensions as equivalent. Only use this feature for the languages used in your index.
condition
object
5 properties
replaceSynonymsInHighlight
boolean
Whether to replace a highlighted word with the matched synonym By default, the original words are highlighted even if a synonym matches. For example, with home…
restrictHighlightAndSnippetArrays
boolean
Whether to restrict highlighting and snippeting to items that at least partially matched the search query. By default, all items are highlighted and snippeted.
dedupPositioning
string
Deduplication positioning configures how a duplicate result should be resolved between an injected item and main search results. Current configuration supports…
minimumAroundRadius
integer
Minimum radius (in meters) for a search around a location when aroundRadius isn't set.
resultsCompositionsResponse
object
2 properties
1 required
disableTypoToleranceOnAttributes
array
Attributes for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance). Attribu…
synonyms
boolean
Whether to take into account an index's synonyms for this search.
snippetResultMap
object
Snippets that show the context around a matching search query.
aroundPrecisionFromValue
array
facetFilters
Filter the search by facet values, so that only records with the same facet values are retrieved. Prefer using the filters parameter, which supports all filter…
removeStopWords
Removes stop words from the search query. Stop words are common words like articles, conjunctions, prepositions, or pronouns that have little or no meaning on…
insideBoundingBoxArray
array
Coordinates for a rectangular area in which to search. Each bounding box is defined by the two opposite points of its diagonal, and expressed as latitude and l…
snippetResult
searchResponse
highlightResultArray
array
Surround words that match the query with HTML tags for highlighting.
compositionRunSearchResponse
object
2 properties
1 required
compositionObjectID
string
Composition unique identifier.
listCompositionsResponse
object
5 properties
5 required
taskID
integer
Unique identifier of a task. A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress…
GetTaskResponse
object
1 property
1 required
percentileComputation
boolean
Whether to include this search when calculating processing-time percentiles.
SearchParams_enableABTest
boolean
Whether to enable A/B testing for this search.
baseSearchResponse
object
26 properties
snippetResultArray
array
Snippets that show the context around a matching search query.
relevancyStrictness
integer
Relevancy threshold below which less relevant results aren't included in the results You can only set relevancyStrictness on [virtual replica indices](https://…
page
integer
Page of search results to retrieve.
SearchFields
object
7 properties
ErrorBase
object
Error.
1 property
processingTimeMS
integer
Time the server took to process the request, in milliseconds.
minProximity
integer
Minimum proximity score for two matching words This adjusts the [Proximity ranking criterion](https://www.algolia.com/doc/guides/managing-results/relevance-ove…
compositionRuleObjectID
string
Composition rule unique identifier.
allowTyposOnNumericTokens
boolean
Whether to allow typos on numbers in the search query Turn off this setting to reduce the number of irrelevant matches when searching in large sets of similar…
sortRemainingBy
string
Order of facet values that aren't explicitly positioned with the order setting. - count. Order remaining facet values by decreasing count. The count is the num…
bannerImageUrl
object
URL for an image to show inside a banner.
1 property
parameters_query
string
Search query for rules.
feedInjection
object
Feed formatted as an injection.
1 property
1 required
disableExactOnAttributes
array
Searchable attributes for which you want to [turn off the Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/…
deleteCompositionRuleAction
object
Operation arguments when deleting.
1 property
1 required
advancedSyntaxFeatures
string
renderingContent
object
Extra data that can be used in the search UI. You can use this to control aspects of your search UI, such as the order of facet names and values without changi…
3 properties
context
string
An additional restriction that only triggers the rule, when the search has the same value as ruleContexts parameter. For example, if context: mobile, the rule…
snippetResultOption
object
Snippets that show the context around a matching search query.
2 properties
2 required
SingleResultSet_params
string
URL-encoded string of all search parameters.
Behaviour_feedID
object
SingleResultSet_query
string
The search query string.
personalizationImpact
integer
Impact that Personalization should have on this search The higher this value is, the more Personalization determines the ranking compared to other factors. For…
matchLevel
string
Whether the whole query string matches or only a part.
compositionMultifeedBehavior
object
An object containing a multifeed behavior.
1 property
1 required
taskStatus
string
Task status, published if the task is completed, notPublished otherwise.
batchCompositionAction
injectionMain
object
Main defines the organic result set of the injection.
1 property
facetingAfterDistinct
boolean
Whether faceting should be applied after deduplication with distinct This leads to accurate facet counts when using faceting in combination with distinct. It's…
facets
array
Facets for which to retrieve facet values that match the search criteria and the number of matching facet values To retrieve all facets, use the wildcard chara…
responseFields
array
Properties to include in the API response of search and browse requests By default, all response properties are included. To reduce the response size, you can…
naturalLanguages
array
ISO language codes that adjust settings that are useful for processing natural language queries (as opposed to keyword searches) - Sets removeStopWords and ign…
supportedLanguage
string
ISO code for a supported language.
compositionRule
object
7 properties
2 required
searchResultsItem
compositionRankingInfo
object
1 property
injectedItemRecommendSource
object
Injected items will originate from a recommendation request performed on the specified index.
1 property
1 required
action
string
Type of Composition Batch operation.
matchedGeoLocation
object
3 properties
rulesBatchCompositionAction
compositionBehavior
object
An object containing either an injection or multifeed behavior schema, but not both.
hit
object
Search result. A hit is a record from your index, augmented with special attributes for highlighting, snippeting, and ranking.
6 properties
1 required
sortBy
string
Indicates which sorting strategy to apply for the request. The value must match one of the labels defined in the "sortingStrategy" mapping. For example, "Price…
parameters_hitsPerPage
integer
Maximum number of hits per page. Algolia uses page and hitsPerPage to control how search results are displayed ([paginated](https://www.algolia.com/doc/guides/…
distinct
Determines how many records of a group are included in the search results. Records with the same value for the attributeForDistinct attribute are considered a…
order
array
Explicit order of facets or facet values. This setting lets you always show specific facets or facet values at the top of the list.
redirectURL
object
The redirect rule container.
1 property
analyticsTags
array
Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments).
injectedItemExternalSource
object
Injected items will originate from externally provided objectIDs (that must exist in the index) given at runtime in the run request payload.
1 property
1 required
highlightResultMap
object
Surround words that match the query with HTML tags for highlighting.
booleanString
string
bannerImage
object
Image to show inside a banner.
2 properties
IndexSettings_facets
object
Order of facet names.
1 property
banner
object
Banner with image and link to redirect users.
2 properties
resultsInjectedItemAppliedRulesInfoResponse
object
1 property
1 required
nbPages
integer
Number of pages of results.
aroundRadiusAll
string
Return all records with a valid geoloc attribute. Don't filter by distance.
resultsCompositionInfoResponse
object
1 property
1 required
aroundPrecision
Precision of a coordinate-based search in meters to group results with similar distances. The Geo ranking criterion considers all matches within the same range…
minWordSizefor1Typo
integer
Minimum number of characters a word in the search query must contain to accept matches with [one typo](https://www.algolia.com/doc/guides/managing-results/opti…
IndexSettings_alternativesAsExact
array
Determine which plurals and synonyms should be considered an exact matches By default, Algolia treats singular and plural forms of a word, and single-word syno…
hits
array
Search results (hits). Hits are records from your index that match the search criteria, augmented with additional attributes, such as, for highlighting.
injectionMainSource
Source to be used to retrieve organic result set.
SingleResultSet_hitsPerPage
integer
Number of hits returned per page.
highlightResultOption
object
Surround words that match the query with HTML tags for highlighting.
4 properties
3 required
snippetEllipsisText
string
String used as an ellipsis indicator when a snippet is truncated.
feedsOrder
array
A list of Feed IDs that specifies the order in which to order the results in the response. The IDs should be a subset of those in the feeds object of the targe…
compositionBaseSearchResponse
object
1 property
ruleID
string
Unique identifier of a rule object.
RedirectRuleIndexMetadata
object
5 properties
5 required
values
object
Order of facet values. One object for each facet.
deleteCompositionAction
object
Operation arguments when deleting.
1 property
1 required
maxFacetHits
integer
Maximum number of facet values to return when [searching for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/search-f…
ruleContexts
array
Assigns a rule context to the run query [Rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-result…
Hit_rankingInfo
alternativesAsExact
string
enableABTest
boolean
Whether to enable index level A/B testing for this run request. If the composition mixes multiple indices, the A/B test is ignored.
aroundLatLng
string
Coordinates for the center of a circle, expressed as a comma-separated string of latitude and longitude. Only records included within a circle around this cent…
personalization
object
3 properties
baseInjectionQueryParameters
object
44 properties
bannerLink
object
Link for a banner defined in the Merchandising Studio.
1 property
clickAnalytics
boolean
Whether to include a queryID attribute in the response The query ID is a unique identifier for a search query and is required for tracking [click and conversio…
compositionInjectionBehavior
object
An object containing an injection behavior.
1 property
1 required
queryLanguages
array
Languages for language-specific query processing steps such as plurals, stop-word removal, and word-detection dictionaries. This setting sets a default list of…
model
string
Recommendation model to use for retrieving recommendations.
mainInjectionQueryParameters
object
searchResults
object
1 property
1 required
compositionRunAppliedRules
object
1 property
1 required
searchForFacetValuesResults
object
4 properties
3 required
numericFilters
Filter by numeric facets. Prefer using the filters parameter, which supports all filter types and combinations with boolean operators. You can use numeric comp…
attributesToHighlight
array
Attributes to highlight By default, all searchable attributes are highlighted. Use to highlight all attributes or use an empty array [] to turn off highlightin…
searchForFacetValuesResponse
object
1 property
minWordSizefor2Typos
integer
Minimum number of characters a word in the search query must contain to accept matches with [two typos](https://www.algolia.com/doc/guides/managing-results/opt…
advancedSyntax
boolean
Whether to support phrase matching and excluding words from search queries Use the advancedSyntaxFeatures parameter to control which feature is supported.
distinctSeqID
integer
enableRules
boolean
Whether to enable composition rules.
optionalWords
Words that should be considered optional when found in the query. By default, records must match all words in the search query to be included in the search res…
timeRange
object
2 properties
injectionInjectedItem
object
5 properties
4 required
SearchParams_ruleContexts
array
Assigns a rule context to the search query [Rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-res…
sumOrFiltersScores
boolean
Whether to sum all filter scores If true, all filter scores are summed. Otherwise, the maximum filter score is kept. For more information, see [filter scores](…
params
object
30 properties
userData
An object with custom data. You can store up to 32kB as custom data.
composition
object
5 properties
3 required
restrictSearchableAttributes
array
Restricts a search to a subset of your searchable attributes. Attribute names are case-sensitive.
highlightPostTag
string
HTML tag to insert after the highlighted parts in all highlighted results and snippets.
objectID
string
Unique record identifier.
removeWordsIfNoResults
string
Strategy for removing words from the query when it doesn't return any results. This helps to avoid returning empty search results. - none. No words are removed…
nbHits
integer
Number of results (hits).
typoTolerance
Whether [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance) is enabled and how it is applied. If typo…
injection
object
3 properties
1 required
queryType
string
Determines if and how query words are interpreted as prefixes. By default, only the last query word is treated as a prefix (prefixLast). To turn off prefix sea…
userToken
string
Unique pseudonymous or anonymous user identifier. This helps with analytics and click and conversion events. For more information, see [user token](https://www…
IndexSettings_enableRules
boolean
Whether to enable rules.
injectionMainRecommendSource
object
Organic result set will originate from a recommend request.
1 property
1 required
enableReRanking
boolean
Whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking) This setting only has an effect if you activated Dy…
hitsPerPage
integer
Number of hits per page.
insidePolygon
array
Coordinates of a polygon in which to search. Polygons are defined by 3 to 10,000 points. Each point is represented by its latitude and longitude. Provide multi…
sortingStrategy
object
A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. The sorting indices MUST be related to the associated main targete…
injectedItems
object
An object containing keys corresponding to the keys from an injection's injectedItems and values containing a list of hits to inject.
injectedItemSource
exactOnSingleWordQuery
string
Determines how the [Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-dep…
attributesToRetrieve
array
Attributes to include in the API response To reduce the size of your response, you can retrieve only some of the attributes. Attribute names are case-sensitive…
enablePersonalization
boolean
Whether to enable Personalization.
typoToleranceEnum
string
- min. Return matches with the lowest number of typos. For example, if you have matches without typos, only include those. But if there are no matches without…
highlightPreTag
string
HTML tag to insert before the highlighted parts in all highlighted results and snippets.
sortFacetValuesBy
string
Order in which to retrieve facet values - count. Facet values are retrieved by decreasing count. The count is the number of matching records containing this fa…
insideBoundingBox
value
object
3 properties
getRankingInfo
boolean
Whether the run response should include detailed ranking information.
attributesToSnippet
array
Attributes for which to enable snippets. Attribute names are case-sensitive Snippets provide additional context to matched words. If you enable snippets, they…
multifeed
object
2 properties
1 required
SearchParams_getRankingInfo
boolean
Whether the search response should include detailed ranking information.
banners
array
Banners defined in the Merchandising Studio for a given search.
hide
array
Hide facet values.
optionalWordsArray
array
List of [optional words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/creating-a-list-of-optional-…
attributeCriteriaComputedByMinProximity
boolean
Whether the best matching attribute should be determined by minimum proximity This setting only affects ranking if the Attribute ranking criterion comes before…
injectedItemSearchSource
object
Injected items will originate from a search request performed on the specified index.
1 property
1 required
query
string
Search query.
injectionMainSearchSource
object
Organic result set will originate from a search request performed on the specified index.
1 property
1 required
highlightResult
compositionsSearchResponse
object
1 property
1 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
#Search#Merchandising#REST
Where this information came from
This is an independent, third-party profile of Algolia Composition API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.