VTEX Intelligent Search API

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 Specification

vtex-intelligent-search-openapi-original.yml Raw ↑
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