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

> Agent-friendly site search works through a plain GET URL, such as /search?q=socks, that returns a server-rendered results page with product links. AI agents can then search your catalog in one request instead of typing into a JavaScript widget, and learn the URL pattern from a search form or SearchAction markup.

- Source: https://is-agentic-storefront.com/checks/site-search
- Updated: 2026-10-15
- Category: Operability (20% of score)
- Impact: High
- Spec: [MDN role=search](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/search)
- Scanner check: Site search works through a GET URL

## 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/search).
- [WebSite SearchAction](https://schema.org/SearchAction) JSON-LD with a `urlTemplate`. Google [retired the sitelinks search box](https://developers.google.com/search/blog/2024/10/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:

```html
<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:

```html
<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](https://is-agentic-storefront.com/checks/robots-txt)).
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](https://github.com/medusajs/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](https://docs.medusajs.com/resources/storefront-development/products/list#filter-products)), and renders the product links on the server. Store API requests need the `x-publishable-api-key` header ([publishable API keys](https://docs.medusajs.com/resources/storefront-development/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](https://medusajs.com/blog/announcing-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](https://is-agentic-storefront.com/guides/medusa-agent-readiness) for the full checklist.

## Sources

- [MDN: the search element and role=search](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/search)
- [schema.org SearchAction](https://schema.org/SearchAction)
- [Google: farewell to the sitelinks search box](https://developers.google.com/search/blog/2024/10/sitelinks-search-box)
- [Medusa Store API: list products](https://docs.medusajs.com/api/store/products/list-products)
- [Medusa: list products and filter by keyword](https://docs.medusajs.com/resources/storefront-development/products/list#filter-products)

## Frequently asked questions

### How do AI agents search an online store?

Browser agents can type into a search box, but the faster and more reliable path is to request a search URL directly, such as /search?q=wool+socks. That only works when search results are available at a GET URL and rendered on the server.

### Does JavaScript instant search work for AI agents?

Only for agents that run a full browser, and even then autocomplete dropdowns are fragile to operate. Keep a regular GET search form and results page underneath the instant search.

### Is SearchAction structured data still useful?

Google retired the sitelinks search box in 2024, so it no longer affects Google results. It still documents your search URL pattern in a machine-readable way, and the scanner uses it to find your search URL.

## Run your store on a platform built for agentic commerce

Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.

### Deploy on Medusa Cloud

Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.

- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fsite-search)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Fsite-search)

### Storefront skills for coding agents

Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.

```bash
npx skills add medusajs/medusa-agent-skills
```

[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)

---

Scan your store for free at https://is-agentic-storefront.com/