edit_document

Preferred way to change an existing document. Unfurl applies exact search/replace edits to the current HTML on the server and stores a new version. The share URL does not change. Use this instead of publish_document for small or targeted HTML changes. Maps to POST /api/v1/documents/:id/edit.

Workflow

Call get_document once with include_html: true (default version is current).
For each change, pick the smallest unique snippet of that HTML as old_string.
Call edit_document with those pairs. Edits apply in order. The batch is atomic — if one edit fails, nothing is saved.

Parameters

Parameter	Type	Required	Description
`document_id`	uuid	Yes	Document to edit
`edits`	array	Yes	1–100 search/replace objects, applied in order
`edits[].old_string`	string	Yes	Exact snippet of the current HTML. Must match verbatim, including whitespace. Must be unique unless `replace_all` is true.
`edits[].new_string`	string	Yes	Replacement. Use `""` to delete the snippet.
`edits[].replace_all`	boolean	No	Replace every occurrence instead of requiring a unique match
`note`	string	No	Version note (up to 2000 characters)

Matching is literal (no regex, no whitespace normalisation) against the raw stored HTML.

Returns

JSON including document_id, version_id, share_url, and a summary (edits_applied, replacements, bytes_before, bytes_after, sanitizer_warning).

Example

Tool call: edit_document
  document_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  note: "Fix pricing table total"
  edits:
    - old_string: "<td>$4,200</td>"
      new_string: "<td>$4,800</td>"

Errors

Situation	What happens
`old_string` not found	Request fails; no new version
`old_string` matches more than once (and `replace_all` is off)	Request fails as ambiguous
Edits produce no change	Request fails
Resulting HTML over 4 MB	Request fails

Do not use update_document for HTML changes — that tool only updates title and description.

MCP tools

REST

edit_document

edit_document

Workflow

Parameters

Returns

Example

Errors

Updating a document

REST POST /edit

​edit_document

​Workflow

​Parameters

​Returns

​Example

​Errors

Updating a document

REST POST /edit

edit_document

Workflow

Parameters

Returns

Example

Errors