--- title: "Create Edit" method: POST path: "/v1/edit" --- # Create Edit `POST /v1/edit` ## Request - Base URL: `https://api.versionstory.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.versionstory.com/v1/edit` - Auth: HTTP bearer Edit a file. The result has two files: files.comparison, the redline, holds the edits as Word tracked changes attributed to the user (or to author, when the user names someone else); files.clean, the edited document, carries none: every tracked change in it is accepted. Read the file's listing first (GET /v1/files/{file_id}?format=md) and copy every locator from it. Give a one-line description of what the edits change. To edit the result again, pass its files.clean.file_id as file_id: that file is the edited document. Never upload or name the original again for a further change, which would drop this edit. Your further edits for the same piece of work ("also change…") amend the version the first one made, the user's working draft, so one version holds all of their changes. Pass new_version: true when the user asks for a new version or a separate draft: "create a version", "up version", "save as", or a draft for someone else, such as a template filled in for a customer. Pass amend: true with an earlier version's file_id when the change belongs there too ("fix the template as well"); later versions get it too, even one whose redline is still being made. Pass version_name, the user's name for the file you save. Every edit has a type and that type's fields; unknown fields are refused. The request is all or nothing: if any edit is refused, none is applied and every refusal is reported together, each naming its edit by its index, so fix them all and send the corrected request. A request that accepts or rejects revisions holds only accept_revision and reject_revision edits. Every locator and selector names the file as listed, whatever earlier edits in the request did. Repeating a request repeats its effect: sending an insertion twice inserts twice. When the file is a version of one of your documents, the edit is kept as that document's next version: the result's version, and app_url opens its redline in the Version Story app. An edit of any other file is one-off; to keep its history, make a document of the file first (POST /v1/documents with its file_id). The call answers at once with status processing, the edit_id and both files' file_ids; GET /v1/edit/{edit_id} returns the files once the edit is applied. With wait: true, the call holds its answer as GET /v1/edit/{edit_id} does. ## Headers - `X-Customer-Id` string, nullable: Id of one of your customers (created in the developer dashboard) to attribute this request's credit usage to. Billing and limits stay organization-wide. ## Request body - EditRequest: POST /v1/edit with a JSON body (docs/public-api.md). A request that uploads style_template is multipart, with the same fields and edits as a JSON string. - `file_id` string, required: The file to edit: the file_id POST /v1/files returned, or a version's file_id. - `schema_version` integer, required: The listing's schema_version; a mismatch is refused. - `author` string, nullable: The name every tracked change and new comment carries, when the user wants one other than their own; at most 255 characters, one line. Omitted, it is the signed-in user's own name (Version Story AI for an API key, which acts as its organization's service account). - `date` string, nullable: ISO 8601 date and time on every tracked change; defaults to the time of the request. - `wait` boolean: Hold the response until the job finishes (up to 5 s). - `inline` boolean: With wait: return the files' bytes in the body. - `outputs` string[], nullable: With wait: the formats of both files, docx (the default), pdf, md, json or html. - `description` string, nullable: What the edits change, in one plain line, such as "Extend the termination notice to 60 days". It is kept with the version the edit becomes and shown in the Version Story app. - `new_version` boolean: True when the user asks for a new version or a separate draft: 'create a version', 'up version', 'save as', or a draft for someone else, such as a template filled in for a customer. Otherwise an edit of the draft your own edits made amends that version, so one version holds all of the user's changes for the same piece of work. - `amend` boolean: True to put the change in that version and every version after it. - `style_template_file_id` string, nullable: A Word file whose styles and numbering are imported before the first edit: the file_id of a .docx (or .doc) you uploaded, such as the template whose look the document should take. Styles of the same name are replaced by the template's, so paragraphs in them take its fonts, spacing and numbering; set_paragraph_style then gives other paragraphs its styles. Its text, page layout, headers and footers are not copied. - `style_template_styles` union: Which of the style template's styles to take: left out, only the paragraph styles the edits give paragraphs (set_paragraph_style, new paragraphs' style_id), each replacing the document's style of that name where the template defines it, so the rest of the document keeps its look; the document's default paragraph style (Normal) is never replaced unless named. A list of style ids takes exactly those, refusing one the template lacks. "all" takes every style and the template's default font and spacing, which restyles the whole document. Read the template's listing (paragraph_styles) to choose. - 'all' - string[] - `version_name` string, nullable: The version's name: the user's name for its file. - `edits` union[], required: The edits, applied in order, each with a type and that type's fields; unknown fields are refused. Every target is a locator copied from GET /v1/files/{file_id}?format=md, never a number you counted. The types: text (insert, replace, delete, format); paragraphs (insert_paragraphs, delete_paragraphs, move_paragraphs, split_paragraph, join_paragraphs, set_paragraph_style, set_paragraph_format, set_style_format, rename_style, set_numbering); sections and pages; tables; fields and links; notes; comments; tracked revisions (accept_revision, reject_revision); and document settings. Replace example: {"type": "replace", "paragraphs": {"id": ""}, "text": {"match": "Acme"}, "content": "Beta"}. For any other type, first call GET /v1/reference/{topic} with topic edits. - union - InsertEdit - `type` 'insert', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `at` union, required - 'start' | 'end' - AtAfter - `after` Selector, required: Text in the named paragraphs: match, with optional context and which occurrence. - … - AtBefore - `before` Selector, required: Text in the named paragraphs: match, with optional context and which occurrence. - … - `content` union, required: A string ("\t" a tab, "\n" a line break) or an array of runs in the listing's shapes. - string - union[] - union - … - ReplaceEdit - `type` 'replace', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `text` Selector, required: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - `content` union, required: A string ("\t" a tab, "\n" a line break) or an array of runs in the listing's shapes. - string - union[] - union - … - DeleteEdit - `type` 'delete', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `text` Selector, required: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - FormatEdit - `type` 'format', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `text` Selector: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - `format` CharacterFormat, required: Character formatting, the listing's format: a value sets a property, false turns it off, null removes the direct setting. - `bold` boolean, nullable - `italic` boolean, nullable - `small_caps` boolean, nullable - `all_caps` boolean, nullable - `superscript` boolean, nullable - `subscript` boolean, nullable - `underline` union: true is single. - boolean - 'single' | 'double' | 'thick' | 'dotted' | 'dash' | 'wave' | 'words' - `strike` union: true is single. - boolean - 'single' | 'double' - `highlight` union: true is refused. - false - 'black' | 'blue' | 'cyan' | 'green' | 'magenta' | 'red' | 'yellow' | 'white' | 'dark_blue' | 'dark_cyan' | 'dark_green' | 'dark_magenta' | 'dark_red' | 'dark_yellow' | 'dark_gray' | 'light_gray' - `color` string, nullable: Six hex digits. - `font_size` union: Points, in halves. - integer - number - `font` string, nullable - InsertParagraphsEdit - `type` 'insert_paragraphs', required - `destination` BlockDestination, required: Where new blocks go: before or after a paragraph, directly before or after a table, or, naming neither, at the start or end of the body ({"position": "end"}), which a document with no paragraph to name, such as the blank one POST /v1/create starts from, takes its first content at. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `position` 'before' | 'after' | 'start' | 'end', required: before or after the paragraph or table; with neither, start or end of the body. - `new_paragraphs` NewParagraph[], required - `content` union: As content; "" or none makes an empty paragraph. - string - union[] - … - `style_id` string, nullable - `paragraph_format` ParagraphFormat: Paragraph formatting, the listing's paragraph_format: a value sets, null removes the direct setting. - `alignment` 'left' | 'center' | 'right' | 'justify', nullable - `indent` Indent - … - `spacing` Spacing - … - `keep_with_next` boolean, nullable - `keep_lines_together` boolean, nullable - `page_break_before` boolean, nullable - `widow_control` boolean, nullable - `borders` ParagraphBorders - … - `list` union: null leaves it out of the operation's list (its style's numbering applies); false: no numbering. - NewList - … - SameList - … - false - `list_level` integer, nullable: A list level, 1 to 9. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `style_id` string, nullable - `paragraph_format` ParagraphFormat: Paragraph formatting, the listing's paragraph_format: a value sets, null removes the direct setting. - `alignment` 'left' | 'center' | 'right' | 'justify', nullable - `indent` Indent - `left` union - … - `right` union - … - `first_line` union - … - `hanging` union - … - `spacing` Spacing - `before` union - … - `after` union - … - `line_spacing` LineSpacing: One of {"multiple": lines}, {"exact": points}, {"at_least": points}. - … - `keep_with_next` boolean, nullable - `keep_lines_together` boolean, nullable - `page_break_before` boolean, nullable - `widow_control` boolean, nullable - `borders` ParagraphBorders - `top` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `left` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bottom` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `right` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `between` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bar` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `list` union - NewList - `new` 'bulleted' | 'numbered', required - SameList - `same_as` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `list_level` integer, nullable: A list level, 1 to 9. - DeleteParagraphsEdit - `type` 'delete_paragraphs', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - MoveParagraphsEdit - `type` 'move_paragraphs', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `destination` BlockDestination, required: Where new blocks go: before or after a paragraph, directly before or after a table, or, naming neither, at the start or end of the body ({"position": "end"}), which a document with no paragraph to name, such as the blank one POST /v1/create starts from, takes its first content at. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `position` 'before' | 'after' | 'start' | 'end', required: before or after the paragraph or table; with neither, start or end of the body. - `pending_changes` 'accept' | 'reject', nullable: Settles the tracked changes inside the moved paragraphs before moving them; without it, a move of paragraphs holding tracked changes is refused. - SplitParagraphEdit - `type` 'split_paragraph', required - `paragraphs` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - `kind` 'body' | 'footnote' | 'endnote' | 'header' | 'footer', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `type` 'default' | 'first' | 'even', nullable: A header's or footer's pages. - `section` SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `at` union, required - 'start' | 'end' - AtAfter - `after` Selector, required: Text in the named paragraphs: match, with optional context and which occurrence. - … - AtBefore - `before` Selector, required: Text in the named paragraphs: match, with optional context and which occurrence. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - JoinParagraphsEdit - `type` 'join_paragraphs', required - `paragraphs` ParagraphRange, required: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - SetParagraphStyleEdit - `type` 'set_paragraph_style', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `style_id` string, required - `clear` union - 'all' - string[] - SetParagraphFormatEdit - `type` 'set_paragraph_format', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `paragraph_format` ParagraphFormat, required: Paragraph formatting, the listing's paragraph_format: a value sets, null removes the direct setting. - `alignment` 'left' | 'center' | 'right' | 'justify', nullable - `indent` Indent - `left` union - … - `right` union - … - `first_line` union - … - `hanging` union - … - `spacing` Spacing - `before` union - … - `after` union - … - `line_spacing` LineSpacing: One of {"multiple": lines}, {"exact": points}, {"at_least": points}. - … - `keep_with_next` boolean, nullable - `keep_lines_together` boolean, nullable - `page_break_before` boolean, nullable - `widow_control` boolean, nullable - `borders` ParagraphBorders - `top` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `left` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bottom` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `right` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `between` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bar` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - SetStyleFormatEdit: Sets a paragraph style's own paragraph formatting, which every paragraph in the style takes. - `type` 'set_style_format', required - `style_id` string, required - `paragraph_format` ParagraphFormat, required: Paragraph formatting, the listing's paragraph_format: a value sets, null removes the direct setting. - `alignment` 'left' | 'center' | 'right' | 'justify', nullable - `indent` Indent - `left` union - … - `right` union - … - `first_line` union - … - `hanging` union - … - `spacing` Spacing - `before` union - … - `after` union - … - `line_spacing` LineSpacing: One of {"multiple": lines}, {"exact": points}, {"at_least": points}. - … - `keep_with_next` boolean, nullable - `keep_lines_together` boolean, nullable - `page_break_before` boolean, nullable - `widow_control` boolean, nullable - `borders` ParagraphBorders - `top` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `left` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bottom` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `right` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `between` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bar` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - RenameStyleEdit: Gives a style a new name, and an id made from it, and points everything in the style at the new id. - `type` 'rename_style', required - `style_id` string, required: The style to rename, by its style_id in the listing's paragraph styles. - `name` string, required: The style's new name, as Word shows it: one no other style, and none of Word's built-in styles, has, whatever its case. Its new style_id is the name's letters and digits ('DPA Heading 2' is DPAHeading2, numbered on when taken), which later edits in the request name it by. - SetNumberingEdit - `type` 'set_numbering', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `action` 'apply' | 'remove' | 'set_level' | 'restart' | 'continue' | 'set_number_format', required - `list` union - NewList - `new` 'bulleted' | 'numbered', required - SameList - `same_as` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `list_level` integer, nullable: A list level, 1 to 9. - `start` integer, nullable - `number_format` 'decimal' | 'decimal_zero' | 'lower_roman' | 'upper_roman' | 'lower_letter' | 'upper_letter' | 'ordinal' | 'cardinal_text' | 'ordinal_text' | 'bullet' | 'none', nullable - `pattern` string, nullable - InsertSectionBreakEdit - `type` 'insert_section_break', required - `paragraphs` union, required: A paragraph locator, {"from": locator, "through": locator}, an array of those, "all", or {"all": true, "part": {...}}. - 'all' - AllParagraphs: Every paragraph of the matching parts; a part with only kind matches every part of that kind. - `all` true, required - `part` PartLocator, required: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - union[] - union - … - `section_type` 'next_page' | 'continuous' | 'even_page' | 'odd_page', required - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - RemoveSectionBreakEdit - `type` 'remove_section_break', required - `section` SectionLocator, required: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `keep` 'earlier' | 'later': Whose headers, footers and page setup the merged section keeps: earlier (the default), the section whose break is removed; later, the section after it, as Word does. - SetPageSetupEdit - `type` 'set_page_setup', required - `section` union, required - 'all' - SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - SectionLocator[] - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `page_setup` PageSetup, required: A section's page setup in points, the listing's page_setup. - `orientation` 'portrait' | 'landscape', nullable - `paper` 'letter' | 'legal' | 'a4', nullable - `page_width` union - integer - number - `page_height` union - integer - number - `margins` Margins - `top` union - … - `bottom` union - … - `left` union - … - `right` union - … - `header` union - … - `footer` union - … - `gutter` union - … - `different_first_page` boolean, nullable - `page_numbering` PageNumbering - `start` integer, nullable - `number_format` 'decimal' | 'lower_roman' | 'upper_roman' | 'lower_letter' | 'upper_letter', nullable - `columns` SectionColumns: How many columns of equal width a section's text runs in, and the space between them, the listing's page_setup.columns. - `count` integer, required: 1 sets the text in one column. - `spacing` union: Points between the columns; Word's 36 when the section sets none. - … - AddHeaderFooterEdit - `type` 'add_header_footer', required - `part` HeaderFooterPart, required - `kind` 'header' | 'footer', required - `type` 'default' | 'first' | 'even', required - `section` SectionLocator, required: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `content` union - string - union[] - union - … - `new_paragraphs` BlockParagraph[], nullable - `content` union: As content; "" or none makes an empty paragraph. - string - union[] - … - `style_id` string, nullable - `paragraph_format` ParagraphFormat: Paragraph formatting, the listing's paragraph_format: a value sets, null removes the direct setting. - `alignment` 'left' | 'center' | 'right' | 'justify', nullable - `indent` Indent - … - `spacing` Spacing - … - `keep_with_next` boolean, nullable - `keep_lines_together` boolean, nullable - `page_break_before` boolean, nullable - `widow_control` boolean, nullable - `borders` ParagraphBorders - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - InsertTableEdit - `type` 'insert_table', required - `destination` BlockDestination, required: Where new blocks go: before or after a paragraph, directly before or after a table, or, naming neither, at the start or end of the body ({"position": "end"}), which a document with no paragraph to name, such as the blank one POST /v1/create starts from, takes its first content at. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `position` 'before' | 'after' | 'start' | 'end', required: before or after the paragraph or table; with neither, start or end of the body. - `rows` array[], required - union[] - union - … - `header_row` boolean - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - InsertTableRowEdit - `type` 'insert_table_row', required - `destination` RowDestination, required - `row` RowLocator, required: A table row: {"table": {...}, "index": n} among its table's rows, {"id": "..."}, both index and id, {"paragraph": {...}} for the row holding that paragraph in the innermost table holding it, or {"ref": name}. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `position` 'before' | 'after', required - `cells` union[], required - union - '' - string - union[] - … - CellParagraphs: A table cell of several paragraphs, each as an insert_paragraphs item. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - InsertTableColumnEdit - `type` 'insert_table_column', required - `destination` ColumnDestination, required - `column` ColumnLocator, required: A table column: {"table": {...}, "index": n} counting the table's grid columns from 0 (a listed cell's column), {"paragraph": {...}} for the column of the cell holding that paragraph in the innermost table holding it, or {"ref": name}. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `position` 'before' | 'after', required - `cells` union[], required - union - '' - string - union[] - … - CellParagraphs: A table cell of several paragraphs, each as an insert_paragraphs item. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - DeleteTableEdit - `type` 'delete_table', required - `table` TableLocator, required: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - `kind` 'body' | 'footnote' | 'endnote' | 'header' | 'footer', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `type` 'default' | 'first' | 'even', nullable: A header's or footer's pages. - `section` SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - DeleteTableRowEdit - `type` 'delete_table_row', required - `row` RowLocator, required: A table row: {"table": {...}, "index": n} among its table's rows, {"id": "..."}, both index and id, {"paragraph": {...}} for the row holding that paragraph in the innermost table holding it, or {"ref": name}. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - DeleteTableColumnEdit - `type` 'delete_table_column', required - `column` ColumnLocator, required: A table column: {"table": {...}, "index": n} counting the table's grid columns from 0 (a listed cell's column), {"paragraph": {...}} for the column of the cell holding that paragraph in the innermost table holding it, or {"ref": name}. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - SetTableFormatEdit - `type` 'set_table_format', required - `table` TableLocator, required: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - `kind` 'body' | 'footnote' | 'endnote' | 'header' | 'footer', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `type` 'default' | 'first' | 'even', nullable: A header's or footer's pages. - `section` SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `table_format` TableFormat, required: A table's formatting, the listing's table_format: a value sets, null removes the direct setting. - `borders` TableBorders - `top` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `left` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bottom` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `right` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `inside_horizontal` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `inside_vertical` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - SetCellFormatEdit - `type` 'set_cell_format', required - `cells` union, required: One cell locator, or {"from": cell locator, "through": cell locator}. - CellRange: The cells from one corner through the other, in one table: every cell whose row, and the grid column it starts at, lie between from's and through's. - `from` CellLocator, required: A table cell: {"row": row locator, "index": n} among its row's cells, {"id": "..."}, both index and id, or {"paragraph": {...}} for the cell holding that paragraph in the innermost table holding it. - … - `through` CellLocator, required: A table cell: {"row": row locator, "index": n} among its row's cells, {"id": "..."}, both index and id, or {"paragraph": {...}} for the cell holding that paragraph in the innermost table holding it. - … - CellLocator: A table cell: {"row": row locator, "index": n} among its row's cells, {"id": "..."}, both index and id, or {"paragraph": {...}} for the cell holding that paragraph in the innermost table holding it. - `row` RowLocator: A table row: {"table": {...}, "index": n} among its table's rows, {"id": "..."}, both index and id, {"paragraph": {...}} for the row holding that paragraph in the innermost table holding it, or {"ref": name}. - … - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `cell_format` CellFormat, required: A cell's formatting, the listing's cell_format: a value sets, null removes the direct setting. - `borders` CellBorders - `top` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `left` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `bottom` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `right` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `inside_horizontal` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `inside_vertical` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `diagonal_down` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - `diagonal_up` Border: One border, the listing's border: a line style with its width, colour and spacing. Style none is an explicit absence, which keeps a border the style or a neighbouring cell would draw from being drawn. - … - InsertTableOfContentsEdit - `type` 'insert_table_of_contents', required - `destination` BlockDestination, required: Where new blocks go: before or after a paragraph, directly before or after a table, or, naming neither, at the start or end of the body ({"position": "end"}), which a document with no paragraph to name, such as the blank one POST /v1/create starts from, takes its first content at. - `paragraph` ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `table` TableLocator: A table: {"index": n} among its part's tables (body unless part is given), {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `position` 'before' | 'after' | 'start' | 'end', required: before or after the paragraph or table; with neither, start or end of the body. - `from_level` integer, required - `to_level` integer, required - `hyperlinks` boolean - `page_numbers` boolean - RefreshFieldsEdit - `type` 'refresh_fields', required - AddHyperlinkEdit - `url` string, required - `type` 'add_hyperlink', required - `paragraphs` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - `kind` 'body' | 'footnote' | 'endnote' | 'header' | 'footer', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `type` 'default' | 'first' | 'even', nullable: A header's or footer's pages. - `section` SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `text` Selector: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - SetHyperlinkEdit - `url` string, required - `type` 'set_hyperlink', required - `paragraphs` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - `kind` 'body' | 'footnote' | 'endnote' | 'header' | 'footer', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `type` 'default' | 'first' | 'even', nullable: A header's or footer's pages. - `section` SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `text` Selector: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - RemoveHyperlinkEdit - `type` 'remove_hyperlink', required - `paragraphs` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - `kind` 'body' | 'footnote' | 'endnote' | 'header' | 'footer', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `type` 'default' | 'first' | 'even', nullable: A header's or footer's pages. - `section` SectionLocator: A section: {"index": n} counted from 0 in document order, or {"ref": name} for a section this request creates. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `text` Selector: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - DeleteNoteEdit - `type` 'delete_note', required - `note` NoteLocator, required: A footnote or endnote: {"kind": ..., "index": n} among the notes of its kind, or {"ref": name}. - `kind` 'footnote' | 'endnote', nullable - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - AddCommentEdit - `type` 'add_comment', required - `paragraphs` union - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `text` Selector: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - `revision` RevisionLocator: One entry of the listing's revisions, by its index. - `index` integer, required: Where a thing is now: its position within its container, counted from 0. - `content` union, required: A string, or text, tab and line-break runs; a comment holds no other run. - string - union[] - union - … - `author` string, nullable - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - AddBookmarkEdit - `type` 'add_bookmark', required - `paragraphs` union, required: The paragraphs the bookmark spans, from the start of the first to the end of the last; with text, the one paragraph holding it. - ParagraphRange: The paragraphs from one locator through another, inclusive. - `from` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - `through` ParagraphLocator, required: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - … - ParagraphLocator: A paragraph: {"index": n} in the body or {"part": {...}, "index": n} elsewhere, {"id": "..."} in any part, both index and id, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `id` string, nullable: What a thing is, as the listing prints it: kept when content moves. - `part` PartLocator: A part of the document: body; a footnote or endnote by index; a header or footer by type and section; or a header, footer or note this request creates, by ref. - … - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `text` Selector: Text in the named paragraphs: match, with optional context and which occurrence. - `match` union, required: Text or runs. - string - union[] - … - `prefix` string, nullable - `suffix` string, nullable - `occurrence` union: Omitted: the match must be unique; N: the Nth; all: every match. - integer: Counted from 1. - 'all' - `name` string, required: The bookmark's name, which fields and cross-references name it by (an INCLUDETEXT field in another document, say): a letter, then letters, digits and underscores, 40 at most, and not a name the document already uses, whatever its case. - ReplyCommentEdit - `type` 'reply_comment', required - `comment` CommentLocator, required: A comment thread: {"index": n} counted from 0 among top-level threads, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - `content` union, required: A string, or text, tab and line-break runs; a comment holds no other run. - string - union[] - union - … - `author` string, nullable - ResolveCommentEdit - `type` 'resolve_comment', required - `comment` CommentLocator, required: A comment thread: {"index": n} counted from 0 among top-level threads, or {"ref": name}. - `index` integer, nullable: Where a thing is now: its position within its container, counted from 0. - `ref` string, nullable: A name for something this request creates; letters, digits, _ . : and -. - AcceptRevisionEdit - `revision` union, required - 'all' - RevisionLocator: One entry of the listing's revisions, by its index. - `index` integer, required: Where a thing is now: its position within its container, counted from 0. - RevisionFilter: Every revision by this author and/or of this type. - `author` string, nullable - `type` 'insertion' | 'deletion' | 'move' | 'property', nullable - `skip_if_none` boolean, nullable: With a filter (author and/or kind), true makes a filter that selects no revision decide nothing instead of refusing the request, as when accepting every insertion of a document that may have none. - `type` 'accept_revision', required - RejectRevisionEdit - `revision` union, required - 'all' - RevisionLocator: One entry of the listing's revisions, by its index. - `index` integer, required: Where a thing is now: its position within its container, counted from 0. - RevisionFilter: Every revision by this author and/or of this type. - `author` string, nullable - `type` 'insertion' | 'deletion' | 'move' | 'property', nullable - `skip_if_none` boolean, nullable: With a filter (author and/or kind), true makes a filter that selects no revision decide nothing instead of refusing the request, as when accepting every insertion of a document that may have none. - `type` 'reject_revision', required - SetDocumentSettingsEdit - `type` 'set_document_settings', required - `settings` DocumentSettingsOperation, required: Settings of the output document, applied directly: Word cannot track them. Unset fields are left as they are. - `track_changes` boolean, nullable: true turns on Track Changes in the output (w:trackRevisions); false turns it off. - `protection` union: Restrict editing of the output (w:documentProtection, enforced), replacing any protection it has; false removes protection. - false - DocumentProtectionSetting: Word's Restrict Editing, enforced: which changes the output allows, and optionally a password to lift it. The password is hashed as Word hashes it (word_protection_hash) when the edit is first serialized, after the request's checks; the operation serializes the hash as password_hash, so the password itself is never stored with the edit nor sent to the apply worker. - … - `remove_personal_information` boolean, nullable: true sets Word's remove-personal-information-on-save (w:removePersonalInformation) and clears the creator and last-modified-by names from the file properties; false turns the setting off. ## Response `202` Successful Response - union - EditAcceptedResponse - `edit_id` string, required: The edit's id (edt_...), which GET /v1/edit/{edit_id} takes. - `status` 'processing', required - `files` Files, required: A document's files, as an edit and a version carry them: its clean document and its redline. - `clean` FileResource, required: A file: GET /v1/files/{file_id} answers with it, and every response that carries a document embeds it. It never carries version fields: a version holds its file. - `file_id` string, required - `file_name` string, required - `status` 'processing' | 'ready' | 'failed', required: The state of the formats this request asked for: processing while one is still being produced (poll again after Retry-After), ready when every one is in downloads, failed when the document cannot be used (error) or a requested format will never be produced. - `downloads` FormatDownload[], nullable: One per requested format that is ready. - `format` string, required - `url` string, required: Signed; it expires at expires_at. - `file_name` string, required - `expires_at` string, required: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z. - `metadata_report` MetadataReport: What a clean found in one download and did to each kind of hidden data. - `format` string, required: docx, xlsx, pptx, pdf or zip. - `preset` string, required: standard or strict. - `items` MetadataReportItem[], required - … - `warnings` MetadataReportWarning[], required - … - `files` integer, nullable: For a zip, how many documents inside it were cleaned. - `content_base64` string, nullable: Only in an edit's or a creation's files, with inline=true: the file's bytes, base64-encoded. - `pending_formats` string[], nullable: Requested formats still being produced. - `failed_formats` string[], nullable: Requested formats that will never be produced. - `error` ComparisonErrorDescriptor - `code` string, required - `upstream_code` string, nullable - `comparison` FileResource: A file: GET /v1/files/{file_id} answers with it, and every response that carries a document embeds it. It never carries version fields: a version holds its file. - `file_id` string, required - `file_name` string, required - `status` 'processing' | 'ready' | 'failed', required: The state of the formats this request asked for: processing while one is still being produced (poll again after Retry-After), ready when every one is in downloads, failed when the document cannot be used (error) or a requested format will never be produced. - `downloads` FormatDownload[], nullable: One per requested format that is ready. - `format` string, required - `url` string, required: Signed; it expires at expires_at. - `file_name` string, required - `expires_at` string, required: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z. - `metadata_report` MetadataReport: What a clean found in one download and did to each kind of hidden data. - `format` string, required: docx, xlsx, pptx, pdf or zip. - `preset` string, required: standard or strict. - `items` MetadataReportItem[], required - … - `warnings` MetadataReportWarning[], required - … - `files` integer, nullable: For a zip, how many documents inside it were cleaned. - `content_base64` string, nullable: Only in an edit's or a creation's files, with inline=true: the file's bytes, base64-encoded. - `pending_formats` string[], nullable: Requested formats still being produced. - `failed_formats` string[], nullable: Requested formats that will never be produced. - `error` ComparisonErrorDescriptor - `code` string, required - `upstream_code` string, nullable - `version` VersionReference: A version a response points at: a parent, a Document's latest version, an edit's version. Sent back as it is, it names the version in a request (VersionLocator reads its version_id). - `document_id` string, required: The Document the version belongs to. - `version_id` string, required: The version's id. - `index` integer, required: The version's position among its Document's versions in the order they were made, counted from 0: the first version, v1, is index 0. It shows the order and names nothing: deleting a version moves the ones after it down, so a request names a version by its version_id. - `label` string, required: The app's label for the version, such as v2, or v2(a) for one of competing drafts, which the user names it by. It comes from the version graph, so a sibling added later can relabel it. - `app_url` string, nullable: Opens the version the edit is kept as at its redline in the Version Story app. Present only with version. - `message` string, nullable - EditStatusResponse - `edit_id` string, required - `status` 'processing' | 'ready' | 'failed', required: The edit's status; each file's status is that file's. - `files` Files, required: A document's files, as an edit and a version carry them: its clean document and its redline. - `clean` FileResource, required: A file: GET /v1/files/{file_id} answers with it, and every response that carries a document embeds it. It never carries version fields: a version holds its file. - `file_id` string, required - `file_name` string, required - `status` 'processing' | 'ready' | 'failed', required: The state of the formats this request asked for: processing while one is still being produced (poll again after Retry-After), ready when every one is in downloads, failed when the document cannot be used (error) or a requested format will never be produced. - `downloads` FormatDownload[], nullable: One per requested format that is ready. - `format` string, required - `url` string, required: Signed; it expires at expires_at. - `file_name` string, required - `expires_at` string, required: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z. - `metadata_report` MetadataReport: What a clean found in one download and did to each kind of hidden data. - `format` string, required: docx, xlsx, pptx, pdf or zip. - `preset` string, required: standard or strict. - `items` MetadataReportItem[], required - … - `warnings` MetadataReportWarning[], required - … - `files` integer, nullable: For a zip, how many documents inside it were cleaned. - `content_base64` string, nullable: Only in an edit's or a creation's files, with inline=true: the file's bytes, base64-encoded. - `pending_formats` string[], nullable: Requested formats still being produced. - `failed_formats` string[], nullable: Requested formats that will never be produced. - `error` ComparisonErrorDescriptor - `code` string, required - `upstream_code` string, nullable - `comparison` FileResource: A file: GET /v1/files/{file_id} answers with it, and every response that carries a document embeds it. It never carries version fields: a version holds its file. - `file_id` string, required - `file_name` string, required - `status` 'processing' | 'ready' | 'failed', required: The state of the formats this request asked for: processing while one is still being produced (poll again after Retry-After), ready when every one is in downloads, failed when the document cannot be used (error) or a requested format will never be produced. - `downloads` FormatDownload[], nullable: One per requested format that is ready. - `format` string, required - `url` string, required: Signed; it expires at expires_at. - `file_name` string, required - `expires_at` string, required: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z. - `metadata_report` MetadataReport: What a clean found in one download and did to each kind of hidden data. - `format` string, required: docx, xlsx, pptx, pdf or zip. - `preset` string, required: standard or strict. - `items` MetadataReportItem[], required - … - `warnings` MetadataReportWarning[], required - … - `files` integer, nullable: For a zip, how many documents inside it were cleaned. - `content_base64` string, nullable: Only in an edit's or a creation's files, with inline=true: the file's bytes, base64-encoded. - `pending_formats` string[], nullable: Requested formats still being produced. - `failed_formats` string[], nullable: Requested formats that will never be produced. - `error` ComparisonErrorDescriptor - `code` string, required - `upstream_code` string, nullable - `version` VersionReference: A version a response points at: a parent, a Document's latest version, an edit's version. Sent back as it is, it names the version in a request (VersionLocator reads its version_id). - `document_id` string, required: The Document the version belongs to. - `version_id` string, required: The version's id. - `index` integer, required: The version's position among its Document's versions in the order they were made, counted from 0: the first version, v1, is index 0. It shows the order and names nothing: deleting a version moves the ones after it down, so a request names a version by its version_id. - `label` string, required: The app's label for the version, such as v2, or v2(a) for one of competing drafts, which the user names it by. It comes from the version graph, so a sibling added later can relabel it. - `app_url` string, nullable: Opens the version the edit is kept as at its redline in the Version Story app. Present only with version. - `carried_versions` VersionReference[], nullable: For an amend: every version after the amended one, which took the change too. - `document_id` string, required: The Document the version belongs to. - `version_id` string, required: The version's id. - `index` integer, required: The version's position among its Document's versions in the order they were made, counted from 0: the first version, v1, is index 0. It shows the order and names nothing: deleting a version moves the ones after it down, so a request names a version by its version_id. - `label` string, required: The app's label for the version, such as v2, or v2(a) for one of competing drafts, which the user names it by. It comes from the version graph, so a sibling added later can relabel it. - `error` EditErrorDescriptor - `code` string, required - `upstream_code` string, nullable - `message` string, nullable - `message` string, nullable ## Other responses - `400`: The request is invalid: INVALID_REQUEST when a parameter or the body fails validation, otherwise the code of the operation's own refusal. --- [API](https://skmtc.dev/versionstory/apis/version-story-public-api.md) - [All operations](https://skmtc.dev/versionstory/apis/version-story-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/versionstory/apis/version-story-public-api/revisions/994ce15faf32?raw)