> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Compositions

> Combine results from multiple indices, content types, and data sources into a single response.

export const organicResultsDefinition = "These are the search results ranked by relevance and your configuration without compositions.";

export const OrganicResults = () => <Tooltip tip={organicResultsDefinition} cta="Smart Groups" href="/doc/guides/compositions/smart-groups/smart-groups">
    organic results
  </Tooltip>;

export const feedDefinition = "Group of items used in a composition. Sources can be search results, recommendations, or external data.";

export const Feed = () => <Tooltip tip="Group of items used in a composition. Sources can be search results, recommendations, or external data." href="/doc/guides/compositions/multifeed-compositions" cta="Multifeed compositions">
    feed
  </Tooltip>;

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 <OrganicResults />.
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](/doc/guides/compositions/smart-groups/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

<AccordionGroup>
  <Accordion title="Composition">
    A composition combines results from multiple sources into one response.
    Your frontend queries a single endpoint instead of searching each source on its own.
  </Accordion>

  <Accordion title="Feed">
    {feedDefinition}
  </Accordion>

  <Accordion title="Composition rule">
    Sets when and where groups appear, based on a query, catalog, or collection.
  </Accordion>

  <Accordion title="Smart Group">
    A set of results that match specific attributes, placed at a chosen spot in an organic results feed.
  </Accordion>

  <Accordion title="Category page">
    A product landing page built from a search request with applied filters.
  </Accordion>

  <Accordion title="Collection">
    Curated product listings.
    You can create a collection by manually selecting records or defining them using conditions.
  </Accordion>

  <Accordion title="Organic results">
    {organicResultsDefinition}
  </Accordion>

  <Accordion title="Search-based groups">
    [Search-based groups](https://algolia.com/doc/guides/compositions/smart-groups/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.
  </Accordion>

  <Accordion title="External source groups">
    [External source groups](https://algolia.com/doc/guides/compositions/smart-groups/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.
  </Accordion>

  <Accordion title="Recommend-based groups">
    [Recommend-based groups](https://algolia.com/doc/guides/compositions/smart-groups/recommend-based-groups) let you populate a group with items returned by an [Algolia Recommend](https://algolia.com/doc/guides/algolia-recommend/overview) model.
    You configure them through the Composition API by setting the group source to `recommend`.
  </Accordion>
</AccordionGroup>

## 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](/doc/guides/scaling/infrastructure/dynamic/dynamic). If your app uses [classic infrastructure](/doc/guides/scaling/infrastructure/classic/servers-clusters), migrate it first. Contact your customer success manager or the [support team](https://support.algolia.com/hc/en-us/requests/new).
* You must have access to [Merchandising Studio](/doc/guides/managing-results/rules/merchandising-and-promoting#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](https://support.algolia.com/hc/en-us/requests/new).
* [Multifeed compositions](/doc/guides/compositions/multifeed-compositions) require additional access. To request it, contact your Algolia customer success manager.