Enhance documentation

canvas.render

Render production-faithful canvas pixels into a protected PNG artifact.

canvas.render

mutation read

Use when the requested change exactly matches canvas.render; 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","anyOf":[{"anyOf":[{"type":"object","properties":{"canvasRef":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"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}},"required":["kind","bounds"],"additionalProperties":false}]},"sourceState":{"default":null,"anyOf":[{"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},{"type":"null"}]},"scale":{"default":1,"type":"number","exclusiveMinimum":0},"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}},"required":["canvasRef","expectedVersion","target"],"additionalProperties":false},{"type":"object","properties":{"canvasRef":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"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},"targets":{"minItems":1,"type":"array","items":{"type":"object","properties":{"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"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}},"required":["kind","bounds"],"additionalProperties":false}]},"sourceState":{"default":null,"anyOf":[{"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},{"type":"null"}]},"scale":{"default":1,"type":"number","exclusiveMinimum":0},"id":{"type":"string","minLength":1,"maxLength":80},"maxOutputPixels":{"description":"Optional requested pixel budget for this target.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["target","id"],"additionalProperties":false}}},"required":["canvasRef","expectedVersion","targets"],"additionalProperties":false}],"type":"object"},{"type":"object","properties":{"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)$"},"expectedVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Exact document version to render, or null to accept the current version."},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"]},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"]},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"]}},"required":["kind","bounds"]}],"description":"Area to render: all authored content, one stable node id, or explicit world-space bounds."},"sourceState":{"anyOf":[{"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"]},{"type":"null"}],"description":"Recording moment to display while rendering its recording node, or null."},"scale":{"type":"number","exclusiveMinimum":0,"description":"Output pixels per canvas unit."},"outputPath":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Local PNG path, or null for a protected temporary artifact."},"overwrite":{"type":"boolean","description":"Whether an existing outputPath may be replaced."},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local render polling deadline in milliseconds."},"timeoutOutcome":{"type":"string","const":"pending"},"scope":{"type":"object","properties":{"pageId":{"type":"string"},"nodeIds":{"type":"array","items":{"type":"string"}}},"required":["nodeIds"],"additionalProperties":false}},"required":["canvasId","expectedVersion","target","sourceState","scale","outputPath","overwrite","timeoutMs"]}],"type":"object"}

Example

Show example input

{
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "expectedVersion": 1,
 "target": {
  "kind": "content"
 },
 "sourceState": null,
 "scale": 1,
 "outputPath": null,
 "overwrite": false,
 "timeoutMs": 120000
}

Result

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

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

Inspect the returned image; read more structure only if the pixels reveal a discrepancy.

Compatibility: c02d9faa983246a7d9d72803249a76026947eaaaca45cfc43e278b67ac06a46e.