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). The ranking behind a config (search steps, boosts, elevates, excludes, personalization) lives on its product search engine, covered by the Search engines tools.

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 my top searches with no results for the last 30 days, work out which products each one was looking for, and add synonyms so they return results.

Show which search filters my visitors used most in the last 90 days, then reorder the filters on my overlay search config to match and suggest any I should remove.

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.

Which product search engine does my main search config use, and which other configs share it?

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_setConfigProductEngine¶

Set which product search engine a search configuration uses. Every search config references exactly one product engine, and most websites have a single engine shared by all their configs, so this matters once you have created an alternative engine with search_createProductEngine and want a config to use it. search_listProductEngines shows which configs use each engine today.

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. The LIVE config keeps its engine until the draft is published.

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

{
  "key": "<string>",
  "draftId": 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_listSynonyms¶

List all search synonyms for a customer website using Hello Retail, with the id the editing tools take. Each synonym expands a search query: when a visitor searches for word, products containing synonym are also found. Synonyms are applied when products are indexed, so an edit reaches visitors once the product catalog has been re-indexed.

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

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

search_addSynonyms¶

Add one or more search synonyms to a customer website using Hello Retail. Existing synonyms are kept. Values are stored lowercase and trimmed. An entry the website already has is refused, so read the current list with search_listSynonyms first. Listing the same entry twice in one call stores it once, so an uploaded list with repeated lines is not rejected over them.

Each entry has these fields:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_addSynonyms",
    "arguments": {
      "websiteUuid": "<string>",
      "synonyms": [
        {"word": "sneakers", "synonym": "running shoes"},
        {"word": "trainers", "synonym": "running shoes"}
      ]
    }
  }
}

[
  {
    "id": 0,
    "word": "sneakers",
    "synonym": "running shoes"
  },
  {
    "id": 1,
    "word": "trainers",
    "synonym": "running shoes"
  }
]

search_updateSynonym¶

Edit one search synonym of a customer website using Hello Retail, identified by its id. Pass the fields to change; an omitted field keeps its value. Returns the synonym as stored. The edit is refused when it would duplicate another synonym.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateSynonym",
    "arguments": {
      "websiteUuid": "<string>",
      "synonymId": 0,
      "word": "trainers"
    }
  }
}

{
  "id": 0,
  "word": "trainers",
  "synonym": "running shoes"
}

search_deleteSynonym¶

Delete one search synonym of a customer website using Hello Retail, identified by its id. Returns the synonyms that remain.

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

[]

search_replaceSynonyms¶

Replace all search synonyms of a customer website using Hello Retail. This is a full replacement: the provided list becomes the complete set, so pass an empty list to remove every synonym. Prefer search_addSynonyms, search_updateSynonym and search_deleteSynonym for individual changes. The same entry listed twice is stored once.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_replaceSynonyms",
    "arguments": {
      "websiteUuid": "<string>",
      "synonyms": [
        {"word": "sneakers", "synonym": "running shoes"}
      ]
    }
  }
}

[
  {
    "id": 0,
    "word": "sneakers",
    "synonym": "running shoes"
  }
]

search_listStopWords¶

List all search stop words for a customer website using Hello Retail, with the id the editing tools take. 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>"
    }
  }
}

[
  {
    "id": 0,
    "word": "<string>"
  }
]

search_addStopWords¶

Add one or more search stop words to a customer website using Hello Retail. Existing stop words are kept. Words are stored lowercase and trimmed. A word the website already has is refused, so read the current list with search_listStopWords first. Listing the same word twice in one call stores it once.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_addStopWords",
    "arguments": {
      "websiteUuid": "<string>",
      "words": ["and", "the"]
    }
  }
}

[
  {
    "id": 0,
    "word": "and"
  },
  {
    "id": 1,
    "word": "the"
  }
]

search_updateStopWord¶

Edit one search stop word of a customer website using Hello Retail, identified by its id. The edit is refused when it would duplicate another stop word.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_updateStopWord",
    "arguments": {
      "websiteUuid": "<string>",
      "stopWordId": 0,
      "word": "a"
    }
  }
}

{
  "id": 0,
  "word": "a"
}

search_deleteStopWord¶

Delete one search stop word of a customer website using Hello Retail, identified by its id. Returns the stop words that remain.

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

[
  {
    "id": 1,
    "word": "the"
  }
]

search_replaceStopWords¶

Replace all search stop words of a customer website using Hello Retail. This is a full replacement: the provided list becomes the complete set, so pass an empty list to remove every stop word. Prefer search_addStopWords, search_updateStopWord and search_deleteStopWord for individual changes. The same word listed twice is stored once.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_replaceStopWords",
    "arguments": {
      "websiteUuid": "<string>",
      "words": ["and", "the", "with"]
    }
  }
}

[
  {
    "id": 0,
    "word": "and"
  }
]