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

# Preview

> See a finished version, or the task's live sandbox.

### `get_version_preview_url`

<Icon icon="eye" /> 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.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="version" type="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.</ParamField>

### `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.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `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".)

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `get_storybook_status`

<Icon icon="eye" /> 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.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `start_storybook`

Start the variants (component render) server in a task sandbox and return its URL.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `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".

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="name" type="string" required>Component name, e.g. 'Button'.</ParamField>
<ParamField path="path" type="string" required>File path to the component, e.g. 'src/components/Button.tsx'.</ParamField>

### `open_task_ide`

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

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `restart_dev_server`

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

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>

### `restart_storybook`

Recover a broken/stuck variants preview by restarting its render server.

<ParamField path="project_id" type="UUID" required>Project UUID.</ParamField>
<ParamField path="task_id" type="UUID" required>Task UUID.</ParamField>
<ParamField path="force" type="boolean" default="False">Force a restart. When false, a health probe leaves a healthy server untouched and only restarts a broken one.</ParamField>