Folder Instructions API and SDK

Use the shared folder guide 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:

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 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.