> ## 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 Instructions visual proof

> Render the real employer Instructions workspace or designated worker reader into agent-readable visual evidence.

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.

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

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:

```json theme={null}
{
  "jobId": "job_123",
  "audience": "EMPLOYER",
  "pageId": "page_456"
}
```

Worker session:

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

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