Hosted quiz visual proof

Hosted quiz visual proof renders one exact Native Forms draft revision or published version through the real worker form runner in Chromium. It gives agents desktop/mobile PNG, ARIA, diagnostics, and provenance evidence without creating a real worker attempt.

Base path: /api/public/v1/project-todos/quizzes/preview

Warning

This is SIMULATED_WORKER_PREVIEW evidence. It proves the captured visual and semantic state, not that a worker received or opened an assignment.

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.
2. Create a session with exactly one draft revision or one published version.
3. Optionally select one question using the current state revision.
4. Render desktop, mobile, or both.
5. Inspect the returned artifacts directly, or create a short-lived human review link.
6. Revoke the link or expire the session.

Endpoints

Method	Path	Purpose
GET	/capabilities	Discover pins, targets, evidence, retention, and safety guarantees.
POST	/sessions	Create a session pinned to a draft revision/content hash or immutable version.
GET	/sessions/{sessionId}	Read session state and source drift.
POST	/sessions/{sessionId}/manage	Select a question, expire the session, or refresh its renderer grant with an expected-state revision.
POST	/sessions/{sessionId}/render	Capture desktop/mobile evidence with the real worker runner.
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.

Pin an exact form

Draft:

{
  "formId": "form_123",
  "draftRevision": 7,
  "questionId": "question_456"
}

Published version:

{
  "formId": "form_123",
  "formVersionId": "version_789"
}

Exactly one pin is required. Draft sessions are content-hash bound so a later edit cannot be mistaken for the reviewed content.

Render with the current state revision:

{
  "expectedStateRevision": 1,
  "viewports": ["desktop", "mobile"],
  "questionId": "question_456"
}

The result contains the exact render revision, target, PNG records, ARIA snapshot, diagnostics, and a manifest binding every artifact to its checksum and byte size. MCP returns PNGs inline when the client supports image content; the CLI can download and verify the complete evidence set with --out.

Zero-write and privacy guarantees

Preview never creates or changes:

• Native Forms attempts, answers, grades, or result releases;
• Project To-do assignments or transitions;
• worker progress or completion;
• notifications; or
• audit completion events.

The renderer receives the worker-safe projection and never returns answer keys. Direct agent renders do not require a browser or Vercel login. Human observe links require a currently authorized OpenTrain employer and are short-lived, organization-bound, and revocable.

Authorization and retry behavior

• Capability, session, artifact, and link reads require project_todos:read.
• Session control, rendering, and link mutations require project_todos:write and an Idempotency-Key.
• State-changing operations require the current expectedStateRevision.
• Reuse the same idempotency key after an uncertain or retryable 503.
• Retrieve an artifact again when its signed URL expires.

SDK

@opentrain-ai/sdk 0.21.0 or later exposes getNativeFormPreviewCapabilities, createNativeFormPreviewSession, getNativeFormPreviewSession, manageNativeFormPreviewSession, renderNativeFormPreview, artifact list/get, and link create/list/revoke.

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