Elastic Path Search API

openapi: 3.2.0
info:
  title: Catalog Introduction Search API
  version: 26.0604.7696948
  x-version-timestamp: 2026-06-04 10:33:46+00:00
  description: 'Elastic Path Catalog Search provides fast, relevant product search capabilities for your published catalogs. Catalog Search enables shoppers to find products quickly using full-text search, filtering, faceting, and sorting, while giving merchandisers powerful tools to customize search relevance and ranking.


    You can integrate Catalog Search into your storefront using the Catalog Search API or manage search settings through Commerce Manager.


    ### How Catalog Search Works


    Catalog Search works alongside your Product Experience Manager catalogs to provide optimized search functionality.


    When creating or updating a catalog, enable search to allow the catalog''s products to be indexed. See [Catalogs](/docs/api/pxm/catalog/catalogs). Then when a search-enabled catalog is published, the products are automatically indexed for search. The search index contains product data optimized for fast querying.


    Use the Search API to query products with full-text search, filtering, faceting, and sorting. The results of the search contain the full product information, not just the indexed fields, reducing the need for further API calls.


    ### Key Capabilities


    - **Full-text search**: Search across product names, descriptions, SKUs, and custom fields with typo tolerance and relevance ranking

    - **Filtering**: Narrow results using conditions on product attributes, categories, prices, and custom fields

    - **Faceting**: Get aggregated counts for attribute values to build dynamic navigation and refinement options

    - **Sorting**: Order results by price, name, custom fields, or relevance score

    - **Search Profiles**: Configure search behavior including field weights, filters, and boost rules without code changes

    - **Custom Fields**: Extend the search schema with your own product attributes for filtering, faceting, and sorting

    - **Fully Hydrated Responses**: Search results contain complete information about the products, reducing the requirement for follow-up API calls.


    ### Personalized Search Results


    Search results are automatically personalized based on the shopper''s context. The system determines which catalog and prices to show based on:


    - **Channel**: The shopping experience, such as a web storefront or mobile app

    - **Account**: For B2B scenarios, the shopper''s account and any parent accounts

    - **Customer**: The logged-in customer''s segment or tier

    - **Tags**: Custom context tags for advanced segmentation scenarios


    See [**Characteristics of Shopper Catalogs**](/docs/api/pxm/catalog/shopper-catalog-api#characteristics-of-shopper-catalogs) for more information.


    ### Search Profiles


    Search Profiles give merchandisers control over search behavior without requiring code changes. With Search Profiles, you can:


    - **Configure field weights**: Control which product fields are most important for relevance ranking

    - **Apply default filters**: Enforce business rules like only showing live products

    - **Boost products**: Promote featured products, specific brands, or categories to the top of results

    - **A/B test**: Create multiple profiles to test different search configurations


    See [**Search Profiles**](/docs/api/pxm/catalog-search/search-profiles) for more information.


    ### Extending the Search Schema


    By default, the search index includes standard product fields like name, description, SKU, and categories. You can extend the schema by adding custom fields using [Indexable Fields](/docs/api/pxm/catalog-search/indexable-fields).


    Two types of custom fields can be indexed:


    - **Product extension fields** (`extensions.products(<slug>).<field>`): Fields from your product extension templates.

    - **Product custom attributes** (`shopper_attributes.<attribute>` and `admin_attributes.<attribute>`): Merchant-defined key/value attributes on products.


    This allows you to:


    - Search on custom product attributes like brand, material, or specifications

    - Filter products by custom fields like color, size, or rating

    - Display facets for custom field values in your navigation

    - Sort results by custom numeric fields like rating or popularity


    See [**Indexable Fields**](/docs/api/pxm/catalog-search/indexable-fields) for more information.

    '
servers:
- url: https://euwest.api.elasticpath.com/v2
  description: EU west cluster
- url: https://useast.api.elasticpath.com/v2
  description: US east cluster
security:
- BearerToken: []
tags:
- name: Search
  description: 'The Search API enables you to search for products in your published catalogs. Search provides powerful capabilities including full-text search, filtering, faceting, and sorting to help shoppers find products quickly and efficiently.


    ### How Search Works


    When you publish a catalog with search enabled, the catalog''s products are automatically indexed for search. The search index contains product data optimized for fast querying, including product names, descriptions, SKUs, categories, prices, and any custom fields you''ve configured.


    There are two types of search operations:


    - **Search**: Execute a single search query against a catalog. Use the GET endpoint for simple searches with query parameters.

    - **Multi-search**: Execute multiple search queries in a single request. Use the POST endpoint to batch searches together for improved performance.


    ### Search Features


    - **Full-text search**: Search across product names, descriptions, SKUs, and custom fields with typo tolerance and relevance ranking

    - **Filtering**: Narrow results using conditions on product attributes, categories, prices, and custom fields

    - **Faceting**: Get aggregated counts for attribute values to build dynamic navigation and refinement options

    - **Sorting**: Order results by price, name, custom fields, or relevance score

    - **Highlighting**: Get highlighted snippets showing where search terms match in product fields

    - **Autocomplete**: Get search suggestions as shoppers type their queries


    ### Shopper Context


    Search results are personalized based on the shopper''s context. The system automatically determines which catalog and prices to use based on:


    - **Channel**: The shopping experience (web, mobile, B2B portal)

    - **Account**: For B2B scenarios, the account and parent accounts

    - **Customer**: The logged-in customer''s segment

    - **Tags**: Custom context tags for advanced segmentation


    This context is provided via request headers and is used to resolve the appropriate catalog rules and price books.


    ### Admin vs Shopper Endpoints


    - **Shopper endpoints** (`/pcm/catalog/search`, `/pcm/catalog/multi-search`): Use shopper context headers to automatically resolve the correct catalog and prices.

    - **Admin endpoints** (`/pcm/catalogs/{catalog_id}/releases/{release_id}/search`): Directly specify the catalog and release to search, useful for previewing releases or testing.

    '
paths:
  /pcm/catalog/multi-search:
    post:
      tags:
      - Search
      operationId: postMultiSearch
      summary: Multi-search
      description: Execute one or more searches in a single request.
      parameters:
      - $ref: '#/components/parameters/accept-language'
      - $ref: '#/components/parameters/channel'
      - $ref: '#/components/parameters/products-include'
      - $ref: '#/components/parameters/tag'
      - $ref: '#/components/parameters/search-profile'
      - $ref: '#/components/parameters/simulated-shopper-date'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiSearchRequest'
      responses:
        '200':
          description: Multi-search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiSearchResponse'
        '400':
          description: Bad request - invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-filter:
                  value:
                    errors:
                    - title: Invalid Filter
                      status: '400'
                      detail: Could not parse the filter query.
                invalid-facet:
                  value:
                    errors:
                    - title: Invalid Facet
                      status: '400'
                      detail: Invalid facet field specified.
                invalid-pagination:
                  value:
                    errors:
                    - title: Invalid Pagination
                      status: '400'
                      detail: Invalid page or per_page parameter.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /pcm/catalogs/{catalog_id}/releases/{release_id}/multi-search:
    post:
      tags:
      - Search
      operationId: multiSearchByCatalogRelease
      summary: Admin Multi-search
      description: Execute one or more searches in a single request.
      parameters:
      - name: catalog_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the catalog to query
        x-go-name: catalogID
      - name: release_id
        in: path
        required: true
        schema:
          type: string
        description: The unique ID of a published release of the catalog or `latestPublished` for the most recently published version
        x-go-name: releaseID
      - $ref: '#/components/parameters/accept-language'
      - $ref: '#/components/parameters/products-include'
      - $ref: '#/components/parameters/pricebook-ids-for-price-segmentation-preview'
      - $ref: '#/components/parameters/pricebook-ids-of-available-prices-to-show'
      - $ref: '#/components/parameters/search-profile'
      - $ref: '#/components/parameters/simulated-shopper-date'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiSearchRequest'
      responses:
        '200':
          description: Multi-search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiSearchResponse'
        '400':
          description: Bad request - invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-filter:
                  value:
                    errors:
                    - title: Invalid Filter
                      status: '400'
                      detail: Could not parse the filter query.
                invalid-facet:
                  value:
                    errors:
                    - title: Invalid Facet
                      status: '400'
                      detail: Invalid facet field specified.
                invalid-pagination:
                  value:
                    errors:
                    - title: Invalid Pagination
                      status: '400'
                      detail: Invalid page or per_page parameter.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /pcm/catalog/search:
    get:
      tags:
      - Search
      operationId: searchByContext
      summary: Search
      description: Execute search.
      parameters:
      - $ref: '#/components/parameters/accept-language'
      - $ref: '#/components/parameters/channel'
      - $ref: '#/components/parameters/products-include'
      - $ref: '#/components/parameters/tag'
      - $ref: '#/components/parameters/search-profile'
      - $ref: '#/components/parameters/search-query-param-type'
      - $ref: '#/components/parameters/search-query-param-highlight-full-fields'
      - $ref: '#/components/parameters/search-query-param-q'
      - $ref: '#/components/parameters/search-query-param-facet-by'
      - $ref: '#/components/parameters/search-query-param-filter-by'
      - $ref: '#/components/parameters/search-query-param-sort-by'
      - $ref: '#/components/parameters/search-query-param-max-facet-values'
      - $ref: '#/components/parameters/simulated-shopper-date'
      - in: query
        name: page
        schema:
          type: integer
        example: 1
      - in: query
        name: per_page
        schema:
          type: integer
        example: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request - invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-filter:
                  value:
                    errors:
                    - title: Invalid Filter
                      status: '400'
                      detail: Could not parse the filter query.
                invalid-facet:
                  value:
                    errors:
                    - title: Invalid Facet
                      status: '400'
                      detail: Invalid facet field specified.
                invalid-pagination:
                  value:
                    errors:
                    - title: Invalid Pagination
                      status: '400'
                      detail: Invalid page or per_page parameter.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /pcm/catalogs/{catalog_id}/releases/{release_id}/search:
    get:
      tags:
      - Search
      operationId: searchByCatalogRelease
      summary: Admin Search
      description: Execute search.
      parameters:
      - name: catalog_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the catalog to query
        x-go-name: catalogID
      - name: release_id
        in: path
        required: true
        schema:
          type: string
        description: The unique ID of a published release of the catalog or `latestPublished` for the most recently published version
        x-go-name: releaseID
      - $ref: '#/components/parameters/accept-language'
      - $ref: '#/components/parameters/products-include'
      - $ref: '#/components/parameters/pricebook-ids-for-price-segmentation-preview'
      - $ref: '#/components/parameters/pricebook-ids-of-available-prices-to-show'
      - $ref: '#/components/parameters/search-profile'
      - $ref: '#/components/parameters/search-query-param-type'
      - $ref: '#/components/parameters/search-query-param-highlight-full-fields'
      - $ref: '#/components/parameters/search-query-param-q'
      - $ref: '#/components/parameters/search-query-param-facet-by'
      - $ref: '#/components/parameters/search-query-param-filter-by'
      - $ref: '#/components/parameters/search-query-param-sort-by'
      - $ref: '#/components/parameters/search-query-param-max-facet-values'
      - $ref: '#/components/parameters/simulated-shopper-date'
      - in: query
        name: page
        schema:
          type: integer
        example: 1
      - in: query
        name: per_page
        schema:
          type: integer
        example: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request - invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-filter:
                  value:
                    errors:
                    - title: Invalid Filter
                      status: '400'
                      detail: Could not parse the filter query.
                invalid-facet:
                  value:
                    errors:
                    - title: Invalid Facet
                      status: '400'
                      detail: Invalid facet field specified.
                invalid-pagination:
                  value:
                    errors:
                    - title: Invalid Pagination
                      status: '400'
                      detail: Invalid page or per_page parameter.
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    search-profile:
      in: query
      name: search_profile
      description: The slug of the search profile to use for this search. Do not specify to use default search profile.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
      example: clothing
      x-go-name: SearchProfileSlug
    accept-language:
      description: The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
      in: header
      name: accept-language
      schema:
        type: string
      example: en-US
      required: false
    search-query-param-facet-by:
      in: query
      name: facet_by
      description: Specifies which fields to use for generating facets in search results. See [faceting](/guides/How-To/Catalogs/Search/faceting) for more details.
      example: meta.search.nodes.name
      schema:
        type: string
    products-include:
      name: include
      in: query
      description: 'Using the include parameter, you can retrieve top-level resources.


        - Files or main image. For example, `include=files,main_image`.

        - Component product data. For example, `include=component_products`.

        - Key attribute data, such as SKU or slug.

        '
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - files
          - main_image
          - component_products
    pricebook-ids-of-available-prices-to-show:
      in: header
      name: EP-Pricebook-IDs-Of-Available-Prices-To-Show
      description: Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.
      schema:
        type: array
        maxItems: 5
        items:
          type: string
    channel:
      description: The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.
      in: header
      name: EP-Channel
      schema:
        type: string
      required: false
    simulated-shopper-date:
      in: header
      name: EP-Simulated-Shopper-Date
      schema:
        type: string
      required: false
    search-query-param-highlight-full-fields:
      in: query
      name: highlight_full_fields
      description: Comma-separated list of fields to highlight
      schema:
        type: string
      example: name,description
    search-query-param-filter-by:
      in: query
      name: filter_by
      description: Applies conditions to narrow down search results based on specific field values. See [filtering](/guides/How-To/Catalogs/Search/filtering) for more details.
      example: meta.search.nodes.name:=Electronics && price.float_price:>=10.00
      schema:
        type: string
    search-query-param-type:
      in: query
      name: type
      description: Type of search operation to perform
      schema:
        type: string
        enum:
        - search
        - autocomplete
      example: search
    search-query-param-max-facet-values:
      in: query
      name: max_facet_values
      description: Maximum number of facet values to return
      schema:
        type: integer
      example: 10
    search-query-param-sort-by:
      in: query
      name: sort_by
      description: Orders search results by specified fields. See [sorting](/guides/How-To/Catalogs/Search/sorting) for more details.
      example: price.amount:asc,extensions.products(Specification).rating:desc
      schema:
        type: string
    search-query-param-q:
      in: query
      name: q
      description: Search query
      schema:
        type: string
      required: true
      example: search query
    pricebook-ids-for-price-segmentation-preview:
      in: header
      name: EP-Pricebook-IDs-For-Price-Segmentation-Preview
      description: Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.
      schema:
        type: array
        maxItems: 5
        items:
          type: string
    tag:
      description: Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.
      in: header
      name: EP-Context-Tag
      schema:
        type: string
      required: false
  schemas:
    AutocompleteResponse:
      type: object
      title: AutocompleteResponse
      description: An autocomplete suggestion with query frequency information.
      properties:
        id:
          description: A unique identifier for the autocomplete suggestion.
          type: string
          example: hammer_123
          x-go-name: ID
        q:
          description: The query text for the autocomplete suggestion.
          type: string
          example: hammer
          x-go-name: Query
        count:
          description: The frequency count of this query.
          type: integer
          example: 42
          x-go-name: Count
    SearchResultType:
      type: string
      enum:
      - search
      - autocomplete
      example: search
      description: Type of search operation to performed
    SearchResult:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SearchResultType'
        facet_counts:
          type: array
          items:
            $ref: '#/components/schemas/FacetCount'
        found:
          type: integer
          example: 150
        hits:
          type: array
          items:
            $ref: '#/components/schemas/Hit'
        out_of:
          type: integer
          example: 150
        page:
          type: integer
          example: 1
        request_params:
          type: object
        search_cutoff:
          type: boolean
          example: false
        search_time_ms:
          type: integer
          example: 25
    FacetValue:
      type: object
      properties:
        count:
          type: integer
          example: 42
        highlighted:
          type: string
          example: <em>electronics</em>
        value:
          type: string
          example: electronics
    MultiSearchRequest:
      type: object
      required:
      - searches
      properties:
        searches:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/SearchQuery'
    IncludedResponse:
      type: object
      description: Included is an array of resources that are included in the response.
      additionalProperties:
        type: array
        items:
          type: object
    MultiSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        included:
          $ref: '#/components/schemas/IncludedResponse'
    SearchQuery:
      type: object
      properties:
        type:
          type: string
          enum:
          - search
          - autocomplete
          example: search
          description: Type of search operation to perform
        highlight_full_fields:
          type: string
          example: name,description
        q:
          type: string
          example: search query
        facet_by:
          $ref: '#/components/schemas/FacetByField'
        filter_by:
          $ref: '#/components/schemas/FilterByField'
        sort_by:
          $ref: '#/components/schemas/SortByField'
        max_facet_values:
          type: integer
          example: 10
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
    FacetByField:
      type: string
      description: Specifies which fields to use for generating facets in search results. See [faceting](/guides/How-To/Catalogs/Search/faceting) for more details.
      example: meta.search.nodes.name
    SearchResponse:
      allOf:
      - $ref: '#/components/schemas/SearchResult'
      - type: object
        properties:
          included:
            $ref: '#/components/schemas/IncludedResponse'
    FacetCount:
      type: object
      properties:
        counts:
          type: array
          items:
            $ref: '#/components/schemas/FacetValue'
        field_name:
          type: string
          example: category
        sampled:
          type: boolean
          example: false
        stats:
          type: object
    Error:
      required:
      - status
      - title
      properties:
        status:
          type: string
          description: The HTTP response code of the error.
          example: '500'
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
            - e7d50bd5-1833-43c0-9848-f9d325b08be8
    Hit:
      type: object
      properties:
        document:
          oneOf:
          - $ref: '#/components/schemas/Product'
          - $ref: '#/components/schemas/AutocompleteResponse'
          description: Document object - either a Product or AutocompleteResponse
        highlight:
          type: object
        highlights:
          type: array
          items:
            type: object
    Product:
      type: object
      title: Product
      description: A product in a catalog with the following attributes.
      properties:
        attributes:
          type: object
          description: Arbitrary document object
        id:
          description: A unique identifier for a product.
          type: string
          example: 8fccaa19-dba9-4621-8d11-31a222a68c7c
          x-go-name: ID
        relationships:
          type: object
          description: Arbitrary document object
        type:
          description: This represents the type of object being returned. Always `product`.
          type: string
          example: product
          x-go-name: Type
        meta:
          type: object
          description: Arbitrary document object
    SortByField:
      type: string
      description: Orders search results by specified fields. See [sorting](/guides/How-To/Catalogs/Search/sorting) for more details.
      example: price.amount:asc,extensions.products(Specification).rating:desc
    FilterByField:
      type: string
      description: Applies conditions to narrow down search results based on specific field values. See [filtering](/guides/How-To/Catalogs/Search/filtering) for more details.
      example: meta.search.nodes.name:=Electronics && price.float_price:>=10.00
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
  responses:
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                - title: Internal Server Error
                  status: '500'
  securitySchemes:
    BearerToken:
      scheme: bearer
      type: http