VTEX Autocomplete API

openapi: 3.2.0
info:
  title: Vtex Autocomplete API
  version: '1.0'
  description: 'Operations tagged Autocomplete across 2 of this provider''s published API definitions: vtex-intelligent-search-openapi-original.yml, vtex-legacy-search-openapi-original.yml. Each path carries the servers of the definition it was published in.'
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
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
tags:
- name: Autocomplete
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.


        For more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4gXFsEWjF7QF7UtI2GAvhL) guide.


        This 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'
    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
  /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.


        For more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4gXFsEWjF7QF7UtI2GAvhL) guide.


        This 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'
    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
  /search_suggestions:
    get:
      summary: VTex Get list of suggested terms similar to the search term
      description: 'Lists suggested terms similar to the search term.


        For more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4gXFsEWjF7QF7UtI2GAvhL) guide.


        This 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'
    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
  /buscaautocomplete:
    get:
      tags:
      - Autocomplete
      summary: VTex Product Search Autocomplete
      description: 'Retrieves product''s information related to the searched string.

        `{{searchString}} is the part of string the user is looking for.

        E.g.: `ref` | `refrig` | `refrigerator`'
      operationId: AutoComplete
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent
        required: true
        style: simple
        schema:
          type: string
          example: application/json
      - name: Accept
        in: header
        description: 'HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand '
        required: true
        style: simple
        schema:
          type: string
          example: application/json
      - name: productNameContains
        in: query
        description: Part of the string that will be searched.
        required: true
        style: form
        explode: true
        schema:
          type: string
          example: jeans
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: The root schema comprises the entire JSON document.
                example:
                  itemsReturned:
                  - items: []
                    thumb: ''
                    thumbUrl: null
                    name: Cacilds in Coronas
                    href: https://merch.vtexcommercestable.com.br/coronas/Cacilds
                    criteria: £Cacilds in Coronas¢/coronas/Cacilds
                  - items:
                    - productId: '3'
                      itemId: '5'
                      name: Llf
                      nameComplete: Cacilds Llf
                      imageUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                    thumb: <img src="https://merch.vteximg.com.br/arquivos/ids/155400-25-25/image-433ec3e72d7e4b94964481e843c9dd88.jpg?v=637172099619830000" width="25" height="25" alt="image-433ec3e72d7e4b94964481e843c9dd88" id="" />
                    thumbUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                    name: cacilds - llf
                    href: https://merch.vtexcommercestable.com.br/bay-max-3/p
                    criteria: null
                required:
                - itemsReturned
                properties:
                  itemsReturned:
                    type: array
                    description: Autocomplete returned items.
                    example:
                    - items: []
                      thumb: ''
                      thumbUrl: null
                      name: Cacilds in Coronas
                      href: https://merch.vtexcommercestable.com.br/coronas/Cacilds
                      criteria: £Cacilds in Coronas¢/coronas/Cacilds
                    - items:
                      - productId: '3'
                        itemId: '5'
                        name: Llf
                        nameComplete: Cacilds Llf
                        imageUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                      thumb: <img src="https://merch.vteximg.com.br/arquivos/ids/155400-25-25/image-433ec3e72d7e4b94964481e843c9dd88.jpg?v=637172099619830000" width="25" height="25" alt="image-433ec3e72d7e4b94964481e843c9dd88" id="" />
                      thumbUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                      name: cacilds - llf
                      href: https://merch.vtexcommercestable.com.br/bay-max-3/p
                      criteria: null
                    items:
                      type: object
                      example:
                        items: []
                        thumb: ''
                        thumbUrl: null
                        name: Cacilds in Coronas
                        href: https://merch.vtexcommercestable.com.br/coronas/Cacilds
                        criteria: £Cacilds in Coronas¢/coronas/Cacilds
                      required:
                      - items
                      - thumb
                      - thumbUrl
                      - name
                      - href
                      - criteria
                      properties:
                        items:
                          type: array
                          description: Array of products.
                          example:
                          - productId: '3'
                            itemId: '5'
                            name: Llf
                            nameComplete: Cacilds Llf
                            imageUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                          properties:
                            productId:
                              type: string
                              description: Product ID.
                              example: '1'
                            itemId:
                              type: string
                              description: Item ID.
                              example: '3'
                            name:
                              type: string
                              description: Product name.
                              example: Llf
                            nameComplete:
                              type: string
                              description: Complete product name.
                              example: Cacilds Llf
                            imageUrl:
                              type: string
                              description: Product image URL.
                              example: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                        thumb:
                          type: string
                          description: Item thumbnail.
                          example: <img src="https://merch.vteximg.com.br/arquivos/ids/155400-25-25/image-433ec3e72d7e4b94964481e843c9dd88.jpg?v=637172099619830000" width="25" height="25" alt="image-433ec3e72d7e4b94964481e843c9dd88" id="" />
                        thumbUrl:
                          type:
                          - string
                          - 'null'
                          description: Item thumbnail URL.
                          example: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                        name:
                          type: string
                          description: Item name.
                          example: cacilds - llf
                        href:
                          type: string
                          description: Item URL.
                          example: https://merch.vtexcommercestable.com.br/bay-max-3/p
                        criteria:
                          type:
                          - string
                          - 'null'
                          description: Item criteria.
                          example: £Cacilds in Coronas¢/coronas/Cacilds
              example:
                itemsReturned:
                - items: []
                  thumb: ''
                  thumbUrl: null
                  name: Cacilds in Coronas
                  href: https://merch.vtexcommercestable.com.br/coronas/Cacilds
                  criteria: £Cacilds in Coronas¢/coronas/Cacilds
                - items:
                  - productId: '3'
                    itemId: '5'
                    name: Llf
                    nameComplete: Cacilds Llf
                    imageUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                  thumb: <img src="https://merch.vteximg.com.br/arquivos/ids/155400-25-25/image-433ec3e72d7e4b94964481e843c9dd88.jpg?v=637172099619830000" width="25" height="25" alt="image-433ec3e72d7e4b94964481e843c9dd88" id="" />
                  thumbUrl: https://merch.vteximg.com.br/arquivos/ids/172754-25-25/Diablo.jpg?v=637521970448770000
                  name: cacilds - llf
                  href: https://merch.vtexcommercestable.com.br/bay-max-3/p
                  criteria: null
      deprecated: false
      servers:
      - url: http://example.com/.{environment}.com.br
        variables:
          environment:
            default: DefaultParameterValue
      security:
      - appKey: []
        appToken: []
    servers:
    - url: https://{accountName}.{environment}.com.br
      description: VTEX server URL.
      variables:
        accountName:
          description: Name of the VTEX account. Used as part of the URL
          default: apiexamples
        environment:
          description: Environment to use. Used as part of the URL.
          enum:
          - vtexcommercestable
          default: vtexcommercestable
components:
  schemas:
    Error:
      type: object
      description: Response body object.
      required:
      - stack
      - message
      properties:
        message:
          type: string
          description: Error message.
        stack:
          type: string
          description: Error stack trace.
    AutocompleteSearchSuggestions:
      type: object
      description: Response body object.
      properties:
        searches:
          type: array
          description: List of suggested facets and terms.
          items:
            type: object
            description: Suggested facet or term.
            properties:
              term:
                type: string
                description: Search term.
              count:
                type: number
                description: Number of times the term was searched.
              attributes:
                type:
                - array
                - 'null'
                description: List of facets in which the term can be searched.
                items:
                  type: object
                  description: Facet information.
                  properties:
                    key:
                      type: string
                      description: Facet key.
                    value:
                      type: string
                      description: Facet value.
                    labelKey:
                      type: string
                      description: Human-readable format of the facet key.
                    labelValue:
                      type: string
                      description: Human-readable format of the facet value.
    SearchSuggestions:
      type: object
      description: Response body object.
      properties:
        searches:
          type: array
          description: List of suggested terms.
          items:
            type: object
            description: Suggested term.
            properties:
              term:
                type: string
                description: Search term.
              count:
                type: number
                description: Number of times the term was searched.
    TopSearches:
      type: object
      description: Response body object.
      properties:
        searches:
          type: array
          description: List of the 10 most searched terms in the past 14 days.
          minItems: 10
          maxItems: 10
          items:
            type: object
            description: Term information.
            properties:
              term:
                type: string
                description: Search term.
              count:
                type: number
                description: Number of times the term was searched.
  parameters:
    query:
      in: query
      name: query
      description: Search term. It can contain any character.
      schema:
        type: string
        example: shirt
    locale:
      in: query
      name: locale
      description: Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.
      example: en-US
      schema:
        type:
        - string
        - 'null'
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
x-refined-from:
- vtex-intelligent-search-openapi-original.yml
- vtex-legacy-search-openapi-original.yml