> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted quiz visual proof

> Render a pinned Native Forms draft or version through the real worker runner without creating learner state.

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.

```text theme={null}
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.
</Warning>

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:

```json theme={null}
{
  "formId": "form_123",
  "draftRevision": 7,
  "questionId": "question_456"
}
```

Published version:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://app.opentrain.ai/api/public/v1/openapi.json)
for complete request, response, and error schemas.