Full rendered search: autocomplete suggestions + faceted results.

GET /search/query/{term}

GET https://mercury.plutocracy.io/search/query/{term}

Served from Redis in all four regions (Sydney, N. Virginia, N. California, Frankfurt); DNS latency routing picks the nearest.

Auth: Origin+bypass redis strategy.

400 No term specified when term is empty or the literal string "undefined".

406 when the underlying redis query fails.

Authentication

Send the storefront's Origin (browsers do this for you) or ?bypassToken=. A request with neither gets 401. See authentication.

Parameters

Name	In	Type	Description
`term` required	path	string
`take`	query	string	Results to return; max 50, default 20. Arrives as a string.
`skip`	query	string	Results to skip; should be a multiple of `take`.
`page`	query	string	1-based page number. When present, `skip` is recomputed as `take * (page - 1)` (default take 20). Values < 1 → 400.
`pageNumber`	query	string	Alias for `page` honoured by the pagination helper.
`query`	query	string	JSON-stringified `FilterOperator` array of additional filters.
`sort`	query	string	Mercury sort order (e.g. `newest`, `priceLow`, `az`).
`currency`	query	string	Narrow all product `prices` maps to this currency.
`tracking`	query	string	`none` disables analytics tracking for this request.
`userId`	query	string	Client user id used to key the analytics entry.
`red`	query	string	Allow the search to return redirect URLs for the term (swagger-documented).
`sug`	query	string	Allow the search to return similar search terms (swagger-documented).
`grid_config`	query	string	Include the store Grid Config in the response. BUG: string-truthiness check — `grid_config=false` STILL includes it (pinned by libs/controllers/src/search.controller.spec.ts). Omit the parameter (or send an empty string) to exclude it.

Responses

200 OK application/json

Type: RenderedSearch

Response of GET search/query/:term (rendered search). Spread order (pinned by libs/controllers/src/search.controller.spec.ts): suggested from autocomplete first, then the search-result keys (which can OVERRIDE suggested), then optionally grid_config.

Field	Type	Description
`suggested`	string[]	Autocomplete suggestions for the term ([] when the dictionary errors).
`facets`	SearchFacets
`products`	RenderedProduct[]
`query`	FilterOperator[]	Echo of the parsed `query` filter operators ([] when unparsable).
`search`	string	The cleaned search term actually executed.
`redirect` optional	string \| null	Present when a search-term redirect is configured for the term.
`grid_config` optional	GridConfig	Present when `grid_config` was requested (any non-empty string).

Example response (illustrative)

{
  "suggested": [
    "linen"
  ],
  "facets": {
    "vendors": [
      {
        "vendor": "Mercury Apparel",
        "count": 12
      }
    ],
    "types": [
      {
        "type": "Shirts",
        "count": 12
      }
    ],
    "tags": [
      {
        "value": "string",
        "count": 12
      }
    ],
    "count": 12
  },
  "products": [
    {
      "id": "7712345678901",
      "title": "Linen shirt",
      "implode": 1,
      "handle": "linen-shirt",
      "min_price": 89,
      "compare_at_min_price": 89,
      "vendor": "Mercury Apparel",
      "type": "Shirts",
      "on_sale": false,
      "total_stock": 12,
      "variants": [
        {
          "title": "Linen shirt",
          "id": 7712345678901,
          "inventory": 12,
          "price": "89.00",
          "compare_at_price": "89.00"
        }
      ],
      "prices": {
        "AUD": {
          "price": 89
        }
      },
      "created_date": "2026-11-01T00:00:00.000Z",
      "options": null,
      "normalised_stock": 12,
      "tags": [
        "summer"
      ],
      "image": "https://cdn.shopify.com/s/files/1/0000/0001/files/linen-shirt.jpg",
      "images": [
        "https://cdn.shopify.com/s/files/1/0000/0001/files/linen-shirt.jpg"
      ],
      "related": "string",
      "imploded": [
        {
          "id": "7712345678901",
          "title": "Linen shirt",
          "implode": 1,
          "handle": "linen-shirt",
          "min_price": 89,
          "max_price": 89,
          "compare_at_min_price": 89,
          "compare_at_max_price": 89,
          "vendor": "Mercury Apparel",
          "type": "Shirts",
          "on_sale": false,
          "total_stock": 12,
          "variants": [
            {
              "title": "Linen shirt",
              "id": 7712345678901,
              "inventory": 12,
              "price": "89.00",
              "compare_at_price": "89.00"
            }
          ],
          "prices": {
            "AUD": {
              "price": null
            }
          },
          "created_date": "2026-11-01T00:00:00.000Z",
          "tags": [
            "summer"
          ]
        }
      ],
      "meta": {
        "key": null
      }
    }
  ],
  "query": [
    {
      "type": "Shirts",
      "condition": "string",
      "value": null
    }
  ],
  "search": "linen",
  "redirect": "string",
  "grid_config": {
    "grid": {
      "elements": {
        "key": null
      },
      "core": {
        "key": null
      },
      "breakpoints": [
        {
          "index": 1,
          "label": "string",
          "minwidth": 1,
          "columns": 1,
          "format": "string"
        }
      ],
      "currentBreakpoint": {
        "key": null
      },
      "styles": "string"
    },
    "currency": "AUD",
    "locale": "string",
    "delimiter": "string",
    "sizeMapping": null,
    "colourMapping": {
      "key": "#1f6feb"
    },
    "imageMapping": {
      "key": "string"
    },
    "facetMapping": null,
    "integrations": null,
    "skuSearch": null
  }
}

401 No valid credential. application/json

Type: ApiErrorResponse

default An error, in the standard envelope. application/json

Type: ApiErrorResponse

Errors use the standard envelope; see errors and status codes.

Example request

curl "https://mercury.plutocracy.io/search/query/linen?bypassToken=$MERCURY_BYPASS_TOKEN"

Where this comes from

Contract: SearchQueryRoute in api-types/src/storefront/search.ts
Route: GET /search/query/:term on the view app