Job Instructions API

The Instructions API reads and edits the pages in a real job’s employer Instructions tab. Every path is keyed by jobId; there is no separate workspace, manual, binding, review, or publication resource.

Base path: /api/public/v1/instructions/jobs/{jobId}

Endpoints

Method	Path	Purpose
GET	/instructions/capabilities	Discover schemas, limits, imports, rich nodes, and mutation guarantees.
GET	/instructions/jobs/{jobId}	Inspect the canonical tree and employer URL.
POST	/instructions/jobs/{jobId}/preview	Validate and render TipTap JSON without writing.
POST	/instructions/jobs/{jobId}/preflight	Validate and sign one exact page mutation without writing.
GET	/instructions/jobs/{jobId}/verify	Validate and checksum every canonical page.
GET	/instructions/jobs/{jobId}/visual-review	Return the employer URL and visual-review checklist.
POST	/instructions/jobs/{jobId}/tree/preflight	Validate and sign one complete desired tree without writing.
POST	/instructions/jobs/{jobId}/tree/apply	Atomically apply the exact preflighted tree.
POST	/instructions/jobs/{jobId}/assets/images/plan	Plan a stable final image URL without uploading bytes.
POST	/instructions/jobs/{jobId}/assets/images	Upload one supported image without editing a page.
POST	/instructions/jobs/{jobId}/pages	Idempotently create a root page or one-level subpage.
GET	/instructions/jobs/{jobId}/pages/{pageId}	Read one page and checksum.
PUT	/instructions/jobs/{jobId}/pages/{pageId}	Replace a complete page document.
PATCH	/instructions/jobs/{jobId}/pages/{pageId}	Patch content or update title/tree metadata.
DELETE	/instructions/jobs/{jobId}/pages/{pageId}	Archive a page.

Authorization

Capabilities is authenticated. Job reads and verification require instructions:read. Preview, preflight, image planning/upload, and mutations require instructions:write. The token owner must also have employer access to the job.

Write safety

The job editor is immediately live. Preview and preflight write nothing and return writesApplied: false. Each mutation body requires confirmLive: true and the short-lived preflightToken signed for that exact operation. A token cannot authorize changed content, metadata, placement, target, or checksum.

Page creation also requires an Idempotency-Key header. Patch and replacement use the checksum from the last page read. Replacement requires confirmReplace: true; archive requires confirmArchive: true.

The page tree supports root pages plus one subpage level. Requests for deeper nesting return a tree conflict. Complete-tree apply also requires confirmTreeReplace: true, an idempotency key, the exact expected tree checksum, and the archive set returned by tree preflight. The applied tree becomes visible atomically.

Canonical responses

Responses identify canonicalSource: "JOB_INSTRUCTION_SET" and include the exact employer URL. Applied writes address the same TipTap document used by the web editor and worker resolver.

Supported image types are JPEG, PNG, WebP, GIF, and AVIF up to 5 MB. Image plan returns the stable final URL for reviewed content without uploading. Image upload returns that URL after storing the bytes; neither endpoint mutates a page.

Visual review returns a fast employer-surface checklist. The separate hosted visual-proof API renders the real employer workspace or a real designated test-worker reader in Chromium and returns PNG, ARIA, diagnostics, and provenance evidence. It does not require the agent to hold a browser or Vercel session.

Use the machine-readable OpenAPI document for complete schemas.