# watermarks.apply > Atomically insert, replace, or remove selected watermarks in explicit scopes while preserving surrounding headers. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`. - Member path: `doc.watermarks.apply(…)` - Mutates document: yes - Idempotency: `conditional` - Supports tracked mode: no - Supports dry run: yes ## Expected result Returns the resulting watermarks, changed header slots, preserved boundaries, and evaluated revision. ## Input schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] } }, "oneOf": [ { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "document" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "headerFooterSlots" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "kind": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "const": "header" }, "variant": { "enum": [ "default", "first", "even" ] } }, "additionalProperties": false, "required": [ "kind", "section", "headerFooterKind", "variant" ] }, "minItems": 1, "uniqueItems": true } }, "additionalProperties": false, "required": [ "kind", "slots" ] } ] }, "action": { "const": "insert" }, "watermark": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "text": { "type": "string", "minLength": 1 }, "fontFamily": { "type": "string", "minLength": 1 }, "fontSizePt": { "oneOf": [ { "const": "auto" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "orientation": { "enum": [ "horizontal", "diagonal" ] }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "const": "picture" }, "src": { "type": "string", "minLength": 1 }, "scalePercent": { "enum": [ "auto", 50, 100, 150, 200, 500 ] }, "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "lockAspectRatio": { "type": "boolean" }, "washout": { "type": "boolean" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "kind", "src" ] } ] } }, "additionalProperties": false, "required": [ "target", "action", "watermark" ] }, { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "document" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "headerFooterSlots" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "kind": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "const": "header" }, "variant": { "enum": [ "default", "first", "even" ] } }, "additionalProperties": false, "required": [ "kind", "section", "headerFooterKind", "variant" ] }, "minItems": 1, "uniqueItems": true } }, "additionalProperties": false, "required": [ "kind", "slots" ] } ] }, "action": { "const": "replace" }, "watermarkIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true }, "watermark": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "text": { "type": "string", "minLength": 1 }, "fontFamily": { "type": "string", "minLength": 1 }, "fontSizePt": { "oneOf": [ { "const": "auto" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "orientation": { "enum": [ "horizontal", "diagonal" ] }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "const": "picture" }, "src": { "type": "string", "minLength": 1 }, "scalePercent": { "enum": [ "auto", 50, 100, 150, 200, 500 ] }, "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "lockAspectRatio": { "type": "boolean" }, "washout": { "type": "boolean" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "kind", "src" ] }, { "type": "object", "properties": { "kind": { "const": "picture" }, "src": { "not": {} }, "scalePercent": { "enum": [ "auto", 50, 100, 150, 200, 500 ] }, "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "lockAspectRatio": { "type": "boolean" }, "washout": { "type": "boolean" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false }, "source": { "type": "object", "properties": { "kind": { "const": "existing" }, "watermarkId": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "kind", "watermarkId" ] } }, "additionalProperties": false, "required": [ "kind", "source" ] } ] } }, "additionalProperties": false, "required": [ "target", "action", "watermarkIds", "watermark" ] }, { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "document" } }, "additionalProperties": false, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "headerFooterSlots" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "kind": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "const": "header" }, "variant": { "enum": [ "default", "first", "even" ] } }, "additionalProperties": false, "required": [ "kind", "section", "headerFooterKind", "variant" ] }, "minItems": 1, "uniqueItems": true } }, "additionalProperties": false, "required": [ "kind", "slots" ] } ] }, "action": { "const": "remove" }, "watermarkIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true } }, "additionalProperties": false, "required": [ "target", "action", "watermarkIds" ] } ] } ``` ## Output schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] } }, "oneOf": [ { "type": "object", "properties": { "success": { "const": true }, "watermarks": { "type": "array", "items": { "type": "object", "properties": { "watermarkId": { "type": "string" }, "owner": { "type": "object", "properties": { "refId": { "type": "string" }, "partPath": { "type": "string" } }, "additionalProperties": false, "required": [ "refId", "partPath" ] }, "effectiveIn": { "type": "array", "items": { "type": "object", "properties": { "kind": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "const": "header" }, "variant": { "enum": [ "default", "first", "even" ] } }, "additionalProperties": false, "required": [ "kind", "section", "headerFooterKind", "variant" ] } }, "watermark": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "text": { "type": "string", "minLength": 1 }, "fontFamily": { "type": "string", "minLength": 1 }, "fontSizePt": { "oneOf": [ { "const": "auto" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "orientation": { "enum": [ "horizontal", "diagonal" ] }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "const": "picture" }, "mediaPartPath": { "type": "string" }, "contentType": { "type": "string" }, "scalePercent": { "enum": [ "auto", 50, 100, 150, 200, 500 ] }, "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "lockAspectRatio": { "type": "boolean" }, "washout": { "type": "boolean" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "placement": { "type": "object", "properties": { "widthPt": { "type": "number", "exclusiveMinimum": 0 }, "heightPt": { "type": "number", "exclusiveMinimum": 0 }, "rotationDegrees": { "type": "number" }, "behindText": { "type": "boolean" }, "horizontal": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "left", "center", "right" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] }, "vertical": { "type": "object", "properties": { "relativeFrom": { "enum": [ "page", "margin" ] }, "alignment": { "enum": [ "top", "center", "bottom" ] }, "offsetPt": { "type": "number" } }, "additionalProperties": false, "required": [ "relativeFrom" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "kind", "mediaPartPath", "contentType", "scalePercent", "widthPt", "heightPt", "lockAspectRatio", "washout", "opacity", "placement" ] } ] } }, "additionalProperties": false, "required": [ "watermarkId", "owner", "effectiveIn", "watermark" ] } }, "affectedSlots": { "type": "array", "items": { "type": "object", "properties": { "kind": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "const": "header" }, "variant": { "enum": [ "default", "first", "even" ] } }, "additionalProperties": false, "required": [ "kind", "section", "headerFooterKind", "variant" ] } }, "preservedSlots": { "type": "array", "items": { "type": "object", "properties": { "kind": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "const": "header" }, "variant": { "enum": [ "default", "first", "even" ] } }, "additionalProperties": false, "required": [ "kind", "section", "headerFooterKind", "variant" ] } }, "evaluatedRevision": { "type": "string" }, "dryRun": { "const": true } }, "additionalProperties": false, "required": [ "success", "watermarks", "affectedSlots", "preservedSlots", "evaluatedRevision" ] }, { "type": "object", "properties": { "success": { "const": false }, "failure": { "type": "object", "properties": { "code": { "enum": [ "TARGET_NOT_FOUND", "INVALID_TARGET", "INVALID_INPUT", "PRECONDITION_FAILED", "CAPABILITY_UNAVAILABLE", "REVISION_MISMATCH", "PERMISSION_DENIED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": {} }, "additionalProperties": false, "required": [ "code", "message" ] } }, "additionalProperties": false, "required": [ "success", "failure" ] } ] } ``` ## Pre-apply throws - `INVALID_INPUT` - `INVALID_TARGET` - `CAPABILITY_UNAVAILABLE` - `INTERNAL_ERROR` ## Non-applied receipt codes - `TARGET_NOT_FOUND` - `INVALID_TARGET` - `INVALID_INPUT` - `PRECONDITION_FAILED` - `CAPABILITY_UNAVAILABLE` - `REVISION_MISMATCH` - `PERMISSION_DENIED` - `INTERNAL_ERROR`