Hosted LMS visual preview

Hosted LMS visual preview lets an authorized employer or agent inspect the real worker course player without a local browser, a development server, or a worker account. It uses the same isolated Preview session as the existing LMS preview workflow.

Warning

Hosted preview evidence is a simulated worker preview. It does not prove that a particular worker received an assignment, and it never writes learner progress, Native Forms attempts, Project To-dos, notifications, or completion records.

Base path: /api/public/v1/lms/preview

Workflow

1. Create or restore a Preview session pinned to an exact draft revision or published course version.
2. Select the module, lesson, or supported item with the normal session manage operation.
3. Call render with the current expectedStateRevision.
4. Inspect the returned PNG, ARIA snapshot, diagnostics, and provenance manifest artifacts.
5. Use step only when you need to test one supported interaction.
6. Optionally mint an observe-only link for a signed-in employer organization member, then revoke it when review is complete.

Endpoints

Method	Path	Purpose
POST	/sessions/{sessionId}/render	Capture the session’s current focus in desktop, mobile, or both viewports.
POST	/sessions/{sessionId}/step	Execute one closed preview-only action and return before/after evidence.
POST	/sessions/{sessionId}/links	Mint a short-lived, observe-only employer review link.
GET	/sessions/{sessionId}/links	List link records without recovering their secret URLs.
GET	/sessions/{sessionId}/links/{linkId}	Read one link’s lifecycle status.
POST	/sessions/{sessionId}/links/{linkId}/revoke	Revoke one review link.
GET	/sessions/{sessionId}/artifacts	List bounded Preview evidence records.
GET	/artifacts/{artifactId}	Read one ready artifact with a short-lived signed URL.

The OpenAPI document also describes the existing session create, restore, selection, answer, simulated-run, reset, and expiration operations.

Render the current view

POST /sessions/{sessionId}/render requires lms:write, an Idempotency-Key, and the current state revision:

{
  "expectedStateRevision": 7,
  "viewports": ["desktop", "mobile"],
  "moduleKey": "reconciliation",
  "lessonKey": "cutoff-testing"
}

The optional target fields are assertions. They do not navigate. Select the target first, then render it. A mismatch fails closed instead of producing a mislabeled screenshot.

The response contains:

• evidenceClass: "SIMULATED_WORKER_PREVIEW";
• the exact state and render revisions;
• private PNG artifact records;
• an ARIA snapshot for semantic inspection;
• renderer diagnostics; and
• a provenance manifest binding every artifact to the session, target, viewport, revision, checksum, and byte size.

Execute a safe step

POST /sessions/{sessionId}/step accepts a closed action vocabulary. It never accepts CSS selectors, JavaScript, arbitrary URLs, coordinates, or free-form browser instructions.

{
  "op": "complete_content",
  "lessonKey": "cutoff-testing",
  "expectedStateRevision": 7,
  "capture": "before_after",
  "viewport": "desktop"
}

Supported actions in this release are open_lesson and complete_content. The receipt reports the canonical before and after state revisions and an outcome of APPLIED or ALREADY_SATISFIED.

Share an employer review link

POST /sessions/{sessionId}/links returns the URL exactly once. Treat it as a short-lived secret. Its fragment token is exchanged once for an HttpOnly cookie, and every read checks that the viewer is currently signed in as a member of the Preview session’s employer organization.

Links are observe-only. Opening one never changes the Preview session. Module and lesson deep links are supported. Exact-question links currently fail with ITEM_LINK_UNAVAILABLE rather than silently opening a broader view.

Later link reads return only metadata and lifecycle status: ACTIVE, CONSUMED, REVOKED, or EXPIRED. They cannot recover the URL.

Authorization and retry behavior

• Render, step, link creation, and link revocation require lms:write and a stable Idempotency-Key.
• Artifact and link reads require lms:read.
• Every operation enforces organization ownership of the Preview session.
• State-changing Preview operations use an expected revision and fail with 409 when the session changed.
• Renderer unavailability or capacity returns a retryable 503. Reuse the same idempotency key after an uncertain response.
• Signed artifact URLs expire. Retrieve the artifact again when an authorized reviewer needs a fresh URL.

SDK methods

@opentrain-ai/sdk 0.15.0 or later exposes the same contract through:

• renderLmsPreviewHosted;
• stepLmsPreviewHosted;
• createLmsPreviewLink;
• getLmsPreviewLink;
• listLmsPreviewLinks; and
• revokeLmsPreviewLink.

Use the machine-readable OpenAPI document for the complete request, response, and error schemas.