Instant Preview API

The hosted Rover preview API lets you create signed-in preview sessions, read the latest preview state, stream launch events, continue a waiting preview, cancel/share a preview, and fetch the live-inject bootstrap loader.

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 Try on Other Sites.

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, use 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

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

Route examples

The preferred create payload uses targetUrl and prompt. The backend still accepts the older compatibility aliases url and message.

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

OpenAPI spec (raw) for AI/programmatic consumers.

OpenAPI source in GitHub as the checked-in contract in `rtrvr-cloud-backend`.

rtrvr-cloud-backend for the hosted preview control plane implementation.

Rover repo for the public Preview Helper, SDK helpers, and runtime docs.

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

Load the public Preview Helper from the Rover repo, test generic Workspace JSON from Workspace docs, then test helper handoff, SDK 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.