Hosted Instructions visual proof

Hosted Instructions visual proof lets an authorized employer or agent inspect the actual OpenTrain Instructions UI without running a local browser. OpenTrain captures the real employer workspace or a real designated test-worker reader in Chromium and returns private PNG, ARIA, diagnostics, and provenance artifacts.

Base path: /api/public/v1/instructions/visual

Note

Direct API, CLI, and MCP renders are for agents. They do not require a Vercel login or an interactive browser session. Human observe links are separate: they are short-lived and require normal OpenTrain authorization.

Agents should fetch the PNG and ARIA artifacts directly. Create an observe link only when an authorized human needs to inspect the same pinned render.

Workflow

1. Read capabilities to discover audiences, targets, viewports, retention, and worker-coverage rules.
2. Create a session pinned to the job’s current canonical Instructions tree.
3. Select a page or stable node, or include it when creating the session.
4. Render desktop, mobile, or both using the current state revision.
5. Inspect the PNG and semantic evidence directly, or mint a human review link.
6. Revoke the link or expire the session when review is complete.

Endpoints

Method	Path	Purpose
GET	/capabilities	Discover the hosted visual-proof contract.
POST	/sessions	Create an employer or designated-worker session pinned to a job tree.
GET	/sessions/{sessionId}	Read session state and live source drift.
POST	/sessions/{sessionId}/manage	Select a page/node, expire the session, or refresh its renderer grant with an expected-state revision.
POST	/sessions/{sessionId}/render	Capture desktop/mobile evidence through the real product renderer.
GET	/sessions/{sessionId}/artifacts	List bounded private evidence records.
GET	/artifacts/{artifactId}	Read one artifact with a fresh signed resource URL.
POST/GET	/sessions/{sessionId}/links	Create or list observe-only links.
POST	/sessions/{sessionId}/links/{linkId}/revoke	Revoke one link.

Create and render

Employer session:

{
  "jobId": "job_123",
  "audience": "EMPLOYER",
  "pageId": "page_456"
}

Worker session:

{
  "jobId": "job_123",
  "audience": "WORKER",
  "workerContractId": "contract_test_789",
  "pageId": "page_456"
}

Worker proof is valid only through a real contract designated for testing. The response carries typed workerCoverage; no synthetic worker is substituted.

Render with the session’s current revision:

{
  "expectedStateRevision": 2,
  "viewports": ["desktop", "mobile"],
  "pageId": "page_456",
  "nodeId": "stable-section-id"
}

The response binds each artifact to the exact session, audience, source tree, page/node, viewport, render revision, checksum, and byte size. It also reports source drift against the live canonical Instructions. A successful render sets browserRenderVerified: true.

collaborationSyncVerified is always false. The capture proves what the renderer displayed at that revision; it cannot prove that an already-open collaborative browser received a real-time update.

Authorization and safety

• Reads and artifact access require instructions:read.
• Session control, rendering, and link mutations require instructions:write, an Idempotency-Key, employer job access, and the Instructions visual-proof rollout for the actor.
• State-changing operations require the current expectedStateRevision and fail closed on drift.
• Sessions, artifacts, and links are organization-bound, expiring, and revocable.
• Visual proof writes only isolated preview evidence. It never changes an Instructions page or learner record.
• Retry a transient renderer 503 with the same idempotency key.

SDK

@opentrain-ai/sdk 0.21.0 or later exposes getInstructionsVisualCapabilities, createInstructionsVisualSession, getInstructionsVisualSession, manageInstructionsVisualSession, renderInstructionsVisual, artifact list/get, and link create/list/revoke.

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