Instructions API

The Instructions API lets agents and integrations maintain the same rich, nested manuals that people edit in OpenTrain. The canonical format is versioned TipTap JSON; page-content and tree mutations travel through atomic changesets, and every publication is an immutable snapshot. Base path:

https://app.opentrain.ai/api/public/v1/instructions

Send Authorization: Bearer ot_pat_… on every request. Start with GET /capabilities so your client uses the current schema vocabulary and limits. The complete machine-readable contract is also available in the OpenAPI document.

Scopes and roles

Token scopes and workspace roles are both enforced. A token never grants access to a workspace the user cannot access.

Scope	Purpose
`instructions:read`	Read workspaces, manuals, trees, pages, revisions, publications, assets, search results, and renders.
`instructions:write`	Create workspaces/manuals and apply guarded changesets.
`instructions:propose`	Validate, diff, and submit a changeset without applying it when the user is a workspace `EDITOR` or `OWNER`.
`instructions:review`	Approve or reject submitted changesets when the user has reviewer access.
`instructions:publish`	Manage workspace grants and publish immutable versions; publication also requires the workspace `OWNER` role.

Workspace creation persists an OWNER permission record for the creator. Owners can grant EDITOR, REVIEWER, or VIEWER access to other users. See Scopes and capabilities for token creation and least-privilege guidance.

Endpoint map

All paths below are relative to the base path.

Discovery, workspaces, and permissions

Method	Path	Scope	Purpose
`GET`	`/capabilities`	`instructions:read`	Return schema version, nodes, marks, attributes, patch operations, audiences, formats, and limits.
`GET`	`/workspaces`	`instructions:read`	List accessible workspaces with cursor pagination.
`POST`	`/workspaces`	`instructions:write`	Create a workspace for a verified user who belongs to an employer organization. Accepts `Idempotency-Key`.
`GET`	`/workspaces/{workspaceId}`	`instructions:read`	Read workspace metadata.
`PATCH`	`/workspaces/{workspaceId}`	`instructions:write`	Rename a workspace.
`POST`	`/workspaces/{workspaceId}/archive`	`instructions:write` + owner	Retain but archive a workspace; it is no longer accessible through this API.
`GET`	`/workspaces/{workspaceId}/permissions`	`instructions:read` + `instructions:publish` + owner	List persisted user roles, including the owner’s record.
`POST`	`/workspaces/{workspaceId}/permissions`	`instructions:publish` + owner	Grant or update `EDITOR`, `REVIEWER`, or `VIEWER`.
`POST`	`/workspaces/{workspaceId}/permissions/{principalId}/revoke`	`instructions:publish` + owner	Revoke a user grant; the owner’s role cannot be revoked.

Create a workspace with {"name":"Operations"}. Grant access with {"principalId":"<userId>","role":"REVIEWER"}.

Manuals, trees, and pages

Method	Path	Scope	Purpose
`GET`	`/workspaces/{workspaceId}/manuals`	`instructions:read`	List manuals in a workspace.
`POST`	`/workspaces/{workspaceId}/manuals`	`instructions:write`	Create a manual with an optional audience and bindings. Accepts `Idempotency-Key`.
`GET`	`/manuals/{manualId}`	`instructions:read`	Read manual metadata, bindings, and current head.
`PATCH`	`/manuals/{manualId}`	`instructions:write`	Update title, default audience, or the complete binding set.
`POST`	`/manuals/{manualId}/archive`	`instructions:write` + owner	Retain but archive a manual; it is no longer accessible through this API.
`GET`	`/manuals/{manualId}/tree`	`instructions:read`	Return the bounded nested tree with page revisions and checksums.
`GET`	`/pages/{pageId}`	`instructions:read`	Read canonical JSON; optionally request an immutable revision and derived HTML or Markdown.

Manual bindings are {kind,targetId,precedence} objects. kind is JOB, FOLDER, or WORK_PROJECT; lower precedence wins among bindings of the same specificity. A manual body is not edited through PATCH /manuals or PATCH /pages—content and tree mutations always use changesets. GET /pages/{pageId} accepts revision and format=json|html|markdown. Markdown responses include a loss report; canonical JSON is always returned so clients never depend on a lossy representation.

Atomic changesets and review

Method	Path	Scope	Purpose
`POST`	`/changesets/validate`	`instructions:write` or `instructions:propose` + workspace `EDITOR`/`OWNER`	Dry-run schema, revision, tree, audience, and asset validation.
`POST`	`/changesets/diff`	`instructions:write` or `instructions:propose` + workspace `EDITOR`/`OWNER`	Return a bounded page/node summary without writing.
`POST`	`/changesets/apply`	`instructions:write`	Apply every operation atomically or none. Accepts `Idempotency-Key`.
`POST`	`/changesets/submit`	`instructions:propose` + workspace `EDITOR`/`OWNER`	Store the same changeset for human review. Accepts `Idempotency-Key`.
`GET`	`/changesets?workspaceId=…`	`instructions:read`	List changesets, optionally filtered by status and cursor.
`GET`	`/changesets/{changesetId}`	`instructions:read`	Read a stored changeset and its operations.
`POST`	`/changesets/{changesetId}/approve`	`instructions:review`	Approve a submitted proposal, with an optional `decisionNote`.
`POST`	`/changesets/{changesetId}/reject`	`instructions:review`	Reject a submitted or approved proposal, with an optional `decisionNote`.
`POST`	`/changesets/{changesetId}/apply`	`instructions:write`	Revalidate and apply an approved proposal; drift records `CONFLICTED`.

Validate, diff, apply, and submit share one body:

{
  "workspaceId": "<workspaceId>",
  "description": "Add the reviewer edge-case section",
  "operations": [
    {
      "kind": "PATCH_CONTENT",
      "pageId": "<pageId>",
      "baseRevisionNumber": 3,
      "baseChecksum": "<pageChecksum>",
      "ops": [
        {
          "op": "append_children",
          "nodeId": null,
          "nodes": [
            {
              "type": "paragraph",
              "attrs": { "id": "edge-case-intro" },
              "content": [{ "type": "text", "text": "Escalate ambiguous evidence." }]
            }
          ]
        }
      ]
    }
  ]
}

Changesets support PATCH_CONTENT, explicitly confirmed REPLACE_CONTENT, CREATE_PAGE, RENAME_PAGE, MOVE_PAGE, SET_AUDIENCE, ARCHIVE_PAGE, RESTORE_PAGE, and ATTACH_ASSET. Node patches support replace_node, insert_before, insert_after, append_children, set_attrs, and delete_node. Use a clientPageKey on CREATE_PAGE and refer to the new parent as new:<clientPageKey> to create a nested section in one request. Operation order does not matter.

Whole-document replacement requires confirmReplace: true. Prefer stable-node patches so concurrent edits to unrelated blocks can be rebased safely.

Conflicts and idempotency

Revision, checksum, node, tree, schema, and asset conflicts are structured:

{
  "operationIndex": 0,
  "code": "REVISION_MISMATCH",
  "message": "The page changed after this edit was prepared.",
  "pageId": "<pageId>",
  "nodeId": null,
  "currentRevisionNumber": 4,
  "currentChecksum": "<currentChecksum>"
}

Possible conflict codes include REVISION_MISMATCH, CHECKSUM_MISMATCH, NODE_NOT_FOUND, PAGE_NOT_FOUND, MANUAL_NOT_FOUND, PARENT_NOT_FOUND, PAGE_ARCHIVED, DEPTH_EXCEEDED, TREE_CYCLE, DUPLICATE_CLIENT_KEY, AUDIENCE_INVALID, ASSET_NOT_READY, SCHEMA_INVALID, and REPLACE_NOT_CONFIRMED. Send a stable Idempotency-Key for creates, applies, submits, restores, and publications. Retrying the same request returns the original result; reusing the key with a different body returns 409.

Revisions and restoration

Method	Path	Scope	Purpose
`GET`	`/manuals/{manualId}/revisions`	`instructions:read`	List immutable manual revisions.
`GET`	`/manuals/{manualId}/revisions/diff?a=N&b=N`	`instructions:read`	Diff two revisions.
`POST`	`/manuals/{manualId}/revisions/{revisionNumber}/restore`	`instructions:write`	Restore a snapshot as a new audited head; history is never rewritten.

Publications

Method	Path	Scope	Purpose
`GET`	`/manuals/{manualId}/publications`	`instructions:read`	List immutable publications.
`POST`	`/manuals/{manualId}/publications`	`instructions:publish` + owner	Freeze an exact manual revision for one or more audiences. Accepts `Idempotency-Key`.
`GET`	`/manuals/{manualId}/publications/{publicationNumber}/manifest`	`instructions:read`	Read the immutable page manifest, optionally filtered by audience.

Publish with {"baseRevisionNumber":7,"audiences":["WORKER","REVIEWER"],"note":"First release"}. Audience values are ADMIN, CONTRIBUTOR, REVIEWER, and WORKER.

Private assets

Method	Path	Scope	Purpose
`GET`	`/assets?workspaceId=…`	`instructions:read`	List asset metadata and short-lived download URLs.
`GET`	`/assets/{assetId}`	`instructions:read`	Read one asset record and short-lived download URL.
`POST`	`/assets/prepare`	`instructions:write`	Validate metadata and obtain a short-lived signed `PUT` target.
`POST`	`/assets/{assetId}/finalize`	`instructions:write`	Verify the uploaded object and mark it ready.

Prepare accepts workspaceId, filename, mimeType, sizeBytes, sha256, and optional kind (IMAGE, FILE, AUDIO, or VIDEO). Upload the bytes to the returned URL with the returned headers, then finalize. Canonical documents reference asset IDs, never storage URLs.

Search and rendering

Method	Path	Scope	Purpose
`GET`	`/search`	`instructions:read`	Search accessible pages by query, workspace, manual, audience, and cursor.
`POST`	`/render-preview`	`instructions:read`	Render saved or ad-hoc canonical content as HTML or Markdown without writing.

Render preview accepts either {pageId,revisionNumber?,format} or {content,format}. format is html or markdown; Markdown always includes a machine-readable loss report.

Error envelope

Transport and permission failures use the standard API error shape:

{
  "error": "Human-readable summary",
  "code": "FORBIDDEN",
  "requestId": "<requestId>",
  "details": {}
}

Expect 400 for malformed requests or canonical documents, 403 for missing token scopes or workspace permission, 404 for inaccessible resources, and 409 for revision, checksum, tree, node, or idempotency conflicts.

Next steps

Instruction manuals explains the data model and safety guarantees.
Author instruction manuals walks through an end-to-end HTTP flow.
CLI: Instructions covers terminal and docs-as-code workflows.
MCP: Instructions tools lists the grouped agent tools and resources.

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Scopes and roles

Endpoint map

Discovery, workspaces, and permissions

Manuals, trees, and pages

Atomic changesets and review

Conflicts and idempotency

Revisions and restoration

Publications

Private assets

Search and rendering

Error envelope

Next steps

​Scopes and roles

​Endpoint map

​Discovery, workspaces, and permissions

​Manuals, trees, and pages

​Atomic changesets and review

​Conflicts and idempotency

​Revisions and restoration

​Publications

​Private assets

​Search and rendering

​Error envelope

​Next steps

Scopes and roles

Endpoint map

Discovery, workspaces, and permissions

Manuals, trees, and pages

Atomic changesets and review

Conflicts and idempotency

Revisions and restoration

Publications

Private assets

Search and rendering

Error envelope

Next steps