Instant Preview API

Signed-in hosted preview contract for create/get/events/input/cancel/share/bootstrap plus the OpenAPI spec.

This page is only for Hosted Preview. If you want to generate Helper, Console, or Bookmarklet output from a real Workspace site config instead of a temporary preview token, use Instant Preview.

Who this is for

Non-dev operator — use Rover Instant Preview and treat this page as the field guide for what the UI is doing.
Developer — call the hosted routes directly, build the public Preview Helper, or generate snippets from the SDK.
AI / programmatic caller — use the OpenAPI spec plus the curl examples below. This is still a signed-in hosted preview flow, not an anonymous public demo endpoint.

Auth and token model

Create route auth — POST /v2/rover/previews requires a Firebase bearer token from a signed-in Rover operator session.
Preview control token — the create response returns previewToken / sessionToken. Use that token for get/events/input/cancel/share/bootstrap.
Runtime token — runtimeSessionToken is the short-lived Rover runtime token used by the helper, bootstrap.js, console snippets, and bookmarklets.
Production install key — publicKey (pk_site_*) is a Workspace install credential, not a preview token.
Query auth — follow-on routes accept either previewToken or token as query params, or the preview token in bearer auth.

Website flow in API terms

1.Sign in to Rover Instant Preview.
2.Create a preview with target URL, prompt or shortcut, mode, and platform.
3.Use the returned helperOpenUrl, consoleSnippet, or bookmarkletUrl.
4.Poll or stream the preview until it succeeds, fails, or needs input.
5.Use workspaceInstallUrl to convert the demo into a real Workspace install.

Route examples

The create payload uses targetUrl and prompt.

Create preview

curl -X POST "https://agent.rtrvr.ai/v2/rover/previews" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://www.amazon.com/",
    "prompt": "Show how Rover would guide a user through this page.",
    "mode": "auto",
    "platform": "desktop"
  }'

Get latest preview state

curl "https://agent.rtrvr.ai/v2/rover/previews/PREVIEW_ID?previewToken=PREVIEW_TOKEN"

Stream events

curl -N "https://agent.rtrvr.ai/v2/rover/previews/PREVIEW_ID/events?previewToken=PREVIEW_TOKEN"

Send follow-up input

curl -X POST "https://agent.rtrvr.ai/v2/rover/previews/PREVIEW_ID/input?previewToken=PREVIEW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Continue to the next step and explain what Rover is doing."}'

Cancel preview

curl -X POST "https://agent.rtrvr.ai/v2/rover/previews/PREVIEW_ID/cancel?previewToken=PREVIEW_TOKEN"

Get share URL

curl -X POST "https://agent.rtrvr.ai/v2/rover/previews/PREVIEW_ID/share?previewToken=PREVIEW_TOKEN"

Fetch live-inject bootstrap

curl "https://agent.rtrvr.ai/v2/rover/previews/PREVIEW_ID/bootstrap.js?previewToken=PREVIEW_TOKEN"

Important response fields

Field	Meaning
`modeChosen`	The actual execution path after attach/fallback: `live_inject` or `hosted_preview`.
`consoleSnippet`	Paste into DevTools on the target page for current-page live injection.
`bookmarkletUrl`	Bookmarklet form of the same current-page live inject bootstrap.
`helperOpenUrl`	Target page URL decorated with a private helper handoff fragment for the public Preview Helper app.
`runtimeSessionToken`	Short-lived Rover runtime token used by helper/bootstrap flows. Not the same as the preview control token.
`helperConfig`	Normalized helper payload including host scope, launch attach metadata, and bootstrap URL.
`workspaceInstallUrl`	Workspace handoff URL for turning the preview into a production install.
`activeLaunch` / `latestEvents` / `finalResult`	Live status, recent launch events, and terminal result details for the selected live/cloud path.

Spec and source of truth

Instant Preview docs — for the supported UI flow and helper handoff behavior.
Preview Helper repo — for extension source, build, and local loading steps.
Instant Preview — for Workspace config, Helper, Console, and Bookmarklet testing.
Workspace docs — for site keys, install material, and production launch.

Manual verification matrix

Non-dev path — sign in at Instant Preview, create a preview, try helper/console/bookmarklet actions, switch to hosted preview if live inject stalls, save a share link, then use the Workspace install handoff.
Developer path — build the Preview Helper from the public repo, use the flow from Instant Preview, test generic Workspace JSON from Workspace docs, then test helper handoff, console/bookmarklet helpers, and production script-tag generation.
AI / programmatic path — use the OpenAPI spec and curl examples above to create a preview, fetch state, stream events, send input, cancel/share it, and fetch bootstrap.js.