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.

​
Preview and live writes

The current job editor is immediately live: there is no separate publication step. Use the preview operation to validate and render a complete TipTap document without writing. Mutations require confirmLive: true (or --confirm-live in the CLI) to acknowledge that hired AI trainers can see the result immediately. 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.

​
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. The CLI can import a DOCX file into a new job page. It converts supported headings, paragraphs, formatting, links, lists, tables, and embedded images. Preview mode uses visible placeholders and uploads nothing. A confirmed import uploads each embedded image and places 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.