> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gotolstoy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets

> Tools that list, create, open, run commands in, preview, publish, discard changes of and read the history and clone URL of the workspace's AI widgets.

## list\_widgets

Lists the workspace's AI widgets: the storefront widgets, landing pages and app blocks Tolstoy builds and hosts for the brand. Each comes with its widgetId, name, template, store, status, Platform link, and whether its saved code differs from its published version. Most recently changed first.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {},
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## create\_widget

Creates an AI widget for the connected store from a template and sets up its project: the template's files, the widget's history and a running preview. The widget is shared with every team of the workspace. The result is the new widget, still a draft that shoppers do not see, and the files and folders at its root.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "templateId": {
>       "type": "string",
>       "enum": [
>         "landing-page",
>         "ad-landing-page",
>         "shopify-ad-page",
>         "product-gallery",
>         "custom-js-widget",
>         "spotlight",
>         "interactive-quiz",
>         "hero",
>         "carousel",
>         "embed",
>         "custom-shopify-liquid-widget",
>         "for-you-feed",
>         "pdp-stories",
>         "review-videos",
>         "bubble-feed",
>         "collection-tile",
>         "tapcart-product-gallery",
>         "tapcart-for-you-feed",
>         "tapcart-pdp-stories",
>         "choose-my-model",
>         "try-on-studio",
>         "complete-the-look",
>         "shopper-chat"
>       ],
>       "description": "The template the widget starts from:\n- landing-page: Generic Landing Page. A media-rich landing page widget with hero section, video galleries, and call-to-action buttons.\n- ad-landing-page: Ad Landing Page. Landing page targeted at paid traffic, with multiple variants for testing campaign angles.\n- shopify-ad-page: Shopify Ad landing page. Shopify optimized. Landing page targeted at paid traffic, with multiple variants for testing campaign angles.\n- product-gallery: Product Gallery. A Shopify product media gallery that replaces the native gallery with video support and variant switching.\n- custom-js-widget: Custom JS Widget. A blank JavaScript widget template for any website. Add your own logic and design.\n- spotlight: Homepage Spotlight. Curate your homepage experience and guide buyers to products they love\n- interactive-quiz: Interactive Quiz. Guided product-finder quiz with branching questions and personalized product recommendations\n- hero: Hero. A full-width inline hero video embed that autoplays muted with no visible controls.\n- carousel: Carousel. A horizontal shoppable media carousel that opens a video player overlay on click.\n- embed: Embed. A single Shopify Liquid video embed with a centered play button and native controls on playback.\n- custom-shopify-liquid-widget: Custom Shopify Liquid Widget. A blank Shopify Liquid block template with JavaScript. Build custom theme sections.\n- for-you-feed: For You Feed. A page-load experience that takes over the page with a full-screen shoppable-video feed.\n- pdp-stories: PDP Stories. Circular story thumbnails on product pages with click-to-play player overlay.\n- review-videos: Review Videos. Product-page review videos that let shoppers watch social proof before they buy.\n- bubble-feed: Bubble Feed. Dismissable floating video bubble that opens a full-screen shoppable feed on click.\n- collection-tile: Collection Tile. Autoplaying product videos injected over matching collection grid product images.\n- tapcart-product-gallery: Tapcart Product Gallery. A mobile product gallery for Tapcart Custom Blocks — swipeable images, variant picker, and add-to-cart.\n- tapcart-for-you-feed: Tapcart For You Feed. A full-screen shoppable video feed experience optimized for Tapcart Custom Blocks.\n- tapcart-pdp-stories: Tapcart PDP Stories. Center-spotlighted stories carousel for Tapcart PDP pages with product price subtitle and PDP open actions.\n- choose-my-model: Choose My Model. A product-page model picker that shows AI try-on images of the current product on the merchant's configured models.\n- try-on-studio: Style Studio. A product-page style studio: shoppers pick a model or upload their own photo, then build the full look with AI-recommended pieces that go with the product.\n- complete-the-look: Complete the Look. Let shoppers build and try on an outfit around the product they are viewing, then shop the exact pieces and variants.\n- shopper-chat: Shopper chat. An AI shopping assistant chat for the storefront. A floating bubble opens the chat, on a product page the chat opens with the top questions for that product, and See it on you shows the product on the shopper's photo."
>     },
>     "name": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widget name. Defaults to the template name."
>     },
>     "description": {
>       "type": "string",
>       "minLength": 1,
>       "description": "A short description of the widget's purpose."
>     }
>   },
>   "required": [
>     "templateId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## open\_widget

Gets a widget's project ready in its sandbox, and brings it up to the latest save when the project has no unsaved work. The result is the widget and the files and folders at its root. run\_widget\_command opens the widget on its own as well.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     }
>   },
>   "required": [
>     "widgetId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## run\_widget\_command

Runs a shell command with bash in the widget's sandbox, from the widget root, and waits for it to finish. The sandbox has Node, pnpm, git, ripgrep and fd; add a package with pnpm add. The result is the command's stdout and stderr, cut to the last 2000 lines or 50KB, and its exit code. When the command changed the widget's files, the change is recorded at once as one save in the widget's history, which Platform and the Tolstoy Agent read, and the result names that save; otherwise save is null. A running preview shows the change; shoppers see it only after the widget is published. Publishing goes through publish\_widget.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     },
>     "command": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The shell command, run with bash from the widget root."
>     },
>     "timeout": {
>       "type": "integer",
>       "exclusiveMinimum": 0,
>       "maximum": 1200,
>       "description": "Seconds available to the command. Defaults to 300, at most 1200. At the end of that time the command and its process group are stopped."
>     }
>   },
>   "required": [
>     "widgetId",
>     "command"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## preview\_widget

Starts the widget's preview server in its sandbox when it is not running, and returns a link to each preview page the widget declares, such as a home page and a product page. The preview shows the widget's current files and updates as they change. A product page needs a productId; without one its url is null. A link works while the sandbox runs, and the sandbox stops after some minutes without use; a new call then returns a working link.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     },
>     "productId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The externalProductId of a store product, from search_products, to show on product pages."
>     }
>   },
>   "required": [
>     "widgetId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## publish\_widget

Builds the widget from its current files and makes that version live for the store's shoppers at once. Publishing needs a Tolstoy plan that includes AI widget publishing. On success the result carries the published version and either the snippets that embed the widget or the live page links. A failed build comes back with success false and the build's error output, and the live version stays as it was.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     }
>   },
>   "required": [
>     "widgetId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## discard\_widget\_changes

Returns the widget to its last published version. Every save after that version is removed from the widget's files and history, so it cannot be restored. A widget that was never published has nothing to return to, and the call is refused while the Tolstoy Agent is working on the widget in Tolstoy.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     }
>   },
>   "required": [
>     "widgetId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## get\_widget\_history

Returns the widget as it is now, with its status and whether its saved code differs from its published version, and lists its saves, newest first, each with its sha, time, message and the files it changed. Every run\_widget\_command that changes the widget's files is one save; Platform and the Tolstoy Agent add saves of their own. With a sha, the result is that one save and its diff.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     },
>     "sha": {
>       "type": "string",
>       "pattern": "^[0-9a-f]{4,40}$",
>       "description": "A save's sha from this tool's list. With it, the result is that save and its diff."
>     },
>     "limit": {
>       "type": "integer",
>       "minimum": 1,
>       "maximum": 100,
>       "description": "The most saves to list, newest first. Defaults to 20."
>     }
>   },
>   "required": [
>     "widgetId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```

## get\_widget\_clone\_url

Returns the git URL of the widget's repository, the one Platform, the Tolstoy Agent and run\_widget\_command save to. The URL carries the access to clone the repository and push to its main branch. A commit pushed there is a save in the widget's history. run\_widget\_command, preview\_widget and publish\_widget bring the widget's sandbox up to the pushed commits before they act; when the sandbox has work the repository lacks, they stop with an error and change nothing. Shoppers see a change only after publish\_widget.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "widgetId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "The widgetId list_widgets or create_widget returned."
>     }
>   },
>   "required": [
>     "widgetId"
>   ],
>   "additionalProperties": false,
>   "$schema": "http://json-schema.org/draft-07/schema#"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.