> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glood.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search APIs

> Versioned, Bearer-authenticated headless APIs for AI-powered search and discovery

Glood.AI Search APIs expose the storefront search and discovery engine as a set of
**versioned, self-contained headless APIs** (`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:

| Header | Value |
| - | - |
| `Authorization` | `Bearer <gl_sf_...>` storefront token |
| `x-shop` | `your-store.myshopify.com` (the shop is resolved from this header only) |

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.

> [!NOTE]
>
> 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.

| Purpose | Base URL |
| - | - |
| Default (global) | `https://search.glood.ai` |
| Edge (regional) | `https://<region>.edge.glood.ai` |

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 — swap `search.glood.ai` for `<region>.edge.glood.ai` and
nothing else changes. Available regions:

| Region | Base URL |
| - | - |
| Mumbai | `https://mum.edge.glood.ai` |
| Toronto | `https://tor.edge.glood.ai` |

Edge must be turned on for the shop from the Glood admin before these hosts serve results —
see [Enable Edge Delivery](https://docs.glood.ai/ai-search-merchandising/enable-edge-delivery.md) for the steps and the
regions available.

> [!NOTE]
>
> 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

> [card] [Init](https://docs.glood.ai/api-reference/search/headless/init.md)
>
> Session bootstrap — resolve the visitor, load their history, and get lean feature flags + the storefront token in one call.

> [card] [Config](https://docs.glood.ai/api-reference/search/headless/config.md)
>
> Feature flags, filter definitions, filter tree, shop, analytics, translations and the storefront token.

> [card] [Instant Search](https://docs.glood.ai/api-reference/search/headless/instant-search.md)
>
> Type-ahead products / collections / pages / articles + suggestions + autocorrect + trending.

> [card] [Filters](https://docs.glood.ai/api-reference/search/headless/filters.md)
>
> DB-driven facet (filter) definitions for the resolved tree — no live counts.

> [card] [Filter Aggregations](https://docs.glood.ai/api-reference/search/headless/filter-aggregations.md)
>
> Live Elasticsearch facet counts for a query + applied filters.

> [card] [Search](https://docs.glood.ai/api-reference/search/headless/search.md)
>
> Full hybrid (text + vector) product search with facets, sort, pagination and inline aggregations.

> [card] [Image Search](https://docs.glood.ai/api-reference/search/headless/image-search.md)
>
> Visual search from a multipart file, base64 image, data: URL, or http(s) image URL.

> [card] [Events](https://docs.glood.ai/api-reference/search/headless/events.md)
>
> Ingest standard Shopify events and custom `glood:search:*` attribution events.

## Using the SDK

If you build on Shopify Hydrogen, the [`@glood/hydrogen` Search SDK](https://docs.glood.ai/for-developers/glood-hydrogen-sdk/search)
wraps every endpoint with typed hooks (`useSearch`, `useInstantSearch`, `useSearchConfig`),
standalone `fetch*` functions for SSR, and automatic event forwarding.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.