{"openapi":"3.1.0","info":{"title":"VTEX (BYOK) API","version":"0.1.0","description":"VTEX (BYOK) lets an AI assistant read your own VTEX data through the VTEX API with a key you supply (VTEX app key). Read-only: 11 tools (list_orders, get_order, list_product_and_sku_ids, get_product, get_sku, get_sku_inventory, get_category_tree, get_category, list_brands, list_sales_channels, list_warehouses). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-vtex.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-vtex/docs"},"termsOfService":"https://connectorbay.com/byok-vtex/terms"},"servers":[{"url":"https://byok-vtex.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-vtex/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_orders":{"post":{"operationId":"list_orders","summary":"List orders with id, creation date, client name, item count, total value (in cents), payment names, status and sales cha","description":"List orders with id, creation date, client name, item count, total value (in cents), payment names, status and sales channel. At most 100 per page and 30 pages per query: narrow with filters. Use for \"Which VTEX orders are waiting for payment approval\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"order_status":{"anyOf":[{"enum":["waiting-for-sellers-confirmation","payment-pending","payment-approved","ready-for-handling","handling","invoiced","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only orders in this status.","title":"Order Status"},"created_range":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Creation date range, for example 'creationDate:[2026-09-01T00:00:00.000Z TO 2026-09-30T23:59:59.999Z]'.","title":"Created Range"},"sales_channel":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders of this sales channel (trade policy) id.","title":"Sales Channel"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Full-text search: order id, client e-mail, client document or client name.","title":"Search"},"order_by":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Sort as 'Field,asc' or 'Field,desc' with Field one of creationDate, orderId, items, totalValue, origin.","title":"Order By"},"page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (maximum 30).","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"Orders per page (1 to 100, default 15).","title":"Per Page"}},"required":["account_name"],"title":"list_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one order by id with status, totals, sellers, items (SKU, quantity, price), marketing data and store currency. Buyer","description":"Get one order by id with status, totals, sellers, items (SKU, quantity, price), marketing data and store currency. Buyer documents, addresses and payment details are not returned. Use for \"Show VTEX order v502556llux-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"order_id":{"description":"Order id such as 'v502556llux-01' (from list_orders).","maxLength":60,"title":"Order Id","type":"string"}},"required":["account_name","order_id"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_product_and_sku_ids":{"post":{"operationId":"list_product_and_sku_ids","summary":"List product ids with the SKU ids of each, optionally for one category. Returns at most 250 records per call; page with ","description":"List product ids with the SKU ids of each, optionally for one category. Returns at most 250 records per call; page with from_index and to_index. Use for \"Which products and SKUs exist in my VTEX category 12\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"category_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only products of this category id.","title":"Category Id"},"from_index":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Index of the first record (default 1).","title":"From Index"},"to_index":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Index of the last record; to_index minus from_index must not exceed 250 (default 50).","title":"To Index"}},"required":["account_name"],"title":"list_product_and_sku_idsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product":{"post":{"operationId":"get_product","summary":"Get one catalog product by id with name, category, brand, reference id, visibility, descriptions, release date and stock","description":"Get one catalog product by id with name, category, brand, reference id, visibility, descriptions, release date and stock display rule. Use for \"Show VTEX catalog product 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"product_id":{"description":"Numeric product id.","title":"Product Id","type":"integer"}},"required":["account_name","product_id"],"title":"get_productArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_sku":{"post":{"operationId":"get_sku","summary":"Get one SKU by id with product id, name, reference id, active flag, dimensions, weight, kit flag and creation date. Use ","description":"Get one SKU by id with product id, name, reference id, active flag, dimensions, weight, kit flag and creation date. Use for \"Show VTEX SKU 2\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"sku_id":{"description":"Numeric SKU id.","title":"Sku Id","type":"integer"}},"required":["account_name","sku_id"],"title":"get_skuArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_sku_inventory":{"post":{"operationId":"get_sku_inventory","summary":"Show stock of one SKU per warehouse: total, reserved and unlimited-stock flag. Use for \"How much stock does VTEX SKU 2 h","description":"Show stock of one SKU per warehouse: total, reserved and unlimited-stock flag. Use for \"How much stock does VTEX SKU 2 have in each warehouse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"sku_id":{"description":"SKU id (a number) from get_sku or list_product_and_sku_ids.","maxLength":30,"title":"Sku Id","type":"string"}},"required":["account_name","sku_id"],"title":"get_sku_inventoryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_category_tree":{"post":{"operationId":"get_category_tree","summary":"Get the category tree down to a number of levels with id, name, URL and children. Use for \"What does my VTEX category tr","description":"Get the category tree down to a number of levels with id, name, URL and children. Use for \"What does my VTEX category tree look like to 2 levels\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"levels":{"description":"How many category levels to return, for example 2.","maxLength":2,"title":"Levels","type":"string"}},"required":["account_name","levels"],"title":"get_category_treeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_category":{"post":{"operationId":"get_category","summary":"Get one category by id with name, parent, title, active flag and tree path. Use for \"Show VTEX category 12\".","description":"Get one category by id with name, parent, title, active flag and tree path. Use for \"Show VTEX category 12\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"category_id":{"description":"Numeric category id.","title":"Category Id","type":"integer"}},"required":["account_name","category_id"],"title":"get_categoryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_brands":{"post":{"operationId":"list_brands","summary":"List catalog brands one page at a time with id, name, active flag and title. Use for \"Which brands are registered in my ","description":"List catalog brands one page at a time with id, name, active flag and title. Use for \"Which brands are registered in my VTEX catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"},"page":{"description":"Page number, starting at 1.","maximum":100000,"minimum":1,"title":"Page","type":"integer"},"page_size":{"description":"Brands per page (1 to 100).","maximum":100,"minimum":1,"title":"Page Size","type":"integer"}},"required":["account_name","page","page_size"],"title":"list_brandsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sales_channels":{"post":{"operationId":"list_sales_channels","summary":"List the store's sales channels (trade policies) with name, active flag, country, currency and time zone. Use for \"Which","description":"List the store's sales channels (trade policies) with name, active flag, country, currency and time zone. Use for \"Which sales channels does my VTEX store have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"}},"required":["account_name"],"title":"list_sales_channelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_warehouses":{"post":{"operationId":"list_warehouses","summary":"List warehouses with id, name, priority, active flag and linked docks. Use for \"Which warehouses are configured in VTEX\"","description":"List warehouses with id, name, priority, active flag and linked docks. Use for \"Which warehouses are configured in VTEX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Your VTEX account name: the part before .vtexcommercestable.com.br in your store's admin address.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account Name","type":"string"}},"required":["account_name"],"title":"list_warehousesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}