Search¶

Inspect and manage a website's search configuration: synonyms, stop words, search configs, the rendered search designs, filters and sort options, initial content ("before you search" product panels), and link content (content search).

There are two ways to build a search experience on Hello Retail:

1. Managed search configs, hosted by Hello Retail and served at core.helloretail.com/serve/search. Create them with search_createConfig, inspect them with search_listConfigs, and read or edit their templates, styles, and init code with search_getDesign and search_updateDesign.
2. A fully custom frontend, built against the public Search API. Your frontend calls core.helloretail.com/serve/search directly, against the website's LIVE config. These MCP tools don't run search queries for you; test against that live endpoint directly while you build.

Tips & tricks¶

Pick the card that matches what you're doing. Each prompt is ready to paste into your assistant.

Show the search synonyms configured for my website and what each one expands to.

List the search stop words for my website and suggest any noise words I should add.

Show the initial content of my overlay search config, then add a panel with this season's best sellers.

Show the filters and sort options on my overlay search config, then translate all their texts to German.

Check whether the search config with key "main-search" for my website is LIVE, and tell me where to publish it if not.

search_createConfig¶

Create a search configuration for a website, optionally with a best-practice Hello-Retail-hosted design attached: embedded search for desktop, mobile search for mobile, or both. A search configuration always has a key; the design (templates, styles, init code) is attached to it unless target is NONE. Use target: NONE for a bare configuration with no design, when building a fully custom frontend against the public Search API instead of using a Hello-Retail-hosted design.

Configs are created as drafts that cannot be published through this tool: INTERNAL_REVIEW for Hello Retail supervisors, REVIEW (awaiting business approval) for other users. Edit a managed design afterward with search_updateDesign. Mobile and desktop are separate per-device configs that coexist at runtime, so target: BOTH creates two configs and returns two entries.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_createConfig",
    "arguments": {
      "websiteUuid": "<string>",
      "target": "BOTH"
    }
  }
}

[
  {
    "key": "<string>",
    "configId": 0,
    "name": "<string>",
    "state": "<string>",
    "lastModified": "<string>"
  }
]

search_getDesign¶

Retrieve the design fields (templates, styles, initialization code) of a search configuration for a customer website using Hello Retail. Returns the draft version if one exists, otherwise the LIVE version. Use this before search_updateDesign to read the current state of the design.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "<string>",
  "inputTemplate": "<string>",
  "initializationCode": "<string>",
  "resultTemplate": "<string>",
  "resultStyles": "<string>"
}

search_updateDesign¶

Update the design fields (templates, styles, initialization code) of a search configuration for a customer website using Hello Retail. Directly edits any config that is in INTERNAL_REVIEW or REVIEW state; if no editable config exists, creates a new draft from the current LIVE config and applies the edits to it. All parameters are optional and updates are partial: omitted fields are left unchanged.

This edits a Hello-Retail-hosted (managed) search config served via core.helloretail.com/serve/search. To instead build a fully custom search frontend against the public Search API, see the public Search API; those frontends aren't edited here. Only a LIVE config is queryable there; search_listConfigs's state and draft fields tell you if this one isn't yet.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "draftId": 0,
  "name": "<string>",
  "state": "<string>",
  "lastModified": "<string>"
}

search_getFilters¶

Get the filters of a search configuration for a customer website using Hello Retail. Filters are the facets visitors can narrow search results by (e.g. brand, price, category), returned in the order shown to visitors. Returns the draft version if one exists, otherwise the LIVE version. Use this before search_updateFilters to read the current state.

A filter's type decides how it renders: LIST offers the field's values as options, RANGE offers a min-max slider, BOOLEAN offers a yes/no choice. trueText and falseText label the two choices of a BOOLEAN filter and are null for other types.

The response also lists every field available for filtering on the website: the standard Hello Retail fields plus any extraData fields indexed for search (manage indexing with dataFields_getProductFields and dataFields_updateProductFieldsIndexing). Use search_getFilterUsage to see which filters visitors actually use.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getFilters",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "<string>",
  "filters": [
    {
      "field": "<string>",
      "type": "LIST",
      "title": "<string>",
      "trueText": null,
      "falseText": null
    }
  ],
  "availableFields": [
    {
      "field": "<string>",
      "type": "RANGE"
    }
  ]
}

search_updateFilters¶

Replace the filters of a search configuration for a customer website using Hello Retail. This is a full replacement: the provided list becomes the complete set of filters, shown to visitors in the given order, and previously enabled filters not in the list are disabled. Pass an empty list to disable all filters, and use search_getFilters first to read the current entries when only adding or changing one.

Directly edits any config that is in INTERNAL_REVIEW or REVIEW state; if no editable config exists, creates a new draft from the current LIVE config and applies the change to it.

Each entry has these fields:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateFilters",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "filters": [
        {
          "field": "brand",
          "title": "Brand"
        },
        {
          "field": "inStock",
          "title": "In stock",
          "trueText": "Yes",
          "falseText": "No"
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "draftId": 0,
  "name": "<string>",
  "state": "<string>",
  "lastModified": "<string>"
}

search_getInitialContent¶

Retrieve the initial content of a search configuration for a customer website using Hello Retail. Initial content is the product panels the search UI shows before the visitor has typed a query ("before you search" content). Each entry has a title, a subtitle, a product count, and a productSources document selecting which products to show. Returns the draft version if one exists, otherwise the LIVE version. Use this before search_updateInitialContent to read the current state.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getInitialContent",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "<string>",
  "entries": [
    {
      "title": "<string>",
      "subtitle": "<string>",
      "count": 0,
      "productSources": {
        "version": 1,
        "filterByGroupingKey": false,
        "sources": [
          {
            "productType": "<string>",
            "filters": [],
            "productLimit": 0
          }
        ],
        "filters": []
      }
    }
  ]
}

search_updateInitialContent¶

Replace the initial content of a search configuration for a customer website using Hello Retail — the product panels the search UI shows before the visitor has typed a query. This is a full replacement: the provided entries become the complete initial content list, in the given order. Pass an empty list to remove all initial content, and use search_getInitialContent first to read the current entries when only adding or changing one.

Directly edits any config that is in INTERNAL_REVIEW or REVIEW state; if no editable config exists, creates a new draft from the current LIVE config and applies the change to it.

Each entry has these fields:

The productSources shape is {"version": 1, "filterByGroupingKey": <boolean>, "filters": [{"key", "operator", "value"}], "sources": [{"productType", "productLimit", "filters", ...}]}, where operator is one of EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, IN, NOT_IN, ALL, and productType is e.g. TOP, MOST_BOUGHT, MOST_VIEWED, RETARGETED, RECENTLY_BOUGHT, RECENTLY_CREATED, RANDOM, MANUAL (with productIds), or SEARCH (with searchTerm). version is always 1 (the current document version) and defaults to 1 when omitted. Read the current value with search_getInitialContent for a live example.

A filter value is always a string: a scalar literal ("Nike"), a JSON-encoded list like "[\"Nike\", \"Adidas\"]" for IN/NOT_IN — not a bare JSON array — or a $-prefixed variable like "$brand", resolved from the visitor's context at serve time.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateInitialContent",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "entries": [
        {
          "title": "<string>",
          "subtitle": "<string>",
          "count": 0
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "draftId": 0,
  "name": "<string>",
  "state": "<string>",
  "lastModified": "<string>"
}

search_getLinkContent¶

Retrieve the link content of a search configuration for a customer website using Hello Retail. Link content is content search: alongside product results, the search UI also searches the website's content (categories, site pages, blog posts, brands) and renders the matches as links. Each entry selects one content type, how many results to show, the title and subtitle rendered above them, and the content search engine that executes the query. Returns the draft version if one exists, otherwise the LIVE version. Also lists the website's content search engines, for picking an engineId in search_updateLinkContent.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getLinkContent",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "<string>",
  "entries": [
    {
      "contentType": "<string>",
      "count": 0,
      "title": "<string>",
      "subtitle": "<string>",
      "engineId": 0,
      "engineName": "<string>"
    }
  ],
  "availableEngines": [
    {
      "id": 0,
      "name": "<string>",
      "contentType": "<string>",
      "archived": false
    }
  ]
}

search_updateLinkContent¶

Replace the link content (content search) of a search configuration for a customer website using Hello Retail — the content types (categories, site pages, blog posts, brands) the search UI searches alongside products and renders as links. This is a full replacement: the provided entries become the complete link content list, in the given order. Pass an empty list to disable content search. Each content type can appear at most once.

Directly edits any config that is in INTERNAL_REVIEW or REVIEW state; if no editable config exists, creates a new draft from the current LIVE config and applies the change to it.

Each entry has these fields:

Entries returned by search_getLinkContent can be passed back unchanged — the extra engineName field is ignored — so read, tweak one entry, and write back.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateLinkContent",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "entries": [
        {
          "contentType": "BLOG_POST",
          "count": 0,
          "title": "<string>"
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "draftId": 0,
  "name": "<string>",
  "state": "<string>",
  "lastModified": "<string>"
}

search_getSorting¶

Get the sort options of a search configuration for a customer website using Hello Retail. Sort options are the orderings visitors can pick, each offering an ascending and/or descending direction with its own display text, returned in the order shown to visitors. A direction is offered to visitors exactly when its text is set; a null text means that direction isn't available. Returns the draft version if one exists, otherwise the LIVE version. Use this before search_updateSorting to read the current state.

The response also lists every field available for sorting on the website: the standard Hello Retail fields plus any extraData fields indexed for search (manage indexing with dataFields_getProductFields and dataFields_updateProductFieldsIndexing). Use search_getSortingUsage to see which sort options visitors actually use.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_getSorting",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "<string>",
  "sorting": [
    {
      "field": "<string>",
      "ascendingText": "<string>",
      "descendingText": "<string>"
    }
  ],
  "availableFields": ["<string>"]
}

search_updateSorting¶

Replace the sort options of a search configuration for a customer website using Hello Retail. This is a full replacement: the provided list becomes the complete set of sort options, shown to visitors in the given order, and previously enabled sort options not in the list are disabled. Pass an empty list to disable all sorting, and use search_getSorting first to read the current entries when only adding or changing one.

Directly edits any config that is in INTERNAL_REVIEW or REVIEW state; if no editable config exists, creates a new draft from the current LIVE config and applies the change to it.

Each entry has these fields:

A direction is offered to visitors exactly when its text is provided, so each entry needs ascendingText, descendingText, or both.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateSorting",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "sorting": [
        {
          "field": "price",
          "ascendingText": "Lowest price",
          "descendingText": "Highest price"
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "draftId": 0,
  "name": "<string>",
  "state": "<string>",
  "lastModified": "<string>"
}

search_listConfigs¶

List search configurations for a customer website. Each entry is one search UI instance: a full-page search, instant/autocomplete, or overlay. One entry is returned per key; when a key has multiple lifecycle versions, the editable version (INTERNAL_REVIEW or REVIEW) takes priority, then LIVE, then archived. The draft flag indicates an unpublished draft of an existing LIVE configuration.

type is one of: Full search, Instant search, Overlay search, Other. state is one of: INTERNAL_REVIEW (internal draft), REVIEW (awaiting business approval), LIVE (serving users), ARCHIVED, or INTERNAL_ARCHIVED.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_listConfigs",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

[
  {
    "key": "<string>",
    "name": "<string>",
    "type": "<string>",
    "state": "<string>",
    "draft": false,
    "lastModified": "<string>"
  }
]

search_listStopWords¶

List all search stop words for a customer website using Hello Retail. Stop words are stripped from the visitor's query before search is executed, which is useful for filtering out noise words (e.g. "and", "the", "with") that would otherwise dilute results. Stop words are stored and matched case-insensitively and are configured per website.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_listStopWords",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

["<string>"]

search_listSynonyms¶

List all search synonyms for a customer website using Hello Retail. Each synonym expands a search query: when a visitor searches for word, results matching synonym are also included.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_listSynonyms",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

[
  {
    "word": "<string>",
    "synonym": "<string>"
  }
]