The VTEX Intelligent Search API delivers AI-powered search and product discovery features for VTEX storefronts. It provides product search with faceted filtering, autocomplete suggestions, banners, product recommendations, and spelling correction powered by machine learning.
openapi: 3.0.0
info:
version: 0.1.12
title: VTex Intelligent Search API
description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Search onboarding guide](https://developers.vtex.com/docs/guides/search-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Search and is organized by focusing on the developer's journey.\r\n\r\n[VTEX Intelligent Search](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/3qgT47zY08biLP3d5os3DG) is a search solution for digital commerce that simply and intuitively displays relevant results based on the catalog from the user's first interaction with the store through the search bar, browsing categories, or even through the window displays.\r\n\r\n The tool also offers features such as autocomplete, displaying search and product suggestions based on the shopper's context, and filters that help when searching for the desired product.\r\n\r\n> ℹ️ VTEX Intelligent Search is an alternative to [VTEX search](https://help.vtex.com/en/tutorial/how-does-vtex-search-work--tutorials_542).\r\n\r\n## Index\r\n### Autocomplete\r\n - `GET` [Get list of the 10 most searched terms](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/top_searches)\r\n - `GET` [Get list of suggested terms and attributes similar to the search term](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/autocomplete_suggestions)\r\n - `GET` [Get list of suggested terms similar to the search term](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/search_suggestions)\r\n ### Product List Page\r\n - `GET` [Get attempt of correction of a misspelled term](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/correction_search)\r\n - `GET` [Get list of banners registered for query](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/banners/-facets-)\r\n - `GET` [Get list of products for a query](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/product_search/-facets-)\r\n - `GET` [Get list of the possible facets for a given query](https://developers.vtex.com/docs/api-reference/intelligent-search-api#get-/facets/-facets-)\r\n ## Common parameters \r\n\r\n| **Parameter name** | **Description** |\r\n| --------------- | ----------------- | \r\n| `{{accountName}}` | Name of the VTEX account. Used as part of the URL. | \r\n| ` {{environment}}` | Environment to use. Used as part of the URL. |"
license:
name: MIT
servers:
- url: https://{accountName}.{environment}.com.br/api/io/_v/api/intelligent-search
description: VTEX IO Intelligent Search server URL.
variables:
accountName:
default: apiexamples
description: Name of the VTEX account. Used as part of the URL.
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/top_searches:
get:
summary: VTex Get list of the 10 most searched terms
description: "Lists the 10 most searched terms in the past 14 days.\r\n\r\nFor more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4gXFsEWjF7QF7UtI2GAvhL) guide.\r\n\r\nThis endpoint does not require authentication."
parameters:
- $ref: '#/components/parameters/locale'
tags:
- Autocomplete
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TopSearches'
example:
searches:
- term: home
count: 14
- term: shirt
count: 10
- term: top
count: 9
- term: tops
count: 6
- term: camera
count: 5
- term: kit
count: 5
- term: work shirt
count: 2
- term: shirts
count: 2
- term: clothing
count: 2
- term: classic shoes
count: 1
5XX:
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/autocomplete_suggestions:
get:
summary: VTex Get list of suggested terms and attributes similar to the search term
description: "Lists the suggested terms and attributes similar to the search term.\r\n\r\nFor more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4gXFsEWjF7QF7UtI2GAvhL) guide.\r\n\r\nThis endpoint does not require authentication."
tags:
- Autocomplete
parameters:
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/locale'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AutocompleteSearchSuggestions'
example:
searches:
- term: tv
count: 28861
attributes:
- key: departamento
value: tvs-e-video
labelKey: Departamento
labelValue: TVs e Vídeo
- key: categoria
value: tvs
labelKey: Categoria
labelValue: TVs
- key: subcategoria
value: receptor-de-controle-de-acesso
labelKey: Subcategoria
labelValue: Receptor de Controle de Acesso
- term: smarth tv
count: 2308
- term: painel para tv
count: 975
- term: rack tv
count: 589
5XX:
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/correction_search:
get:
summary: VTex Get attempt of correction of a misspelled term
description: "Tries to correct a misspelled term from the search.\r\n\r\nThis endpoint does not require authentication."
tags:
- Product List Page
parameters:
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/locale'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Correction'
example:
correction:
correction: true
misspelled: true
text: mountain bike
highlighted: mountain <em>bike</em>
/banners/{facets}:
get:
summary: VTex Get list of banners registered for query
description: "Lists the banners registered for a given query. Check the [configuring banners documentation](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4ViKEivLJtJsvpaW0aqIQ5) for a full explanation of the banner feature.\r\n\r\nThis endpoint does not require authentication."
tags:
- Product List Page
parameters:
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/facetsPath'
- $ref: '#/components/parameters/locale'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Banners'
example:
banners:
- id: summersale
name: Summer Sale
area: '1'
html: <h1>This is a test</h1>
/search_suggestions:
get:
summary: VTex Get list of suggested terms similar to the search term
description: "Lists suggested terms similar to the search term.\r\n\r\nFor more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4gXFsEWjF7QF7UtI2GAvhL) guide.\r\n\r\nThis endpoint does not require authentication."
tags:
- Autocomplete
parameters:
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/locale'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchSuggestions'
example:
searches:
- term: mountain bike
count: 66
- term: bike helmet
count: 121
- term: electric bike
count: 78
- term: bike rack
count: 161
- term: road bike
count: 28
5XX:
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/product_search/{facets}:
get:
summary: VTex Get list of products for a query
description: "Lists the active products for a given query.\r\n\r\nThis endpoint does not require authentication."
tags:
- Product List Page
parameters:
- $ref: '#/components/parameters/facetsPath'
- $ref: '#/components/parameters/query'
- in: query
name: simulationBehavior
schema:
type: string
enum:
- default
- skip
- only1P
nullable: true
default: default
description: |-
Defines the simulation behavior.
* `default` - Calls the simulation for every single seller.
* `skip` - Never calls the simulation.
* `only1P` - Only calls the simulation for first party sellers.
- in: query
name: count
description: Number of products per page.
schema:
type: number
nullable: true
default: 24
- in: query
name: page
description: Current search page.
schema:
type: number
nullable: true
default: 1
- in: query
name: sort
description: "Defines the sort type. The possible values are: \r\n- `price:desc`: The results will be sorted by price in descending order, from highest to lowest.\r\n- `price:asc`: The results will be sorted by price in ascending order, from lowest to highest.\r\n- `orders:desc`: The results will be sorted by the amount of orders in the past 90 days, in descending order.\r\n- `name:desc`: The results will be sorted by name in descending alphabetical order.\r\n- `name:asc`: The results will be sorted by name in ascending alphabetical order.\r\n- `release:desc`: The results will be sorted by release date in descending order, from most recent to least recent.\r\n- `discount:desc`: The results will be sorted by discount percentage in descending order, from highest to lowest.\r\n\r\nIf `null`, the products will be sorted by relevance."
schema:
type: string
nullable: true
enum:
- price:desc
- price:asc
- orders:desc
- name:desc
- name:asc
- release:desc
- discount:desc
example: price:desc
- $ref: '#/components/parameters/locale'
- $ref: '#/components/parameters/hideUnavailableItems'
responses:
'200':
description: List of products for the given query.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductSearch'
example:
products:
- cacheId: sp-2000003
productId: '2000003'
description: Introducing our exquisite Top Wood Clock, a timeless blend of elegance and craftsmanship. Crafted from premium-quality wood, this clock seamlessly combines functionality with aesthetic appeal. Its sleek design and rich wood finish make it a sophisticated addition to any space, from classic to contemporary interiors.
productName: Top Wood Clock
productReference: clock120
linkText: wood-clock
brand: Sony
brandId: 2000005
link: /wood-clock/p
categories:
- /Home & Decor/
categoryId: '40'
categoriesIds:
- /40/
priceRange:
sellingPrice:
highPrice: 197.99
lowPrice: 197.99
listPrice:
highPrice: 197.99
lowPrice: 197.99
specificationGroups:
- originalName: allSpecifications
name: allSpecifications
specifications:
- originalName: sellerId
name: sellerId
values:
- '1'
skuSpecifications: []
productClusters:
- id: '1970'
name: Summer
clusterHighlights:
- id: '1970'
name: Summer
properties:
- name: sellerId
originalName: sellerId
values:
- '1'
items:
- sellers:
- sellerId: '1'
sellerName: VTEX
addToCartLink: ''
sellerDefault: true
commertialOffer:
DeliverySlaSamplesPerRegion: {}
DeliverySlaSamples: []
AvailableQuantity: 10000
discountHighlights: []
Installments:
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: American Express à vista
PaymentSystemName: American Express
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Visa à vista
PaymentSystemName: Visa
- Value: 98.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 2
Name: Visa 2 vezes sem juros
PaymentSystemName: Visa
- Value: 65.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 3
Name: Visa 3 vezes sem juros
PaymentSystemName: Visa
- Value: 49.49
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 4
Name: Visa 4 vezes sem juros
PaymentSystemName: Visa
- Value: 39.59
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 5
Name: Visa 5 vezes sem juros
PaymentSystemName: Visa
- Value: 32.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 6
Name: Visa 6 vezes sem juros
PaymentSystemName: Visa
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Diners à vista
PaymentSystemName: Diners
- Value: 100.48
InterestRate: 100
TotalValuePlusInterestRate: 200.96
NumberOfInstallments: 2
Name: Diners 2 vezes com juros
PaymentSystemName: Diners
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Mastercard à vista
PaymentSystemName: Mastercard
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Boleto Bancário à vista
PaymentSystemName: Boleto Bancário
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Vale à vista
PaymentSystemName: Vale
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Promissory à vista
PaymentSystemName: Promissory
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Customer Credit à vista
PaymentSystemName: Customer Credit
- Value: 98.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 2
Name: Customer Credit 2 vezes sem juros
PaymentSystemName: Customer Credit
- Value: 67.97
InterestRate: 100
TotalValuePlusInterestRate: 203.91
NumberOfInstallments: 3
Name: Customer Credit 3 vezes com juros
PaymentSystemName: Customer Credit
- Value: 197.99
InterestRate: 0
TotalValuePlusInterestRate: 197.99
NumberOfInstallments: 1
Name: Free à vista
PaymentSystemName: Free
Price: 197.99
ListPrice: 197.99
spotPrice: 197.99
taxPercentage: 0
PriceWithoutDiscount: 197.99
Tax: 0
GiftSkuIds: []
BuyTogether: []
ItemMetadataAttachment: []
RewardValue: 0
PriceValidUntil: '2023-04-01T13:13:20Z'
GetInfoErrorMessage:
CacheVersionUsedToCallCheckout: ''
teasers:
- name: 8% Boleto
conditions:
minimumQuantity: 0
parameters:
- name: PaymentMethodId
value: '6'
effects:
parameters:
- name: PercentualDiscount
value: '8.0'
images:
- imageId: '155484'
cacheId: '155484'
imageTag: ''
imageLabel: ''
imageText: ''
imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155484/Frame.jpg?v=636793817478300000
- imageId: '155485'
cacheId: '155485'
imageTag: ''
imageLabel: ''
imageText: ''
imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155485/Frame-1.jpg?v=636793817642000000
- imageId: '155486'
cacheId: '155486'
imageTag: ''
imageLabel: ''
imageText: ''
imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155486/Frame-2.jpg?v=636793817785530000
itemId: '2000534'
name: '1'
nameComplete: Top Wood Clock 1
complementName: ''
referenceId:
- Key: RefId
Value: '16001'
measurementUnit: un
unitMultiplier: 1
variations: []
ean: '16001'
modalType: ''
videos: []
attachments: []
isKit: false
origin: intelligent-search
- cacheId: sp-2000214
productId: '2000214'
description: ''
productName: kevin1
linkText: kevin1-lkn
brand: Sony
brandId: 2000005
link: /kevin1-lkn/p
categories:
- /Home & Decor/
categoryId: '40'
categoriesIds:
- /40/
priceRange:
sellingPrice:
highPrice: 10
lowPrice: 10
listPrice:
highPrice: 10
lowPrice: 10
specificationGroups:
- originalName: allSpecifications
name: allSpecifications
specifications:
- originalName: sellerId
name: sellerId
values:
- '1'
skuSpecifications: []
productClusters: []
clusterHighlights: []
properties:
- name: sellerId
originalName: sellerId
values:
- '1'
items:
- sellers:
- sellerId: '1'
sellerName: VTEX
addToCartLink: ''
sellerDefault: true
commertialOffer:
DeliverySlaSamplesPerRegion: {}
DeliverySlaSamples: []
AvailableQuantity: 10000
discountHighlights: []
Installments:
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: American Express à vista
PaymentSystemName: American Express
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Visa à vista
PaymentSystemName: Visa
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Diners à vista
PaymentSystemName: Diners
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Mastercard à vista
PaymentSystemName: Mastercard
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Boleto Bancário à vista
PaymentSystemName: Boleto Bancário
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Vale à vista
PaymentSystemName: Vale
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Promissory à vista
PaymentSystemName: Promissory
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Customer Credit à vista
PaymentSystemName: Customer Credit
- Value: 5
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 2
Name: Customer Credit 2 vezes sem juros
PaymentSystemName: Customer Credit
- Value: 3.43
InterestRate: 100
TotalValuePlusInterestRate: 10.29
NumberOfInstallments: 3
Name: Customer Credit 3 vezes com juros
PaymentSystemName: Customer Credit
- Value: 10
InterestRate: 0
TotalValuePlusInterestRate: 10
NumberOfInstallments: 1
Name: Free à vista
PaymentSystemName: Free
Price: 10
ListPrice: 10
spotPrice: 10
taxPercentage: 0
PriceWithoutDiscount: 10
Tax: 0
GiftSkuIds: []
BuyTogether: []
ItemMetadataAttachment: []
RewardValue: 0
PriceValidUntil: '2023-04-01T13:13:20Z'
GetInfoErrorMessage:
CacheVersionUsedToCallCheckout: ''
teasers:
- name: 8% Boleto
conditions:
minimumQuantity: 0
parameters:
- name: PaymentMethodId
value: '6'
effects:
parameters:
- name: PercentualDiscount
value: '8.0'
images:
- imageId: '155675'
cacheId: '155675'
imageTag: ''
imageLabel: vtex
imageText: vtex
imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155675/vtex.jpg?v=637655270451200000
itemId: '310124211'
name: kevin1sku
nameComplete: kevin1sku
complementName: ''
referenceId:
- Key: RefId
Value: 2983678w63478
measurementUnit: un
unitMultiplier: 1
variations: []
ean: '2398428937489'
modalType: ''
videos: []
attachments: []
isKit: false
origin: intelligent-search
recordsFiltered: 5
correction:
misspelled: false
fuzzy: '0'
operator: and
translated: false
/facets/{facets}:
get:
summary: VTex Get list of the possible facets for a given query
description: "Lists the possible facets for a given query.\r\n\r\nThis endpoint does not require authentication."
tags:
- Product List Page
parameters:
- $ref: '#/components/parameters/facetsPath'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/locale'
- $ref: '#/components/parameters/hideUnavailableItems'
responses:
'200':
description: List of facets for the given query.
content:
application/json:
schema:
$ref: '#/components/schemas/Facets'
example:
facets:
- values:
- id
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-intelligent-search-openapi-original.yml