# Folder Instructions API and SDK

Shared folder inventory, reviewed activation and migration, recovery, and scope-aware authoring contracts.

Source: https://www.opentrain.ai/docs/developers/api-reference/instructions/folders/

Use the [shared folder guide](https://www.opentrain.ai/docs/developers/guides/manage-folder-instructions/)
for the complete safety workflow. All paths below are relative to
`https://app.opentrain.ai/api/public/v1/instructions/folders/{folderId}`.
Current employer authority is required for every request; token scopes alone
do not grant access to another organization.

## Migration and recovery

| Method | Suffix | SDK method |
| --- | --- | --- |
| `GET` | empty, optionally `?includeContent=true` | `getFolderInstructions` |
| `POST` | `/changes/preview` | `previewFolderInstructionChange` |
| `POST` | `/changes/confirm` | `confirmFolderInstructionChange` |
| `GET` | `/changes/{operationId}` | `getFolderInstructionChange` |
| `POST` | `/changes/{operationId}/apply` | `applyFolderInstructionChange` |
| `POST` | `/changes/{operationId}/cancel` | `cancelFolderInstructionChange` |
| `POST` | `/changes/{operationId}/resume` | `resumeFolderInstructionChange` |
| `GET` | `/changes/{operationId}/recovery` | `exportFolderInstructionRecovery` |

Preview accepts the guide's strict `ACTIVATE`, `APPEND` or `REVERSE` request.
Confirmation accepts `{ request, reviewedPlanDigest, confirmed: true }`.
Apply/cancel/resume accept an empty JSON object; their operation ID already
identifies the confirmed request. Unknown fields are rejected.

Inventory, preview, status and recovery require `instructions:read`. Lifecycle
writes require `instructions:write`. The existing verified-account requirement
also applies to POST preview. Read and preview do not create operations,
checkpoints or pages.

The TypeScript SDK returns typed domain results and throws typed API errors:

```typescript
import { OpenTrainClient, type FolderInstructionOperationRequest } from "@opentrain-ai/sdk";

const api = new OpenTrainClient({ apiToken: process.env.OPENTRAIN_API_KEY! });
const folderId = "your-folder-id";
const inventory = await api.getFolderInstructions(folderId, { includeContent: true });
const request: FolderInstructionOperationRequest = {
  kind: "APPEND",
  idempotencyKey: "copy-reviewed-language-guide-v1",
  sources: [{ jobId: "source-job-id", pageIds: ["source-page-id"], label: "French" }],
  newPages: [],
};
const plan = await api.previewFolderInstructionChange(folderId, request);
// Inspect the complete plan and canApply before any confirmation.
```

Do not automatically confirm an example. After reviewing an applicable plan,
call `confirmFolderInstructionChange(folderId, { request,
reviewedPlanDigest: plan.planDigest, confirmed: true })`, save its operation
ID, and respect `quiesceReadyAt`. Check status and apply the same operation;
require verified readback before treating it as complete.

## Page authoring

Folder authoring uses the same page/tree/document contracts as job authoring,
with explicit `folderId` and `canonicalSource: "FOLDER_INSTRUCTION_SET"`.
Existing job paths and SDK methods remain unchanged.

| Area | Folder suffixes |
| --- | --- |
| Active tree and page | `GET /pages`, `GET /pages/{pageId}` |
| Preview and preflight | `POST /preview`, `POST /preflight` |
| Page writes | `POST /pages`, `PUT/PATCH/DELETE /pages/{pageId}` |
| Atomic tree | `POST /tree/preflight`, `POST /tree/apply` |
| Images | `POST /assets/images/plan`, `POST /assets/images` |
| Videos | `POST /videos/prepare`, `GET /videos/{assetId}`, `POST /videos/{assetId}/cancel` |
| History | `/pages/{pageId}/history` and checkpoint read/compare/restore endpoints |
| Schema | `POST /pages/{pageId}/schema-upgrade` |
| Links and verification | `GET /pages/{pageId}/link`, `GET /verify`, `GET /visual-review` |

Authoring reads and no-write preflights require `instructions:read`; applied
writes require `instructions:write`. Mutations use their documented explicit
confirmation, checksum/preflight and receipt-key requirements. First activation
must use migration rather than ordinary create. Incompatible published or
unknown delivery refuses before mutation.

The SDK provides matching `getFolderInstructionPage`,
`preflightFolderInstructionOperation`, `createFolderInstructionPage`,
`applyFolderInstructionTree`, history/media/schema and other folder methods.
Use the [live OpenAPI document](https://app.opentrain.ai/api/public/v1/openapi.json)
for complete closed request/response schemas and exact endpoint suffixes.

`x-opentrain-authoring-retry` in OpenAPI and the SDK's
`FOLDER_INSTRUCTION_AUTHORING_RETRY` describe exact-operation recovery.
They do not make unkeyed mutations idempotent or safe to resend blindly.
Schema status includes bounded current intent identity, revision and expiry;
video cancellation distinguishes pending progress from an immutable READY asset.