# watermarks.list

> List Word-compatible text and picture watermarks and their effective header scopes. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.



- Member path: `doc.watermarks.list(…)`
- Mutates document: no
- Idempotency: `idempotent`
- Supports tracked mode: no
- Supports dry run: no

## Expected result

Returns a paginated WatermarksListResult with stable watermark identities and Word placement settings.

## 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"
      ]
    }
  },
  "type": "object",
  "properties": {
    "target": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "document"
            }
          },
          "additionalProperties": false,
          "required": [
            "kind"
          ]
        },
        {
          "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"
          ]
        }
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false
}
```

## 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"
      ]
    },
    "PageInfo": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "minimum": 0
        },
        "returned": {
          "type": "integer",
          "minimum": 0
        }
      },
      "additionalProperties": false,
      "required": [
        "limit",
        "offset",
        "returned"
      ]
    }
  },
  "type": "object",
  "properties": {
    "evaluatedRevision": {
      "type": "string"
    },
    "total": {
      "type": "integer",
      "minimum": 0
    },
    "items": {
      "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"
        ]
      }
    },
    "page": {
      "$ref": "#/$defs/PageInfo"
    }
  },
  "additionalProperties": false,
  "required": [
    "evaluatedRevision",
    "total",
    "items",
    "page"
  ]
}
```

## Pre-apply throws

- `INVALID_INPUT`
- `INVALID_TARGET`
- `CAPABILITY_UNAVAILABLE`

## Non-applied receipt codes

- None