comments.patch

Patch fields on an existing comment (text, target, status, or isInternal).

Alpha: Document API is currently alpha and subject to breaking changes.

Summary

Patch fields on an existing comment (text, target, status, or isInternal).

• Operation ID: comments.patch
• API member path: editor.doc.comments.patch(...)
• Mutates document: yes
• Idempotency: conditional
• Supports tracked mode: no
• Supports dry run: no
• Deterministic target resolution: yes

Expected result

Returns a Receipt confirming the comment was updated; reports NO_OP if no fields changed.

Input fields

Field	Type	Required	Description
commentId	string	yes
isInternal	boolean	no
status	enum	no	"resolved"
target	TextAddress	no	TextAddress
target.blockId	string	no
target.kind	"text"	no	Constant: "text"
target.range	Range	no	Range
target.range.end	integer	no
target.range.start	integer	no
text	string	no

Example request

{
  "commentId": "comment-001",
  "target": {
    "blockId": "block-abc123",
    "kind": "text",
    "range": {
      "end": 10,
      "start": 0
    }
  },
  "text": "Hello, world."
}

Output fields

Variant 1 (success=true)

Field	Type	Required	Description
inserted	EntityAddress[]	no
removed	EntityAddress[]	no
success	true	yes	Constant: true
updated	EntityAddress[]	no

Variant 2 (success=false)

Field	Type	Required	Description
failure	object	yes
failure.code	enum	yes	"INVALID_TARGET", "NO_OP"
failure.details	any	no
failure.message	string	yes
success	false	yes	Constant: false

Example response

{
  "inserted": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ],
  "success": true,
  "updated": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ]
}

Pre-apply throws

• TARGET_NOT_FOUND
• CAPABILITY_UNAVAILABLE
• INVALID_TARGET
• INVALID_INPUT

Non-applied failure codes

• INVALID_TARGET
• NO_OP

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "commentId": {
      "type": "string"
    },
    "isInternal": {
      "type": "boolean"
    },
    "status": {
      "enum": [
        "resolved"
      ]
    },
    "target": {
      "$ref": "#/$defs/TextAddress"
    },
    "text": {
      "type": "string"
    }
  },
  "required": [
    "commentId"
  ],
  "type": "object"
}

Raw output schema

{
  "oneOf": [
    {
      "$ref": "#/$defs/ReceiptSuccess"
    },
    {
      "additionalProperties": false,
      "properties": {
        "failure": {
          "additionalProperties": false,
          "properties": {
            "code": {
              "enum": [
                "INVALID_TARGET",
                "NO_OP"
              ]
            },
            "details": {},
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "$ref": "#/$defs/ReceiptSuccess"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "INVALID_TARGET",
            "NO_OP"
          ]
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure"
  ],
  "type": "object"
}