Skip to main content
Every OpenTrain job has one canonical set of worker instructions: the pages in that job’s employer Instructions tab. The web editor, worker view, API, SDK, CLI, and MCP server all read and write that same content. There are no standalone instruction workspaces, reusable manuals, job bindings, publication copies, or separate review queues. A successful job-instruction write must be visible at the employer URL returned in the response.

​
Page tree

Instructions are a multi-page tree with two supported levels:
  • Root pages
  • One level of subpages beneath a root
This is the same limit enforced by the employer editor. An agent cannot create a deeper tree through another surface. A job can also inherit read-only pages from its folder. The inspect response identifies inherited pages and explains when the job is locked to the folder source.

​
Rich documents and checksums

Each page body is a TipTap JSON document:
Reads return the document with a deterministic SHA-256 checksum. Patch and replacement requests present the last-read checksum, so a concurrent human edit produces a conflict instead of being overwritten. OpenTrain normalizes TipTap content before preview and checksumming. For example, a bold mark with omitted attributes and the same mark with an empty attrs object produce the same reviewed checksum. Default-null list background and code-block language attributes are also omitted to match canonical TipTap Cloud readback.

​
Preview and live writes

The current job editor is immediately live: there is no separate publication step. Use preview for content-only rendering and preflight for the complete intended operation. Preflight validates the current target, checksum, placement, content, and resulting tree, then returns a short-lived signed token bound to that exact operation. Mutations require both the token and confirmLive: true (or --confirm-live in the CLI). Agent tools read the canonical page back after a mutation before reporting success. Treat only that readback and returned employer URL as confirmation; a response from any unrelated document system is not worker-visibility evidence. Single-page patch and replacement operations stage a new canonical TipTap document and atomically switch the job page to it. They do not wholesale-replace a collaboration document that may still be open in an employer editor. The employer and worker surfaces adopt the new canonical document identity through their live workspace refresh. For coordinated multi-page revisions, a local CLI bundle can represent the desired tree. The bundle is explicitly non-authoritative. Its reviewed plan is applied as one atomic tree change, preventing a partially assembled manual from becoming visible between individual page writes.

​
Images and DOCX files

The canonical image endpoint accepts JPEG, PNG, WebP, GIF, and AVIF files up to 5 MB and returns a URL for a TipTap image node. Uploading an image does not edit a page by itself. Capability discovery returns image.allowedHostPatterns for image URLs the renderer accepts. Upload any image from another host through the canonical endpoint before placing its returned URL in a page. The CLI exposes this flow as opentrain instructions image upload. It plans a stable URL without writing unless you pass --confirm-live, then verifies the confirmed upload against the reviewed plan. Confirmed uploads require the SHA-256 returned by preview, so changed local bytes fail before upload. The CLI can import a DOCX file into a new job page. It deterministically converts supported headings, paragraphs, formatting, links, lists, tables, and embedded images. Preview mode plans stable final image URLs and uploads nothing. A confirmed import verifies those plans while uploading each embedded image and placing it in the canonical TipTap document. General file, audio, and video attachments are not currently part of the job Instructions API. Do not assume support based on another OpenTrain feature.

​
Required scopes

  • instructions:read reads a job tree or page.
  • instructions:write previews content, uploads images, and mutates pages.
The token owner must also have employer access to the job. A scope never grants cross-organization access. Next, follow Manage job Instructions or choose the CLI, MCP, or HTTP API.