Skip to main content

​
get_version_preview_url

Read-only Get the preview link for a finished version - what Studio’s version card shows. THE tool for “let me see it” once a version is ready, and the only one whose URL is tied to a specific version. Hand preview_url to the user verbatim. It stays valid indefinitely (a published static build, not the sandbox), so it also works for tasks that are sent, merged, discarded, or archived. preview_url is null when this version has nothing published to show, and reason says which case. Tell the user that reason - never pass the live URL off as this version’s preview, since it serves the sandbox’s current working tree:
  • building - the build is in flight. Offer the live app meanwhile.
  • build_failed - say the build failed.
  • not_built - no build was attempted and none is coming: the project previews via the live app rather than published variants. Studio itself shows the live app on these version cards, so offer get_task_preview_url as the way to see it, named as the live app. Do NOT report the version as unfinished or the build as failed - both are wrong here.
  • no_variants_indexed - the build finished but pinned no variant. The version is real and built, there is just nothing to show; offer the live app.
  • no_versions - the task has not produced a version yet, so version is null too. Not an error: say the task has no version to show yet.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.
​
int
Version number to preview. Null uses the task’s active version (the one Studio has checked out) and reports it as-is - a version mid-build answers with no preview even when an older one has one, so pass an explicit version to read that one. Falls back to the newest version with a preview only when there is no active version.

​
get_task_preview_url

Get the LIVE dev-server URL for a task’s sandbox - not a version’s preview. The running app as it stands in the sandbox right now, for watching work in progress or checking a change the agent just made. It is NOT the preview of any finished version - for that use get_version_preview_url, which is what Studio’s version card shows. Starts the dev server if it isn’t up, so it is not a pure read. preview_url is always the sandbox’s proxy host, up or not. The link resolves only when BOTH dev_port_listening and proxy_listening are true - the request goes through the reverse proxy before it reaches the dev server, and the proxy is not started while a task is running. If either is false the link 502s: tell the user it’s still starting rather than passing it off as working, and restart_dev_server if it stays down.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.

​
get_storybook_url

Get the LIVE variants-server URL in a task’s sandbox - not a version’s preview. The variants server running in the sandbox right now, and it starts its reverse proxy if needed (so, not a pure read). For a finished version’s variants use get_version_preview_url instead. storybook_url is returned even when dev_server_running is false, in which case the link is dead - say so and use restart_storybook, don’t hand over a URL that won’t load. (Call these “variants” to the user, not “Storybook”.)
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.

​
get_storybook_status

Read-only Check whether a component’s variants are ready to view. Returns the current variants-render status (or null if none is in flight). Use before/after render_component to know when a render finished.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.

​
start_storybook

Start the variants (component render) server in a task sandbox and return its URL.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.

​
render_component

Render a component’s variants (via Previewer). Runs in the background; poll get_storybook_status for readiness, then get_storybook_url for the URL. Surface the result to the user as “variants”.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.
​
string
required
Component name, e.g. ‘Button’.
​
string
required
File path to the component, e.g. ‘src/components/Button.tsx’.

​
open_task_ide

Open the in-browser code editor (OpenVSCode Server) for a task sandbox and return its URL.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.

​
restart_dev_server

Kill and restart the customer dev server + reverse proxy on a task sandbox — use to recover a broken/stuck live preview.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.

​
restart_storybook

Recover a broken/stuck variants preview by restarting its render server.
​
UUID
required
Project UUID.
​
UUID
required
Task UUID.
​
boolean
default:"False"
Force a restart. When false, a health probe leaves a healthy server untouched and only restarts a broken one.