Use Search GraphQL for new storefront discovery.

Search covers product listings and detail reads, facets, category or collection browsing, brand or series browsing, redirects, variants, autocomplete, and operation documents. Use the Shopper API only when an existing client still depends on the deprecated public REST read surface.

When contract details matter, use Search GraphQL reference, raw SDL, generated documents, and package reference for fields, operation variables, fragments, nullability, enum values, and TypeScript types.

Start by job

• Choose between Search guidance, SDKs, and references from Search overview.
• Query from server code, integrations, scripts, or custom loaders with TypeScript SDK latest.
• Build PLP, search-results, filters, or autocomplete UI with React product listing and search.
• Check fields, variables, fragments, and enum values in Search GraphQL reference.
• Route API/Search agent work with API and Search agent guide.
• Move Search data into shopper-facing React UI with React SDK agent commerce and Search handoff.

Raw schema SDL lives at /graphql/search-schema.graphql; operation and fragment documents live at /graphql/search-documents.graphql.

MCP read surface

Enad MCP should expose GraphQL-backed search.* capabilities for catalog reads instead of adding new Shopper REST dependencies. Use search.* for discovery, product lookup, facets, category and collection browsing, redirects, autocomplete, and related read workflows.

Keep shopper.* MCP capabilities only as deprecated compatibility for existing Shopper REST read flows. If a workflow needs to mutate catalog, commerce, media, or identity state, route it through governed MCP mutation workflows and the api.enad.io API contract instead of Search.

Search endpoint and context

Enad Search is app-scoped. The app ID is part of the request URL, not only a GraphQL variable.

Endpoint shape:

https://graphql.enad.io/{appId}/graphql

Most storefront work also needs the same context your application uses:

• appId
• marketSlug
• storeGroupSlug
• locale

Keep market, store group, and locale together when reproducing a query in GraphiQL or wiring a React runtime. If a product, price, facet, or translation looks wrong, check context before changing query shape.

SDK surfaces

Search GraphQL is the contract. SDKs provide typed helpers around it.

Use the TypeScript SDK for server-side Search work. Use the React SDK to compose shopper-facing experiences. Check reference material before copying fields, variables, fragments, or generated types.

Agent handoffs

• Contract or route-selection tasks: API and Search agent guide.
• Search data flowing into React UI, pricing display, or purchase-adjacent flows: React SDK agent commerce and Search handoff.
• /llms.txt, /llms-full.txt, or /ai/manifest.json setup: Agent files.

Contract facts to keep in mind

Use these facts to choose the right reference. Use Search GraphQL reference, raw SDL, generated documents, and package reference for exact fields, variables, fragments, enum values, nullability, and result types.

• @enadhq/enad-ts-sdk/search is the lower-level package surface for server-side GraphQL reads. Start with createSearchClient() when package helpers fit.
• Search documents and generated types are exported from the package surfaces. Use them when an operation does not have a named helper or when custom transport is needed.
• Product and facet query variables can include top-level warehouseSlug. warehouseSlug is not a ProductFilter field.
• Top-level variables describe request context and query controls. ProductFilter describes product-filtering criteria.
• Search attribute values resolve as structured value objects rather than serialized JSON strings inside values.
• React SDK usage should keep provider context, data loading, and shopper UI composition separate. Use React SDK setup for the provider boundary and Product listing and search for PLP, filters, search results, and autocomplete.

Search GraphQL playground

Use the Search GraphQL playground to enter an app_id, introspect the live app-scoped schema, browse root fields and types, generate a starter operation, edit variables, and send one explicit request.

The playground is schema-introspecting for a specific app context. Use the Search reference, raw schema SDL, operation documents, and package reference before shipping production code.

GraphiQL workflow

Use app-scoped GraphiQL when you need to confirm query shape or field availability for one app:

https://graphql.enad.io/{appId}/graphiql

Recommended flow:

1. Start with the same marketSlug, storeGroupSlug, and locale used by the app.
2. Run a small product or facet query first.
3. Add warehouseSlug only as a top-level variable when the query supports it.
4. Add filters, sort, pagination, or autocomplete variables incrementally.
5. Move the stable operation into application code or generated package usage only after the GraphiQL result matches the target storefront behavior.

Reference checklist

Before documenting or implementing Search behavior, confirm:

• Does this job have a named SearchClient helper?
• If not, is there a generated document/type export for the operation?
• Are appId, marketSlug, storeGroupSlug, and locale explicit?
• Is warehouseSlug top-level rather than inside ProductFilter?
• Does the generated product, variant, or price fragment already include the needed field?
• For React Search UI, is provider context separate from component composition?