trackChanges.get

Summary

Retrieve a single tracked change by SuperDoc logical id.

Operation ID: trackChanges.get
API member path: editor.doc.trackChanges.get(...)
Mutates document: no
Idempotency: idempotent
Supports tracked mode: no
Supports dry run: no
Deterministic target resolution: yes

Expected result

Returns a TrackChangeInfo object with the logical id, semantic type/subtype, state, target, before/after snapshots, author/initials/email, date, revisionGroupId, splitFromId, replacement or move side metadata when applicable, story locator, excerpt, optional overlap metadata, and source provenance via sourceIds / wordRevisionIds. Structural whole-table changes surface subtypes such as table-insert and table-delete.

Input fields

Field	Type	Required	Description
`id`	string	yes
`story`	StoryLocator	no	StoryLocator

Example request

{
  "id": "id-001",
  "story": {
    "kind": "story",
    "storyType": "body"
  }
}

Output fields

Field	Type	Required	Description
`address`	TrackedChangeAddress	yes	TrackedChangeAddress
`address.entityId`	string	yes
`address.entityType`	`"trackedChange"`	yes	Constant: `"trackedChange"`
`address.kind`	`"entity"`	yes	Constant: `"entity"`
`address.story`	StoryLocator	no	StoryLocator
`addressKind`	enum	no	`"entity"`, `"story-entity"`, `"unknown"`
`after`	object	no
`after.formatting`	object	no
`after.formatting.properties`	object	no
`after.formatting.xml`	string	no
`after.text`	string	no
`author`	string	no
`authorEmail`	string	no
`authorImage`	string	no
`before`	object	no
`before.formatting`	object	no
`before.formatting.properties`	object	no
`before.formatting.xml`	string	no
`before.text`	string	no
`canonicalizationKind`	enum	no	`"single-word-revision"`, `"paired-word-revision"`, `"generated-runtime-id"`, `"unknown"`
`date`	string	no
`deletedText`	string \| null	no	One of: string, null
`excerpt`	string	no
`formattingDeltaSummary`	string \| null	no	One of: string, null
`grouping`	enum	no	`"standalone"`, `"replacement-pair"`, `"unknown"`
`id`	string	yes
`imported`	boolean	no
`initials`	string	no
`insertedText`	string \| null	no	One of: string, null
`origin`	enum	no	`"word"`, `"google-docs"`, `"superdoc"`, `"unknown"`
`overlap`	object	no
`overlap.parentId`	string	no
`overlap.preferredContextTarget`	object	no
`overlap.preferredContextTarget.id`	string	no
`overlap.preferredContextTarget.relationship`	enum	no	`"parent"`, `"child"`, `"standalone"`
`overlap.preferredContextTarget.type`	enum	no	`"insertion"`, `"deletion"`, `"replacement"`, `"formatting"`, `"move"`, `"structural"`, `"insert"`, `"delete"`, `"format"`
`overlap.preferredContextTargetId`	string	no
`overlap.relationship`	enum	no	`"parent"`, `"child"`, `"standalone"`
`overlap.visualLayers`	object[]	no
`pairedWithChangeId`	string \| null	no	One of: string, null
`replacement`	object	no
`replacement.deleted`	object \| null	no	One of: object, null
`replacement.inserted`	object \| null	no	One of: object, null
`resolvableById`	boolean	no
`revisionGroupId`	string	no
`sourceIds`	object	no
`sourceIds.rsids`	string[]	no
`sourceIds.wordIdDelete`	string	no
`sourceIds.wordIdInsert`	string	no
`sourceIds.wordIdOther`	string[]	no
`sourcePlatform`	enum	no	`"word"`, `"google-docs"`, `"superdoc"`, `"unknown"`
`splitFromId`	string \| null	no	One of: string, null
`state`	enum	no	`"open"`, `"accepted"`, `"rejected"`
`storyLocator`	StoryLocator	no	StoryLocator
`subtype`	string	no
`target`	object \| object \| object	no	One of: object, object, object
`type`	enum	yes	`"insertion"`, `"deletion"`, `"replacement"`, `"formatting"`, `"move"`, `"structural"`, `"insert"`, `"delete"`, `"format"`
`wordRevisionIds`	object	no
`wordRevisionIds.delete`	string	no
`wordRevisionIds.format`	string	no
`wordRevisionIds.insert`	string	no

Example response

{
  "address": {
    "entityId": "entity-789",
    "entityType": "trackedChange",
    "kind": "entity",
    "story": {
      "kind": "story",
      "storyType": "body"
    }
  },
  "id": "id-001",
  "state": "open",
  "subtype": "example",
  "type": "insertion"
}

Pre-apply throws

TARGET_NOT_FOUND

Non-applied failure codes

None

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    },
    "story": {
      "$ref": "#/$defs/StoryLocator"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

Raw output schema

{
  "additionalProperties": false,
  "properties": {
    "address": {
      "$ref": "#/$defs/TrackedChangeAddress"
    },
    "addressKind": {
      "enum": [
        "entity",
        "story-entity",
        "unknown"
      ]
    },
    "after": {
      "additionalProperties": false,
      "properties": {
        "formatting": {
          "additionalProperties": false,
          "properties": {
            "properties": {
              "additionalProperties": true,
              "description": "Subtype-aware semantic property map for formatting revisions.",
              "type": "object"
            },
            "xml": {
              "description": "Raw OOXML for the property block on this side.",
              "type": "string"
            }
          },
          "type": "object"
        },
        "text": {
          "description": "Visible text snapshot when the affected revision is text-shaped.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "author": {
      "type": "string"
    },
    "authorEmail": {
      "type": "string"
    },
    "authorImage": {
      "type": "string"
    },
    "before": {
      "additionalProperties": false,
      "properties": {
        "formatting": {
          "additionalProperties": false,
          "properties": {
            "properties": {
              "additionalProperties": true,
              "description": "Subtype-aware semantic property map for formatting revisions.",
              "type": "object"
            },
            "xml": {
              "description": "Raw OOXML for the property block on this side.",
              "type": "string"
            }
          },
          "type": "object"
        },
        "text": {
          "description": "Visible text snapshot when the affected revision is text-shaped.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "canonicalizationKind": {
      "enum": [
        "single-word-revision",
        "paired-word-revision",
        "generated-runtime-id",
        "unknown"
      ]
    },
    "date": {
      "type": "string"
    },
    "deletedText": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "excerpt": {
      "type": "string"
    },
    "formattingDeltaSummary": {
      "description": "Human-readable formatting delta summary for formatting changes; null otherwise.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "grouping": {
      "enum": [
        "standalone",
        "replacement-pair",
        "unknown"
      ]
    },
    "id": {
      "type": "string"
    },
    "imported": {
      "type": "boolean"
    },
    "initials": {
      "type": "string"
    },
    "insertedText": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "origin": {
      "enum": [
        "word",
        "google-docs",
        "superdoc",
        "unknown"
      ]
    },
    "overlap": {
      "additionalProperties": false,
      "properties": {
        "parentId": {
          "description": "Parent logical tracked-change id when this change is an overlap child.",
          "type": "string"
        },
        "preferredContextTarget": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "description": "SuperDoc logical tracked-change id for this overlap layer.",
              "type": "string"
            },
            "relationship": {
              "enum": [
                "parent",
                "child",
                "standalone"
              ]
            },
            "type": {
              "description": "Canonical broad tracked-change type for this layer.",
              "enum": [
                "insertion",
                "deletion",
                "replacement",
                "formatting",
                "move",
                "structural",
                "insert",
                "delete",
                "format"
              ]
            }
          },
          "required": [
            "id",
            "type",
            "relationship"
          ],
          "type": "object"
        },
        "preferredContextTargetId": {
          "description": "Preferred child tracked-change id for context-menu/comment targeting.",
          "type": "string"
        },
        "relationship": {
          "enum": [
            "parent",
            "child",
            "standalone"
          ]
        },
        "visualLayers": {
          "description": "Ordered overlap layers, with the parent surface first and child layers after it.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "id": {
                "description": "SuperDoc logical tracked-change id for this overlap layer.",
                "type": "string"
              },
              "relationship": {
                "enum": [
                  "parent",
                  "child",
                  "standalone"
                ]
              },
              "type": {
                "description": "Canonical broad tracked-change type for this layer.",
                "enum": [
                  "insertion",
                  "deletion",
                  "replacement",
                  "formatting",
                  "move",
                  "structural",
                  "insert",
                  "delete",
                  "format"
                ]
              }
            },
            "required": [
              "id",
              "type",
              "relationship"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "pairedWithChangeId": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "replacement": {
      "additionalProperties": false,
      "properties": {
        "deleted": {
          "oneOf": [
            {
              "additionalProperties": false,
              "properties": {
                "excerpt": {
                  "description": "Visible text excerpt on this side.",
                  "type": "string"
                },
                "id": {
                  "description": "Stable SuperDoc-internal side id.",
                  "type": "string"
                },
                "wordId": {
                  "description": "Raw Word `w:id` for this side, when known.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "excerpt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "inserted": {
          "oneOf": [
            {
              "additionalProperties": false,
              "properties": {
                "excerpt": {
                  "description": "Visible text excerpt on this side.",
                  "type": "string"
                },
                "id": {
                  "description": "Stable SuperDoc-internal side id.",
                  "type": "string"
                },
                "wordId": {
                  "description": "Raw Word `w:id` for this side, when known.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "excerpt"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "inserted",
        "deleted"
      ],
      "type": "object"
    },
    "resolvableById": {
      "type": "boolean"
    },
    "revisionGroupId": {
      "type": "string"
    },
    "sourceIds": {
      "additionalProperties": false,
      "description": "Canonical multi-side source provenance. Provenance metadata only; never the canonical SuperDoc tracked-change id.",
      "properties": {
        "rsids": {
          "description": "Word revision-save ids (`w:rsidR` / `w:rsidDel`) seen on contributing wrappers.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "wordIdDelete": {
          "description": "Word `w:id` value from the deletion side of this logical change.",
          "type": "string"
        },
        "wordIdInsert": {
          "description": "Word `w:id` value from the insertion side of this logical change.",
          "type": "string"
        },
        "wordIdOther": {
          "description": "Word `w:id` values from other wrappers (for example moveFrom/moveTo).",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "sourcePlatform": {
      "enum": [
        "word",
        "google-docs",
        "superdoc",
        "unknown"
      ]
    },
    "splitFromId": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "state": {
      "enum": [
        "open",
        "accepted",
        "rejected"
      ]
    },
    "storyLocator": {
      "$ref": "#/$defs/StoryLocator"
    },
    "subtype": {
      "type": "string"
    },
    "target": {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "address": {
              "$ref": "#/$defs/TrackedChangeAddress"
            },
            "kind": {
              "enum": [
                "text"
              ]
            }
          },
          "required": [
            "kind",
            "address"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "address": {
              "$ref": "#/$defs/TrackedChangeAddress"
            },
            "kind": {
              "enum": [
                "replacement"
              ]
            }
          },
          "required": [
            "kind",
            "address"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "address": {
              "$ref": "#/$defs/TrackedChangeAddress"
            },
            "kind": {
              "enum": [
                "formatting"
              ]
            },
            "subtype": {
              "enum": [
                "run",
                "paragraph",
                "list",
                "table",
                "row",
                "cell",
                "section"
              ]
            }
          },
          "required": [
            "kind",
            "address",
            "subtype"
          ],
          "type": "object"
        }
      ]
    },
    "type": {
      "enum": [
        "insertion",
        "deletion",
        "replacement",
        "formatting",
        "move",
        "structural",
        "insert",
        "delete",
        "format"
      ]
    },
    "wordRevisionIds": {
      "additionalProperties": false,
      "description": "Raw imported Word OOXML revision IDs (`w:id`) from the source document when available. This is provenance metadata, not the canonical SuperDoc tracked-change ID. Replacements may include both `insert` and `delete` IDs.",
      "properties": {
        "delete": {
          "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:del>` element when this logical change includes a deletion.",
          "type": "string"
        },
        "format": {
          "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:rPrChange>` element when this logical change includes a formatting revision.",
          "type": "string"
        },
        "insert": {
          "description": "Raw imported Word OOXML revision ID (`w:id`) from a `<w:ins>` element when this logical change includes an insertion.",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "address",
    "id",
    "type"
  ],
  "type": "object"
}

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Summary

Expected result

Input fields

Example request

Output fields

Example response

Pre-apply throws

Non-applied failure codes

Raw schemas

​Summary

​Expected result

​Input fields

​Example request

​Output fields

​Example response

​Pre-apply throws

​Non-applied failure codes

​Raw schemas

Summary

Expected result

Input fields

Example request

Output fields

Example response

Pre-apply throws

Non-applied failure codes

Raw schemas