POST /api/storefront/v1/headless/*).
Consumers — the @glood/hydrogen SDK, mobile apps, and custom storefronts — call them
directly and get everything they need in one response (full product objects, facets,
pagination), with no re-hydration from Shopify required.
Authentication
Every endpoint requires two headers:
Request and response bodies are snake_case. Product-returning endpoints accept a
view of product_details (default) or product_ids, and an optional identity triple
(visitor_id, client_id, customer_id) for personalization.
Send the same anonymous
visitor_id before and after login, and add customer_id
when the shopper is authenticated. Never overwrite visitor_id with the customer id —
the two are linked server-side into one visitor profile.Base URLs
Search runs on its own host, independent of the recommendations API. Every endpoint is a path (/api/storefront/v1/headless/*) on one of these hosts — the path, headers, and
request/response bodies are identical regardless of which host you call. Only the origin
changes. These are the same URLs the Glood Search Shopify app embed uses, so a headless
integration and a theme integration hit exactly the same routes.
Use the default host unless you have been asked to route to the edge. Point your client at
one base URL and prefix it to every endpoint path, e.g.
POST https://search.glood.ai/api/storefront/v1/headless/search.
Edge URLs
Edge hosts serve requests from a location close to the shopper for lower latency. They expose the same routes as the default host — swapsearch.glood.ai for <region>.edge.glood.ai and
nothing else changes. Available regions:
Edge must be turned on for the shop from the Glood admin before these hosts serve results —
see Enable Edge Delivery for the steps and the
regions available.
Add whichever host(s) you call to your Content Security Policy
connect-src — the default
https://search.glood.ai and/or any https://<region>.edge.glood.ai you route to — or the
browser blocks the requests.Endpoints
Init
Session bootstrap — resolve the visitor, load their history, and get lean feature flags + the storefront token in one call.
Config
Feature flags, filter definitions, filter tree, shop, analytics, translations and the storefront token.
Instant Search
Type-ahead products / collections / pages / articles + suggestions + autocorrect + trending.
Filters
DB-driven facet (filter) definitions for the resolved tree — no live counts.
Filter Aggregations
Live Elasticsearch facet counts for a query + applied filters.
Search
Full hybrid (text + vector) product search with facets, sort, pagination and inline aggregations.
Image Search
Visual search from a multipart file, base64 image, data: URL, or http(s) image URL.
Events
Ingest standard Shopify events and custom
glood:search:* attribution events.Using the SDK
If you build on Shopify Hydrogen, the@glood/hydrogen Search SDK
wraps every endpoint with typed hooks (useSearch, useInstantSearch, useSearchConfig),
standalone fetch* functions for SSR, and automatic event forwarding.