Version Story

Report the current connector access-token lifetime and refresh capability.

check_connection

Combine two or more documents that share no common original into a single Word document. Use this when several documents are independent drafts with no shared original — different people each drafting from scratch, or otherwise unrelated versions — and the user wants one combined draft. Prefer create_merge instead whenever the documents are edits of one original: merge diffs each revision against that shared base, which produces a cleaner result. Combine has no base; it constructs a shared base by folding the documents into each other, then carries each document's content into the result as tracked changes labeled by the document it came from, so each change can be accepted or rejected in Word. The result does not depend on the order of the documents. document_authors labels each document's tracked changes with its author, in the same order as the documents (the account's default author label when omitted). Excel files are not supported. The response contains upload_manifest_url describing the file transfers — each an HTTP PUT of the raw file bytes that the calling agent performs itself with any HTTP client (curl, for example) — plus combine.combine_version_id identifying the combined document, and combine.combined_document_url, a link the user can open to view the combined result interactively. Combine generation begins once the uploads land.

create_combine

Compare, diff, or redline local or attached documents into true Word tracked-changes, PDF, or PDF changed-pages-only redlines. Use this when the source documents (DOCX, DOC, PDF, or XLSX) exist as local files — for example attached to the conversation — rather than at https URLs. The comparison engine produces the exact set of changes between each base document and its revisions as a true redline. A single call stages everything, one base document or several. Pass version_story_id to add the comparisons to an existing project instead of creating a new one. Files attached in ChatGPT go in base_file and comparison_files rather than the path fields: Version Story fetches them itself and the response has status uploaded, with no transfers to perform. For files passed by absolute path, the response usually contains command: one shell command that uploads the documents, waits for the redlines, and saves them to output_files — run it as given and present the saved files; no get_redlines call is needed. Otherwise it contains upload_manifest_url describing the file transfers — each an HTTP PUT of the raw file bytes that the calling agent performs itself with any HTTP client (curl, for example). It also contains comparisons[] with a version_mapping_id and a redline_url per comparison document — a link the user can open to view the tracked changes interactively. Redline generation starts automatically as the uploads land.

create_comparison

Compare, diff, or redline documents at https URLs into true Word tracked-changes, PDF, or PDF changed-pages-only redlines. Use this when the source documents (DOCX, DOC, PDF, or XLSX) are reachable at https URLs rather than only as local files: files shared in Slack or publicly fetchable links (presigned storage links, public share links). Private Slack file URLs (files.slack.com) require slack_team_id — the id of the Slack workspace the files belong to (starts with T) — and are fetched with the Slack workspace connection of the caller's Version Story organization; the Version Story Slack app must be installed in that workspace and invited to the channel the files were shared in. Pass the URL of the base (original) document and the URL(s) of one or more comparison (revised) documents — comparison_file_urls compares several revisions against the same base in one call (one redline per revision). Pass version_story_id to add the comparisons to an existing project instead of creating a new one; repeated calls with the same version_story_id build up a project with many comparison groups. Everything runs server-side: the documents are fetched, staged, and compared by Version Story's deterministic comparison engine, which preserves footnotes, tables, numbering, and formatting. Returns a comparisons list with a version_mapping_id and a redline_url per comparison — a link the user can open to view the tracked changes interactively — plus the project URL. Downloadable redline files are retrieved separately using the returned version_mapping_id values.

create_comparison_from_links

Merge two or more revised versions of one base document into a single Word document. Use this when several people have separately edited the same original document and the user wants one combined draft. The result carries each revision's edits as tracked changes, labeled by the version they came from, so each edit can be accepted or rejected in Word. Merging is built on comparisons: each revised version is diffed against the same base document, so all revisions share one base. The result does not depend on the order of the revisions: where revisions conflict, every edit appears as a tracked change attributed to its revision. next_version_authors labels each revision's tracked changes with its author, in the same order as the revisions (the account's default author label when omitted). Excel files are not supported. The response contains upload_manifest_url describing the file transfers — each an HTTP PUT of the raw file bytes that the calling agent performs itself with any HTTP client (curl, for example) — plus merge.merge_version_id identifying the merged document, and merge.merged_document_url, a link the user can open to view the merged result interactively. Merge generation begins once the uploads land and the underlying comparisons finish.

create_merge

Build a version history document across an ordered chain of document versions: 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 this when the user wants to know who changed what across a document's history — which draft introduced a clause, whose edit survived. The versions are passed oldest first; each version is compared to the one before it, so the order determines the attribution. version_authors labels each version's changes with its author (each version's file name when omitted). Excel files are not supported. The response contains upload_manifest_url describing the file transfers — each an HTTP PUT of the raw file bytes that the calling agent performs itself with any HTTP client (curl, for example) — plus version_history.version_history_version_id identifying the chain's newest version. Generation begins once the uploads land and the version-to-version comparisons finish.

create_version_history

Wait server-side for a combined document to generate and return its download link. Returns the combined document identified by version_story_id and combine_version_id. Combining first constructs a shared base from the documents and then folds them together, so the call may return status processing several times — calling again with the same arguments keeps waiting, and several minutes is normal. A status of awaiting_uploads lists source files that were never transferred in missing_uploads. A status of failed is terminal: the errors field lists the causes, and waiting again does not regenerate the combine. When ready, the downloads[] entry carries the combined Word document's download_url, a link that serves the file directly: save the file from it, or give it to the user when the client cannot download files itself. download_manifest_url lists the same file. Ready responses may also carry text_url and text_file_name, a signed URL to a plain-text rendering of the combined document's tracked changes. The links expire after one hour.

get_combined_document

Wait server-side for a merged document to generate and return its download links. Returns the merged document identified by version_story_id and merge_version_id. Merging first generates a comparison of each revised version against the base and then folds those redlines together, so the call may return status processing several times — calling again with the same arguments keeps waiting, and several minutes is normal. A status of awaiting_uploads lists source files that were never transferred in missing_uploads. A status of failed is terminal: the errors field lists the causes, and waiting again does not regenerate the merge. When ready, each downloads[] entry carries the download_url of the merged document's PDF or Word file, a link that serves the file directly: save each file from it, or give it to the user when the client cannot download files itself. download_manifest_url lists the same files. Ready responses may also carry text_url and text_file_name, a signed URL to a plain-text rendering of the merged document's tracked changes. The links expire after one hour.

get_merged_document

Wait server-side for redlines to generate and return their download details. Returns redlines for the comparisons named by version_story_id and version_mapping_ids, whether they were staged moments ago or already exist in the project. Generation usually starts when the uploads land, so the call typically waits until the files are ready. It returns within about a minute with status ready, or with status processing and the still-pending options; calling again with the same arguments keeps waiting. Status failed means the missing formats will not arrive: each failed comparison carries failed_options and a failure_code, and any formats that did generate are still listed. Status awaiting_uploads lists source files that were never transferred. When status is ready, each downloads[] entry carries its download_url, a link that serves the file directly; save the file from it, or give it to the user when the client cannot download files itself. download_manifest_url is a signed JSON file listing the same files. Both expire after one hour. download_options selects the formats. Left unset, it returns the comparison's previewable redline: pdf_redline for document comparisons, excel_redline for spreadsheet comparisons. word_redline (Word tracked changes), pdf_changed_pages_only, excel_redline, and ["all"] serve requests for a specific file; a document's type alone is not a reason to request word_redline. viewer_redline, where available, is a self-contained interactive HTML page of the redline with a change-by-change sidebar, and accepts ?anchor=<id> to open on a specific change. It is not part of ["all"], and comparisons generated before it existed never produce one. Ready comparisons also carry text_url and text_file_name, a signed markdown rendering of the redline. read_text serves the same rendering through the connector, for analyzing the changes when the user asks about them; its description explains the change markup.

get_redlines

Wait server-side for a version history document to generate and return its download links. Returns the version history document identified by version_story_id and version_history_version_id. Generation first produces a comparison between each consecutive pair of versions and then layers them oldest to newest, so the call may return status processing several times — calling again with the same arguments keeps waiting, and several minutes is normal. A status of awaiting_uploads lists source files that were never transferred in missing_uploads. A status of failed is terminal: the errors field lists the causes, and waiting again does not regenerate the document. When ready, each downloads[] entry carries the download_url of the PDF or Word file, a link that serves the file directly: save each file from it, or give it to the user when the client cannot download files itself. download_manifest_url lists the same files. Ready responses may also carry text_url and text_file_name, a signed URL to a plain-text rendering of the document's attributed changes. The links expire after one hour.

get_version_history_document