Skip to main content
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.

​
Endpoints

​
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.