Search

Admin configuration, indexing, and storefront runtime search operations.

Audience: Teams managing search quality, reindex workflows, and query analytics for storefronts.

Critical: Admin configuration endpoints are authenticated under /api/v1/search/*, while storefront querying and logging are served under /api/v1/public/sites/:siteKey/* endpoints.

Synonyms Redirects Boost Rules Zero Results

Who This Page Is For

Use this page to understand the complete search contract: configuration, reindexing, admin support utilities, and public runtime search APIs.

Quick Start (2-5 Minutes)

Load current search config

Read site-level search behavior before making updates.

GET /api/v1/search/config/:siteId

Update search config

Apply ranking/filter/display behavior through config endpoint.

PUT /api/v1/search/config/:siteId

Trigger full reindex

Rebuild search corpus after catalog or mapping changes.

POST /api/v1/search/:siteId/reindex

Validate runtime query path

Check public storefront search results endpoint response shape.

GET /api/v1/public/sites/:siteKey/search?q=headphones

Inspect search analytics stream

Use site search analytics endpoints for quality tuning.

GET /api/v1/sites/:siteId/search/analytics/queries

Admin + runtime endpoints

GET  /api/v1/search/configs
GET  /api/v1/search/config/:siteId
PUT  /api/v1/search/config/:siteId
POST /api/v1/search/:siteId/reindex
GET  /api/v1/search/:siteId/stats
GET  /api/v1/search/:siteId/products
GET  /api/v1/search/:siteId/categories
GET  /api/v1/public/sites/:siteKey/search
GET  /api/v1/public/sites/:siteKey/search-config
GET  /api/v1/public/sites/:siteKey/search/suggestions
POST /api/v1/public/sites/:siteKey/search/log
POST /api/v1/public/sites/:siteKey/search/click
POST /api/v1/public/sites/:siteKey/search/zero-results

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	Admin endpoints	Site ownership boundary for config and indexing operations.
`q`	Required	`string`	Public search query	Search term sent to public search endpoint.
`limit`	Optional	`number`	Public search and analytics list endpoints	Result cap, bounded server-side for safety.
`category / minPrice / maxPrice / inStock`	Optional	`query params`	Public search filtering	Filter constraints for storefront result narrowing.
`search event payload fields`	Conditional	`object`	search/log, search/click, search/zero-results	Event-specific fields for query and click quality analytics.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need all site configs in organization	GET /api/v1/search/configs	Bulk operational view for multi-site teams.
Tune one site search behavior	PUT /api/v1/search/config/:siteId	Single source of truth for site search settings.
Refresh searchable index	POST /api/v1/search/:siteId/reindex	Rebuild index after product feed or mapping changes.
Serve storefront query results	GET /api/v1/public/sites/:siteKey/search	Public runtime endpoint with site/origin safety checks.
Improve ranking for missed intent	Use Search Advanced pages (synonyms/redirects/boost/zero-results)	Dedicated tooling for query quality optimization.

Common Errors and Fixes

Public search returns query required error

Cause: Missing q parameter or empty string sent from frontend.

Fix: Always send non-empty q and trim client input before request.

Reindex completed but results still stale

Cause: Catalog updates not reflected in product feed source yet.

Fix: Validate product feed ingestion first, then rerun reindex.

Search analytics appears sparse

Cause: search/log and click events not sent for all user actions.

Fix: Wire log/click/zero-results endpoints from runtime search UI.

Unexpected 403 on public search

Cause: Origin/domain mismatch or subscription validation failure.

Fix: Verify request origin, site domain setup, and subscription status.

Production Checklist

Search config endpoint is source of truth for runtime behavior.Required
Reindex is run after major catalog schema or data changes.Required
Storefront sends log, click, and zero-results tracking events.Required
Public search request limits and filters are bounded client-side.Required
Advanced quality controls are configured (synonyms, redirects, boost, zero-results).Required