> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# comments.patch
> Patch exactly one field on an existing comment (`text`, `target`, or `status`). The `target` branch accepts a plain TextAddress or a TrackedChangeCommentTarget, with or without `kind: "trackedChange"`, that names a logical tracked-change id. The legacy `isInternal` input is preserved in the schema for v1 backward compatibility but is not supported for new patch behavior and fails with `CAPABILITY_UNAVAILABLE` (kernel reason `internal-comments-unsupported`). Multi-field patches and no-op edits are rejected with `INVALID_INPUT`; reply target / status patches are rejected with `INVALID_CONTEXT`.
## Summary
Patch exactly one field on an existing comment (`text`, `target`, or `status`). The `target` branch accepts a plain TextAddress or a TrackedChangeCommentTarget, with or without `kind: "trackedChange"`, that names a logical tracked-change id. The legacy `isInternal` input is preserved in the schema for v1 backward compatibility but is not supported for new patch behavior and fails with `CAPABILITY_UNAVAILABLE` (kernel reason `internal-comments-unsupported`). Multi-field patches and no-op edits are rejected with `INVALID_INPUT`; reply target / status patches are rejected with `INVALID_CONTEXT`.
* 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 with `updated` populated on success. Reports `NO_OP` for byte-identical edits, rejects empty-body / trim-equivalent edits with `INVALID_INPUT`, no-op resolve/reopen with `INVALID_INPUT`, reply target/status with `INVALID_CONTEXT`, cross-story moves with `INVALID_CONTEXT`, materializing inherited slot moves with `CAPABILITY_UNAVAILABLE`, stale tracked-change targets with `TARGET_NOT_FOUND`, formatting / structural / unpaired-move tracked-change targets with `CAPABILITY_UNAVAILABLE`, and `isInternal` patches with `CAPABILITY_UNAVAILABLE`.
## Input fields
| Field | Type | Required | Description |
| ------------ | ---------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `commentId` | string | yes | |
| `isInternal` | boolean | no | |
| `status` | enum | no | `"resolved"`, `"active"` |
| `target` | TextAddress \| SelectionTarget \| CommentTrackedChangeTarget \| object | no | One of: TextAddress, SelectionTarget, CommentTrackedChangeTarget, object |
| `text` | string | no | |
### Example request
```json theme={null}
{
"commentId": "comment-001",
"target": {
"blockId": "block-abc123",
"kind": "text",
"range": {
"end": 10,
"start": 0
},
"story": {
"kind": "story",
"storyType": "body"
}
},
"text": "Hello, world."
}
```
## Output fields
### Variant 1 (success=true)
| Field | Type | Required | Description |
| ----------------- | ----------------------- | -------- | ---------------- |
| `affectedStories` | StoryLocator\[] | no | |
| `id` | string | no | |
| `inserted` | EntityAddress\[] | no | |
| `invalidatedRefs` | AffectedRef\[] | no | |
| `remappedRefs` | AffectedRefRemapping\[] | no | |
| `removed` | EntityAddress\[] | no | |
| `success` | `true` | yes | Constant: `true` |
| `textRangeShifts` | TextRangeShift\[] | no | |
| `txId` | string | no | |
| `updated` | EntityAddress\[] | no | |
### Variant 2 (success=false)
| Field | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `failure` | object | yes | |
| `failure.code` | enum | yes | `"INVALID_INPUT"`, `"INVALID_TARGET"`, `"INVALID_CONTEXT"`, `"TARGET_NOT_FOUND"`, `"CAPABILITY_UNAVAILABLE"`, `"NO_OP"` |
| `failure.details` | any | no | |
| `failure.message` | string | yes | |
| `success` | `false` | yes | Constant: `false` |
### Example response
```json theme={null}
{
"id": "id-001",
"inserted": [
{
"entityId": "entity-789",
"entityType": "comment",
"kind": "entity"
}
],
"success": true
}
```
## Pre-apply throws
* `TARGET_NOT_FOUND`
* `CAPABILITY_UNAVAILABLE`
* `INVALID_TARGET`
* `INVALID_INPUT`
## Non-applied failure codes
* `INVALID_INPUT`
* `INVALID_TARGET`
* `INVALID_CONTEXT`
* `TARGET_NOT_FOUND`
* `CAPABILITY_UNAVAILABLE`
* `NO_OP`
## Raw schemas
```json theme={null}
{
"additionalProperties": false,
"properties": {
"commentId": {
"type": "string"
},
"isInternal": {
"description": "Legacy v1/document-api compatibility field. Not supported for new comment patch behavior. A `comments.patch` request containing `isInternal` fails with `CAPABILITY_UNAVAILABLE` (kernel reason `internal-comments-unsupported`). The field is preserved in the schema only so v1 callers keep their input shape (`comments-spec.md` §7, §14.6).",
"type": "boolean"
},
"status": {
"description": "Set comment status. Use 'resolved' to resolve a comment, or 'active' to reopen a previously resolved comment (lifecycle inverse).",
"enum": [
"resolved",
"active"
]
},
"target": {
"description": "New anchor for the comment. Accepts a plain TextAddress, a SelectionTarget {kind:'selection', start, end}, a TextSearchCommentTarget {text, story?}, or a TrackedChangeCommentTarget, with or without kind, that names a logical tracked-change id as a convenience re-anchor target .",
"oneOf": [
{
"$ref": "#/$defs/TextAddress"
},
{
"$ref": "#/$defs/SelectionTarget"
},
{
"$ref": "#/$defs/CommentTrackedChangeTarget"
},
{
"additionalProperties": false,
"properties": {
"story": {
"$ref": "#/$defs/StoryLocator"
},
"text": {
"description": "Text to find and anchor the comment to. The adapter resolves the first body/story match.",
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
}
]
},
"text": {
"description": "Updated comment text.",
"type": "string"
}
},
"required": [
"commentId"
],
"type": "object"
}
```
```json theme={null}
{
"oneOf": [
{
"$ref": "#/$defs/ReceiptSuccess"
},
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"INVALID_INPUT",
"INVALID_TARGET",
"INVALID_CONTEXT",
"TARGET_NOT_FOUND",
"CAPABILITY_UNAVAILABLE",
"NO_OP"
]
},
"details": {},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}
]
}
```
```json theme={null}
{
"$ref": "#/$defs/ReceiptSuccess"
}
```
```json theme={null}
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"INVALID_INPUT",
"INVALID_TARGET",
"INVALID_CONTEXT",
"TARGET_NOT_FOUND",
"CAPABILITY_UNAVAILABLE",
"NO_OP"
]
},
"details": {},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}
```