Applies one or more edit operations, in order, to an existing ODocs.co document; people who have it open see each edit in real time. Returns { id, version, ok }, plus a warning when the author name was changed. Two kinds of operation: text-anchored (insert-after / insert-before / replace-text / delete-text), where the server finds the given exact text and resolves it to a position, so no character offsets are needed; and position-based (insert / delete / replace) at an exact character offset. expectedVersion enables conflict detection: if the document changed since that version, the patch is refused with 409 and nothing is applied. Operations are not atomic: they apply one at a time to the live document and are not rolled back. When one fails, the operations before it stay applied (and visible), and the 400 body reports appliedOps: N, the number applied; sending the whole batch again applies those a second time. On an anchor failure the body can also carry nearestMatchOffset and nearestMatchSnippet; they appear only when the anchor matches the document except for whitespace (usually a different newline count), so their absence means the text is not in the document. Anchor matching is exact. LINE BREAKS: each "\n" is a paragraph break, except inside a code block (an insert strictly inside one, or a replace within one, stays in it; at its very start / end a "\n" is a paragraph break). A delete or replace across one JOINS the paragraphs (the first keeps its formatting, except that a range starting at a line start keeps the later line's paragraph); a replace with as many lines as it spans rewrites each line in place, and deleting a whole line with its "\n" joins nothing; identical whole lines at the start / end of find and replace are left out ("2\naf" → "2\nA\nB\naf" only inserts "A\nB\n"). After a join the document can differ from what a position computed before it assumed: list items after a plain paragraph can't join it (one "\n" stays), and a code block's lines joined into a paragraph become hard breaks the plain text doesn't show. While someone has the document open, a patch that would join paragraphs is refused as a whole (409 join_blocked_live_editors, nothing applied); edits within a line and rewrites of whole lines are not affected.
View input schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Document ID"
},
"operations": {
"minItems": 1,
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "insert"
},
"position": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"type",
"position",
"text"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "delete"
},
"position": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"length": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"position",
"length"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "replace"
},
"position": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"length": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"type",
"position",
"length",
"text"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "insert-after"
},
"anchor": {
"type": "string",
"minLength": 1,
"description": "Exact text to anchor against. The new text is inserted immediately after this match."
},
"text": {
"type": "string",
"description": "Text to insert."
},
"occurrence": {
"description": "0-based index of the match to use; required when the anchor matches more than once.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"anchor",
"text"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "insert-before"
},
"anchor": {
"type": "string",
"minLength": 1,
"description": "Exact text to anchor against. The new text is inserted immediately before this match."
},
"text": {
"type": "string",
"description": "Text to insert."
},
"occurrence": {
"description": "0-based index of the match to use; required when the anchor matches more than once.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"anchor",
"text"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "replace-text"
},
"find": {
"type": "string",
"minLength": 1,
"description": "Exact text to find and replace."
},
"replace": {
"type": "string",
"description": "Replacement text."
},
"occurrence": {
"description": "0-based index of the match to use; required when find matches more than once.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"find",
"replace"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "delete-text"
},
"find": {
"type": "string",
"minLength": 1,
"description": "Exact text to find and delete."
},
"occurrence": {
"description": "0-based index of the match to use; required when find matches more than once.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"find"
]
}
]
},
"description": "Operations, applied in order. Text-anchored ops (insert-after / insert-before / replace-text / delete-text) name exact text that the server resolves to a position; position-based ops (insert / delete / replace) take character offsets."
},
"author": {
"description": "Name shown on your edits and comments (e.g. \"Claude via Greg\"), with a robot mark as an agent. Invisible and text-direction characters are removed, line breaks and control characters become spaces, and it is cut to 256 characters. A name that resembles ODocs.co or Octaria (including look-alike spellings) is shown as \"Agent (Anonymous)\". When any of that happens the result has a `warning` field saying what changed.",
"type": "string"
},
"expectedVersion": {
"description": "The document version from your last read. If the document has changed since, the patch is refused with 409 and nothing is applied (conflict detection).",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"id",
"operations"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}