VEversionstory
documents

Create Version

Record a file as a new version of a document, following its latest version or the version named by parent, with a redline of what changed.

Send the file's bytes as multipart/form-data in the file field, or name a file you uploaded (or an edit's files.clean) by file_id, which the version takes as it is; parent, when given, as a form field holding its JSON. A JSON body names the file the same way: {"file_id", "parent"?, "author_name"?, "description"?}. Each upload is a new version; a file named by file_id becomes a version once, and naming it again is 409 CONFLICT. An edit's files.clean can be named while the edit is still being applied: the version's redline is made once the edit is.

post/v1/documents/{document_id}/versions

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/documents/{document_id}/versions
  • Auth
    HTTP bearer

Path parameters

document_idstring required

The Document's document_id, a UUID.

Headers

X-Customer-Idstring 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

file_idstring required

A file you uploaded (POST /v1/files) or an edit's files.clean: the version is that file as it is, not a copy, so the paragraph ids read from it carry over.

author_namestring nullable

Who the redline attributes this version's changes to. Defaults to the acting identity, which for an API key is its organization's service account.

descriptionstring nullable

What changed in this version, shown with it in the app and returned as description.

Response

Successful Response

document_idstring required

The Document the version belongs to.

version_idstring required

The version's id.

indexinteger 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.

labelstring 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.

namestring required

The version's name, which the app shows: its own once renamed, else its file's.

authorstring nullable

Who its changes are attributed to: an edit's author, an upload's author_name.

descriptionstring nullable

What changed: an edit's description, an upload's description.

created_atstring required

When the version was made: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z.

metadataobject

Your own string values by key, stored and returned as they were sent.

Changes

No recorded changes to this operation across all 1 revision of this API.