Version history — blame, in the engineering sense — answers "who changed what, and when" across a document's whole life. Given an ordered chain of versions, it produces one Word document based on the newest version in which every surviving change is a tracked change attributed to the version that introduced it.
Use it when someone wants to know which draft introduced a clause, or whose edit actually survived to the final document.
create_version_history
| Parameter | Type | Default | Meaning |
|---|---|---|---|
version_file_paths | string[] | — | Paths to the versions — at least two, ordered oldest first |
version_file_names | string[] | — | Display names, in the same order |
version_authors | string[] | — | Author label per version, in the same order. Defaults to each version's file name |
version_story_name | string | — | Name for a new project |
version_story_id | string | — | Add to an existing project |
Order is the whole point. Versions are passed oldest first, and each is compared to the one before it, so the ordering determines the attribution. Getting it wrong doesn't error — it silently produces a wrong answer.
Constraints: at least two versions, all list lengths matching, file names unique within the chain.
Response
{
"status": "awaiting_uploads",
"version_story_id": "uuid",
"version_story_name": "Acme SOW",
"version_story_url": "https://app.versionstory.com/version-story/<id>",
"upload_manifest_url": "https://... (signed, 1 hour)",
"uploads": [{ "file_name": "sow_v1.docx", "upload_url": "...", "authorization": "..." }],
"staged_file_names": ["sow_v1.docx", "sow_v2.docx", "sow_v3.docx"],
"version_history": {
"version_history_version_id": "uuid",
"version_history_file_name": "Version history sow_v3.docx"
}
}Transfer each source with a PUT as described in
Transferring files. Generation begins once
the uploads land and the version-to-version comparisons finish.
get_version_history_document
| Parameter | Type | Required | Meaning |
|---|---|---|---|
version_story_id | string | Yes | The project holding the chain |
version_history_version_id | string | Yes | From the create response's version_history.version_history_version_id |
Generation produces a comparison between each consecutive pair of versions and then layers
them oldest to newest, so processing may come back several times — several minutes is
normal for a long chain. Call again with identical arguments to keep waiting.
Response — ready
{
"status": "ready",
"version_story_id": "uuid",
"downloads": [
{ "option": "version_history_docx", "file_name": "Version history sow_v3.docx" }
],
"text_url": "https://... (signed, 1 hour)",
"text_file_name": "Version history sow_v3.md",
"download_manifest_url": "https://... (signed, 1 hour)"
}version_history_docx is the only output format. Fetch download_manifest_url for the
download URL and save it as binary.
text_url gives you the same attribution as markdown, where each change carries the
author and revision it came from — see
Reading the changes. That is usually the
better input when an agent needs to answer questions about the history rather than hand a
file to a person.
A failed status is terminal and lists causes in errors. awaiting_uploads lists the
untransferred sources in missing_uploads.