The new Intelligent Search API v1 is now available for headless integrations at /api/intelligent-search/v1/*. It replaces Intelligent Search API (Legacy) at /api/io/_v/api/intelligent-search/* with HTTP caching, lower latency, and explicit context parameters.

Here is a summary of the key differences between Intelligent Search API (Legacy) and Intelligent Search API v1. See the sections below for full details.

	Intelligent Search API (Legacy)	Intelligent Search API v1
HTTP caching	Not cached	Responses include a Cache-Control header; read it at runtime to determine cacheability.
Context	VTEX segment cookie	Explicit query parameters
Single-product lookup	Via product search pipeline	Dedicated GET /products endpoint
Base URL	/api/io/_v/api/intelligent-search	/api/intelligent-search/v1
Path format	endpoint_name (underscores)	endpoint-name (hyphens)
New items[] data	attachments[] always empty; no estimatedDateArrival or kitItems	attachments[] fully populated; new estimatedDateArrival and kitItems fields

Responses from most endpoints now include a Cache-Control header, enabling CDN and browser caching for public sales channels. This reduces origin load and improves storefront response times.

Always read the Cache-Control header at runtime to determine cacheability. Don't hardcode cache durations in your integration.

Exceptions:

• Responses containing sponsored products (VTEX Ads) are not cached, preventing ad impressions from being served from a shared cache.
• Private sales channel responses: not cached.

Intelligent Search API (Legacy) relied on the VTEX segment cookie to fill in locale, sales channel, regionalization, and marketing context. Intelligent Search API v1 does not read the segment cookie. All context must be passed explicitly as query parameters or facets in the URL path.

Context	Intelligent Search API (Legacy)	Intelligent Search API v1
Locale	Read from segment.cultureInfo	locale query parameter
Sales channel	Read from segment.channel	sc query parameter
Country	Read from segment.countryCode	country query parameter
Region	Read from segment.regionId	regionId query parameter
UTM / price tables	Read from segment.utm_source, utm_campaign, utmi_campaign, campaigns, priceTables	utmSource, utmCampaign, utmiCampaign, campaigns, priceTables query parameters

If your store uses Delivery Promise for headless stores, the following parameters were previously passed via the segment facets string and must now be passed as explicit query parameters on GET Search products (v1), GET List filters for a search (v1), and GET Get pickup point availability for Delivery Promise (v1):

• country, zip-code, and optionally coordinates (buyer's address, the fundamental parameters)
• deliveryZonesHash and pickupPointsHash (pre-computed alternative for faster lookup; hashes expire and require a specific renewal flow, so always have the address available as a fallback)
• pickupPoint

The IO prefix has been removed, underscores in path names have been replaced by hyphens, and /v1 has been added to the path.

Intelligent Search API (Legacy)	Intelligent Search API v1
GET /api/io/_v/api/intelligent-search/top_searches Get list of the 10 most searched terms	GET /api/intelligent-search/v1/top-searches Get list of the 10 most searched terms (v1)
GET /api/io/_v/api/intelligent-search/autocomplete_suggestions Get list of suggested terms and attributes similar to the search term	GET /api/intelligent-search/v1/autocomplete-suggestions Get list of suggested terms and attributes similar to the search term (v1)
GET /api/io/_v/api/intelligent-search/search_suggestions Get list of suggested terms similar to the search term	GET /api/intelligent-search/v1/search-suggestions Get list of suggested terms similar to the search term (v1)
GET /api/io/_v/api/intelligent-search/correction_search Get attempt of correction of a misspelled term	GET /api/intelligent-search/v1/correction-search Get attempt of correction of a misspelled term (v1)
GET /api/io/_v/api/intelligent-search/banners/{facets} Get list of banners registered for query	GET /api/intelligent-search/v1/banners/{facets} Get list of banners registered for query (v1)
GET /api/io/_v/api/intelligent-search/product_search/{facets} Get list of products for a query	GET /api/intelligent-search/v1/product-search/{facets} Search products (v1)
GET /api/io/_v/api/intelligent-search/facets/{facets} Get list of the possible facets for a given query	GET /api/intelligent-search/v1/facets/{facets} List filters for a search (v1)
GET /api/io/_v/api/intelligent-search/pickup-point-availability/{facets} Get pickup point availability for Delivery Promise	GET /api/intelligent-search/v1/pickup-point-availability/{facets} Get pickup point availability for Delivery Promise (v1)
N/A	GET /api/intelligent-search/v1/products Get product (v1)

A new GET Get product (v1) endpoint is now available for product detail pages (PDP). Given a known identifier (product ID, slug, EAN, SKU ID, or reference), it returns a single product without going through the search pipeline, resulting in lower latency and better cache-hit rates than GET Search products (v1).

Intelligent Search API v1 returns additional and corrected data in products[].items[] on the following endpoints:

• GET Search products (v1) (previously GET Get list of products for a query)
• GET Get product (v1) (new)

Field	Type	Description
items[].estimatedDateArrival	string	Estimated arrival date for the SKU, when configured.
items[].kitItems[]	array	Component SKUs when isKit is true. Each entry has itemId and amount.
items[].attachments[].id	number	Attachment unique identifier.
items[].attachments[].isRequired	boolean	Whether the attachment is required.
items[].attachments[].isActive	boolean	Whether the attachment is active.
items[].attachments[].schema	object	Free-form JSON schema describing the attachment.
items[].attachments[].fields[]	array	Array of { field_name, max_characters, domain_values }.

Fields that previously returned incorrect or empty values, such as isKit, modalType, and images[].imageText, now return correctly, potentially resolving a known issue.

For a step-by-step migration checklist, see Migrating to Intelligent Search API v1.

All new headless integrations must use Intelligent Search API v1.

Intelligent Search API (Legacy) remains available for existing integrations, but its endpoints will be deprecated in a future announcement. We recommend migrating existing integrations as soon as possible.

To access all performance and reliability improvements in Intelligent Search API v1, headless integrations should use the REST API directly. Integrations using Search GraphQL aren't recommended for headless implementations and should be migrated to Intelligent Search API v1.

• Intelligent Search API v1
• Intelligent Search API (Legacy)
• Migrating to Intelligent Search API v1