Author Instruction Manuals

This guide walks the full agent authoring loop with the HTTP API. The CLI and MCP tools wrap the same endpoints one-to-one, so every step translates directly. Requirements: a verified user who belongs to an employer organization, plus a personal API token with instructions:read and either instructions:write (direct authoring) or instructions:propose (reviewed proposals). Proposal authors need workspace EDITOR or OWNER; reviewer decisions need instructions:review plus REVIEWER or OWNER. Publishing needs instructions:publish plus OWNER. See scopes.

1. Discover the vocabulary

Fetch the schema contract once and cache it — it tells you every valid node type, mark, attribute, operation, audience, and asset limit:

curl -s https://app.opentrain.ai/api/public/v1/instructions/capabilities \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN"

Author only node/mark types the response lists. Unknown types are rejected at write time because the human editor cannot round-trip them.

2. Create a workspace and manual

curl -s -X POST https://app.opentrain.ai/api/public/v1/instructions/workspaces \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN" \
  -H "Idempotency-Key: ws-setup-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Operations"}'

curl -s -X POST https://app.opentrain.ai/api/public/v1/instructions/workspaces/{workspaceId}/manuals \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN" \
  -H "Idempotency-Key: manual-setup-1" \
  -H "Content-Type: application/json" \
  -d '{"title": "Reviewer handbook", "defaultAudience": "REVIEWER", "bindings": [{"kind": "WORK_PROJECT", "targetId": "<projectId>", "precedence": 0}]}'

Bindings decide where the manual appears: on a job, a folder, or a work project. More specific bindings win (job over folder over work project).

3. Author nested pages in one atomic changeset

Give each CREATE_PAGE a clientPageKey, then reference it from children as new:<key> — order doesn’t matter, and the whole section lands atomically or not at all:

curl -s -X POST https://app.opentrain.ai/api/public/v1/instructions/changesets/apply \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN" \
  -H "Idempotency-Key: handbook-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<workspaceId>",
    "description": "Initial handbook structure",
    "operations": [
      {"kind": "CREATE_PAGE", "manualId": "<manualId>", "parentPageId": null, "title": "Review workflow", "clientPageKey": "workflow"},
      {"kind": "CREATE_PAGE", "manualId": "<manualId>", "parentPageId": "new:workflow", "title": "Edge cases", "clientPageKey": "edge-cases"}
    ]
  }'

The response returns the new page IDs, each page’s revision and checksum, and the manual’s new head revision. Keep those — subsequent edits must present them as base guards.

4. Edit content with stable-node patches

Read a page (GET /pages/{pageId}) to get its canonical JSON, revision, and per-block attrs.id values, then patch specific blocks:

{
  "workspaceId": "<workspaceId>",
  "operations": [{
    "kind": "PATCH_CONTENT",
    "pageId": "<pageId>",
    "baseRevisionNumber": 3,
    "ops": [
      {"op": "append_children", "nodeId": null, "nodes": [
        {"type": "paragraph", "content": [{"type": "text", "text": "Always cite the rubric row you applied."}]}
      ]}
    ]
  }]
}

If another writer changed the page first, you get a structured REVISION_MISMATCH conflict with the current revision — re-read, rebase your patch, retry. Run the same body through /changesets/validate first when you want a dry run.

5. Attach private media

# 1. Register the bytes you are about to upload
curl -s -X POST https://app.opentrain.ai/api/public/v1/instructions/assets/prepare \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId": "<workspaceId>", "filename": "walkthrough.mp4", "mimeType": "video/mp4", "sizeBytes": 104857600, "sha256": "<hex>", "kind": "VIDEO"}'
# 2. PUT the file bytes to the returned upload.url with the returned headers
# 3. Finalize so the asset becomes READY
curl -s -X POST https://app.opentrain.ai/api/public/v1/instructions/assets/{assetId}/finalize \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN"

Then attach it with an ATTACH_ASSET operation. Documents reference assets by ID only; readers get short-lived signed URLs. Finalization checks the prepared object and trusted upload metadata, but it does not independently download and re-hash the stored bytes; keep your local SHA-256 as the source integrity check.

6. Propose, review, publish

On a shared manual, an EDITOR or OWNER can submit instead of applying: POST /changesets/submit stores the proposal and returns a review URL. A REVIEWER or OWNER approves or rejects it (optionally with a decisionNote), and the approved proposal is applied by ID — still revision-guarded, so stale proposals conflict instead of clobbering newer edits. When the manual is ready for workers:

curl -s -X POST https://app.opentrain.ai/api/public/v1/instructions/manuals/{manualId}/publications \
  -H "Authorization: Bearer $OPENTRAIN_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"baseRevisionNumber": 7, "audiences": ["WORKER", "REVIEWER"], "note": "First worker release"}'

Workers read only publications, filtered to their audience — never your drafts.

Prefer files? Use the CLI’s docs-as-code loop

opentrain instructions checkout materializes a manual as local JSON files with a manifest of revisions and checksums; edit, status/diff, then sync pushes your changes back as one guarded changeset. See the CLI reference.

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Author Instruction Manuals

1. Discover the vocabulary

2. Create a workspace and manual

3. Author nested pages in one atomic changeset

4. Edit content with stable-node patches

5. Attach private media

6. Propose, review, publish

Prefer files? Use the CLI’s docs-as-code loop

​1. Discover the vocabulary

​2. Create a workspace and manual

​3. Author nested pages in one atomic changeset

​4. Edit content with stable-node patches

​5. Attach private media

​6. Propose, review, publish

​Prefer files? Use the CLI’s docs-as-code loop

1. Discover the vocabulary

2. Create a workspace and manual

3. Author nested pages in one atomic changeset

4. Edit content with stable-node patches

5. Attach private media

6. Propose, review, publish

Prefer files? Use the CLI’s docs-as-code loop