Identify your siteId from the Searchspring Management Console (SMC); the REST base URL for your store is https://{siteId}.a.searchspring.io.
If your account uses Personalized Search, call the Preflight API (GET /api/personalization/getPersonalizationData) before a search or autocomplete call; pass userId (from ssUserId cookie), sessionId (from ssSessionIdNamespace cookie), and cart (current cart item IDs). This primes the personalization engine.
Send the search request to GET /api/search/search.json with parameters q (query), siteId, userId, sessionId, page, resultsPerPage, and any bgfilter.field[]=value pairs for background filters.
Parse the response: the results array contains matched products, the facets array contains available filter options with counts, and the merchandising object contains any active campaign data.
For autocomplete, call GET /api/suggest/query.json with the partial query string; the response includes suggested queries and optionally inline product results.
Known gotchas
If siteId or the shopper context parameters are missing, the API returns an error with the message 'ShopperContext is invalid' — always pass siteId on every request.
The Preflight call is required before search or autocomplete when your account has Personalized Search & Merchandising enabled; skipping it means the personalization data is not available for ranking.
Searchspring API authentication uses HTTP Basic Auth where the username is the siteId and the password is the secret key from your account — make these calls server-side or via a proxy to avoid exposing credentials.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp