Site search for AI agents: a GET URL that returns products

Why it matters for AI agents

When a shopper asks an AI agent for “navy wool socks under $20 from this store”, the agent’s first move is a search. If your search is a URL, GET /search?q=navy+wool+socks, the agent gets a results page with product links in one request, from any kind of client: a browser agent, a text-only fetcher, or a coding tool.

If search only exists as a JavaScript widget, the agent has to load a browser, find the input, type, and wait for an autocomplete dropdown, which is exactly the kind of custom widget agents struggle to operate. Text-only agents can’t search at all.

Two signals tell an agent where your search lives:

• A search form in the HTML: <form role="search" method="get" action="/search">, or the HTML <search> element.
• WebSite SearchAction JSON-LD with a urlTemplate. Google retired the sitelinks search box in 2024, so this markup no longer changes Google results, but it is still an explicit description of your search URL.

What the scanner checks

The scanner looks at the homepage for a WebSite SearchAction in JSON-LD first, then for a search <form>: one with a type="search" input or an input named q, s, query, search, search_query, keyword, keywords or term. Hidden inputs in the form are kept in the URL.

It then runs a real search. The search term is the first word of three or more letters from a sampled product’s name (or “shirt” if none), and the URL comes from the form if it uses GET, otherwise from known search URL patterns used by common ecommerce platforms (such as /search?q=). Search works when the results page returns 200 and contains product links (/products/…, /product/…, /p/… and similar) or ItemList / SearchResultsPage JSON-LD.

Result	When
Pass	A GET search form or SearchAction is found, and the search URL returns product results
Partial	Search works at a URL but no form or SearchAction advertises it, or a form exists (POST, or GET without working results)
Fail	No search form or SearchAction, and the default search URL returns no product results
Inconclusive	The homepage could not be loaded

How to fix it

1. Serve a search results page at a GET URL that renders results on the server, with links to product pages.
2. Put a real search form in the site header. JavaScript instant search can enhance it but must not replace it:

<form role="search" method="get" action="/search">
  <label for="q">Search products</label>
  <input id="q" type="search" name="q" />
  <button type="submit">Search</button>
</form>

3. Add WebSite SearchAction JSON-LD on the homepage:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "WebSite",
    "url": "https://shop.example.com/",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://shop.example.com/search?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  }
</script>

4. Don’t block /search for AI agents in robots.txt (see robots.txt for AI agents).
5. Verify: curl -s "https://shop.example.com/search?q=socks" | grep -o 'href="/products/[^"]*"' | head prints product links.

Common mistakes

• Search forms that POST, so results can’t be linked or fetched directly.
• Results pages that render an empty shell and load results with client-side JavaScript.
• A search URL that ignores the query and returns the same featured products for every term.

How to fix it on Medusa

Medusa’s DTC starter has a client-side search drawer but no GET results page. To pass:

1. Add a /[countryCode]/search route that reads q from the URL, calls the Store API’s list products route with the q parameter (filter products by keyword), and renders the product links on the server. Store API requests need the x-publishable-api-key header (publishable API keys).
2. Put a <form role="search" method="get"> that targets that route in the header, and keep the drawer as an enhancement.
3. Add the WebSite SearchAction JSON-LD above to the root layout.

For relevance beyond keyword matching, Medusa Search adds full-text and semantic search on Medusa Cloud plans. Either way, the results page must stay reachable at a GET URL. See the Medusa agent-readiness guide for the full checklist.

Sources

• MDN: the search element and role=search
• schema.org SearchAction
• Google: farewell to the sitelinks search box
• Medusa Store API: list products
• Medusa: list products and filter by keyword