Skip to main content
The Composition API lets you combine results from multiple indices, content types and data sources into a single response. Use it to build federated search, category pages, and dynamic experiences. These experiences can show curated or sponsored content next to . Manage compositions in the Algolia dashboard and render them with InstantSearch. Update experiences without changing frontend code.

​
What you can do with compositions

  • Compose results from multiple sources: combine multiple indices, content types, and data sources in a single request. No frontend orchestration needed.
  • Inject Smart Groups: place curated product groups at specific positions within organic results. Inject sponsored content, trending items, brand partnerships and more.
  • Scalable orchestration: the composition holds all the complex logic. Frontend teams can focus on the best rendering and experience for their customers.

​
When to use compositions

Use the Composition API when you need to return multiple result sets in one request. It also works when you want to inject dynamic sponsored results at set spots. Use it to build collections, category pages, or federated search too.

​
Key concepts

A composition combines results from multiple sources into one response. Your frontend queries a single endpoint instead of searching each source on its own.
Group of items used in a composition. Sources can be search results, recommendations, or external data.
Sets when and where groups appear, based on a query, catalog, or collection.
A set of results that match specific attributes, placed at a chosen spot in an organic results feed.
A product landing page built from a search request with applied filters.
Curated product listings. You can create a collection by manually selecting records or defining them using conditions.
These are the search results ranked by relevance and your configuration without compositions.
Search-based groups use Algolia filters to automatically select items that match your criteria. You define what to promote (like brand:Adidas AND in_stock:true), and Algolia finds which items match.Algolia’s AI-powered ranking finds which matching items best fit the user’s query. This keeps promoted items feeling natural in the search results.
External source groups let you pick items to promote by giving a list of object IDs. These object IDs come from an external system like:
  • Retail media platforms
  • Custom bidding or campaign management systems
Your backend calls the external source, receives objectIDs, then passes them to Algolia’s Composition API. Algolia handles injection, deduplication, and optional re-ranking by relevance.
Recommend-based groups let you populate a group with items returned by an Algolia Recommend model. You configure them through the Composition API by setting the group source to recommend.

​
Before you begin using the Compositions API

Before using the Composition API, make sure your setup meets these requirements:
  • Your Algolia application must use Algolia’s dynamic scaling infrastructure. If your app uses classic infrastructure, migrate it first. Contact your customer success manager or the support team.
  • You must have access to Merchandising Studio to curate results.
  • Your application must have the Composition API and Smart Groups enabled. If your plan should include these features but you can’t access them, contact your account manager, your customer success manager, or the support team.
  • Multifeed compositions require additional access. To request it, contact your Algolia customer success manager.
Last modified on September 16, 2026