Enhance documentation

canvas.capture

Freeze an inspected recording moment into a durable screen on its source page, holding the observed canvas revision through attachment.

↓ Markdown

canvas.capture

mutation write

Use when the requested change exactly matches canvas.capture; read the current state first when a version or identifier may have changed.

Before calling

Authenticate as the accountable Enhance person.
Use only resource identifiers returned by an earlier capability result or supplied by the person.
Reuse clientToken only when retrying this exact mutation input.

Input

Show complete JSON Schema

{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"canvasRef":{"type":"string","minLength":1},"waitMs":{"default":1500,"description":"Additional local polling after the server returns an active job; render creation retains its existing bounded HTTP deadline.","type":"integer","minimum":0,"maximum":5000},"baseVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"source":{"type":"object","properties":{"kind":{"type":"string","const":"recording"},"recordingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"atMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","recordingId","atMs"],"additionalProperties":false},"previewJobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The successful canvas_render job whose pixels you inspected at this exact recording time and canvas version."},"placement":{"type":"object","properties":{"kind":{"type":"string","const":"below-source"}},"required":["kind"],"additionalProperties":false}},"required":["canvasRef","baseVersion","source","previewJobId","placement"],"additionalProperties":false}

Example

Show example input

{
 "canvasRef": "00000000-0000-4000-8000-000000000010",
 "baseVersion": 1,
 "source": {
  "kind": "recording",
  "recordingId": "00000000-0000-4000-8000-000000000010",
  "atMs": 500
 },
 "previewJobId": "00000000-0000-4000-8000-000000000010",
 "placement": {
  "kind": "below-source"
 },
 "waitMs": 1500
}

Result

Returns a typed canvas.capture result from the Enhance API without transport-specific prose.

operation (required): Returned field operation.
state (required): Returned field state.
requestedVersion (required): Returned field requestedVersion.
source (required): Returned field source.
attachment (required): Returned field attachment.
result (required): Returned field result.
failure (required): Returned field failure.
warningCount (required): Returned field warningCount.
warnings (required): Returned field warnings.

Show complete result JSON Schema

{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-render"},"canvasId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["kind","canvasId","jobId"],"additionalProperties":false},"state":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"]},"requestedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"source":{"type":"object","properties":{"kind":{"type":"string","const":"recording"},"recordingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"atMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","recordingId","atMs"],"additionalProperties":false},"attachment":{"type":"string","enum":["pending","committed","not_confirmed"]},"result":{"anyOf":[{"type":"object","properties":{"recordingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"atMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"screenId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"screenNodeId":{"type":"string","minLength":1},"viewport":{"type":"object","properties":{"width":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"height":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["width","height"],"additionalProperties":false},"box":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"],"additionalProperties":false},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"alreadyPresent":{"type":"boolean"}},"required":["recordingId","atMs","screenId","screenNodeId","viewport","box","version","alreadyPresent"],"additionalProperties":false},{"type":"null"}]},"failure":{"anyOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["VERSION_CHANGED","TARGET_NOT_FOUND","TARGET_INVALID","OUTPUT_TOO_LARGE","READINESS_TIMEOUT","SOURCE_FAILED","BROWSER_CRASH","CAPTURE_FAILED","CONVERSION_FAILED","PREPARATION_FAILED","UPLOAD_FAILED","WORKER_UNAVAILABLE","CANCELLED","EXPIRED","INTERNAL"]},"phase":{"type":"string","enum":["queued","claimed","grant","navigate","document","sources","fonts","layout","target","capture","serialize","compile","commit","upload","complete"]},"message":{"type":"string","minLength":1,"maxLength":500},"retryable":{"type":"boolean"},"sourceId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["reason","phase","message","retryable","sourceId"],"additionalProperties":false},{"type":"null"}]},"warningCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"warnings":{"type":"array","items":{"type":"string"}}},"required":["operation","state","requestedVersion","source","attachment","result","failure","warningCount","warnings"],"additionalProperties":false}

Example result

Show example result

{
 "operation": {
  "kind": "canvas-render",
  "canvasId": "00000000-0000-4000-8000-000000000010",
  "jobId": "00000000-0000-4000-8000-000000000010"
 },
 "state": "queued",
 "requestedVersion": 1,
 "source": {
  "kind": "recording",
  "recordingId": "00000000-0000-4000-8000-000000000010",
  "atMs": 500
 },
 "attachment": "pending",
 "result": null,
 "failure": null,
 "warningCount": 0,
 "warnings": []
}

Recovery

BAD_REQUEST: correct the named fields and call again.
UNAUTHORIZED: restore Enhance authentication, then retry once.
FORBIDDEN or NOT_FOUND: check the supplied resource and selection; do not substitute unrelated content. Ask for corrected access or scope if needed.
CONFLICT: read the current resource, merge the intended change, and retry with its version.
INTERNAL: run Enhance diagnostics, report the failure, and stop repeating the call.

Continue with

Read the affected canvas resource to confirm the result.

Versions

Compatibility: 219dfc283ee61d5bf1305c451a464c8d2e9b5de80191b78b773f547a51867d61.

Minimum tested versions: Enhance CLI and MCP runtime 0.1.40, plugin 1.0.38, Node.js 24. No older floor is published.