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.