{ "openapi": "3.0.0", "info": { "version": "0.1.0", "title": "Intelligent Search API v1", "description": "[VTEX Intelligent Search](https://help.vtex.com/docs/tracks/overview-intelligent-search) is search solution for digital commerce that delivers relevant product results, autocomplete suggestions, and personalized experiences based on the catalog from the user's first interaction with the store. This API enables headless implementations to integrate VTEX Intelligent Search capabilities into custom storefronts.\r\n\r\nThis reference documents **Intelligent Search API v1**, which replaces the [Intelligent Search API (Legacy)](https://developers.vtex.com/docs/api-reference/intelligent-search-api) at `/api/io/_v/api/intelligent-search/*`.\r\n\r\n>ℹ️ If you are migrating from the legacy API, see [Migrating to Intelligent Search API v1](https://developers.vtex.com/docs/guides/migrating-to-intelligent-search-api-v1).\r\n\r\n## Common Parameters\r\n\r\n| Parameter | Description |\r\n| --- | --- |\r\n| `{{accountName}}` | Name of your VTEX account. Used in the base URL. |\r\n| `{{environment}}` | Environment to use. Typically `vtexcommercestable` for production. |", "license": { "name": "MIT" } }, "servers": [ { "url": "https://{accountName}.{environment}.com.br/api/intelligent-search/v1", "description": "VTEX Intelligent Search v1 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": "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/docs/tutorials/autocomplete) guide.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Autocomplete" ], "parameters": [ { "$ref": "#/components/parameters/locale" } ], "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 } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/autocomplete-suggestions": { "get": { "summary": "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/docs/tutorials/autocomplete) guide.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\n\nIf `query` is missing or empty, the response is `{ \"searches\": [] }`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "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": "department", "value": "tvs-and-video", "labelKey": "Department", "labelValue": "TVs and Video" } ] }, { "term": "smarth tv", "count": 2308 }, { "term": "rack tv", "count": 589 } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/search-suggestions": { "get": { "summary": "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/docs/tutorials/autocomplete) guide.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\n\nIf `query` is missing, empty, or whitespace-only, the response is `{ \"searches\": [] }`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "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 } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/correction-search": { "get": { "summary": "Get attempt of correction of a misspelled term", "description": "Tries to correct a misspelled term from the search.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\n\nIf `query` is missing, empty, or whitespace-only, the response is `{\"correction\": {\"correction\": false, \"misspelled\": false, \"text\": \"\", \"highlighted\": \"\"}}`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "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 bike" } } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/banners/{facets}": { "get": { "summary": "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\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "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": "