Files

A file is one immutable document held by Version Story, named by a file_id. Uploads, edit results, created documents, and the results of accepting or rejecting tracked changes are all files, and every endpoint that reads a document takes its file_id.

POST /v1/files

multipart/form-data with one file field, document: a .docx, .doc or .pdf to read, edit or merge, or a .xlsx or .pptx to compare with another of its kind.

curl -sS https://api.versionstory.com/v1/files \
  -H "Authorization: Bearer vs_live_..." \
  -F "document=@nda.docx"

{ "file_id": "3f2a9c1e-...", "status": "processing" }

• A .docx answers at once while it is prepared in the background. processing needs no polling: every request that reads the file waits for it.
• A .doc or .pdf is converted to Word first. The request waits up to 20 seconds and answers ready, failed with an error, or processing if conversion is still running.
• A workbook or presentation is stored as it is and answers ready. It can be compared, never read or edited.

Reading and editing an uploaded file is covered on Edit.

GET /v1/files/{file_id}

Signed downloads for one file.

curl -sS "https://api.versionstory.com/v1/files/3f2a9c1e-...?format=docx,pdf" \
  -H "Authorization: Bearer vs_live_..."

{
  "file_id": "3f2a9c1e-...",
  "status": "processing",
  "downloads": [
    {
      "format": "docx",
      "url": "https://documents.versionstory.com/...",
      "file_name": "nda.docx",
      "expires_at": "2026-10-15T18:00:00+00:00"
    }
  ],
  "pending_formats": ["pdf"]
}

The first request for a PDF starts its conversion. While a format is pending, status is processing and the response carries Retry-After; poll again until status is ready. A conversion that failed is named in failed_formats, and a file whose source could not be read at all answers "status": "failed" with an error.

A document made by POST /v1/create is served as docx only; asking it for pdf is 400 UNSUPPORTED_FORMAT. Signed URLs are valid for one hour, and polling again mints fresh ones.

POST /v1/files/{file_id}/revisions

Accepts or rejects every tracked insertion, every tracked deletion, or both, into a new file. The source file is unchanged.

curl -sS -X POST https://api.versionstory.com/v1/files/3f2a9c1e-.../revisions \
  -H "Authorization: Bearer vs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"operations": ["accept_all_insertions", "reject_all_deletions"]}'

operations holds at most one decision for each kind of change:

Insertions and deletions include inserted or deleted text, paragraph marks, table rows and table cells, in the body, headers, footers, footnotes and endnotes. Revisions the request does not decide stay tracked in the new file: the other kind, moves, and formatting changes.

The response is 202 with the new file's id. Poll GET /v1/files/{file_id} with it until it is ready:

{ "file_id": "8c41d7b2-...", "status": "processing" }

A source that is still being produced (a PDF still converting, an edit still running) is accepted, and the job waits for it. To decide revisions one at a time, by author or by number, use the accept_revision and reject_revision edit operations.

POST /v1/files/{file_id}/acknowledge

For an organization with zero-day retention, deletes an uploaded file, a created document, or a revisions result as soon as you have saved what you need, instead of an hour after it was created. No body.

curl -sS -X POST https://api.versionstory.com/v1/files/3f2a9c1e-.../acknowledge \
  -H "Authorization: Bearer vs_live_..."

{ "file_id": "3f2a9c1e-...", "status": "deletion_queued" }

An edit's edited and redline files are deleted with the edit: acknowledge those with POST /v1/edit/{edit_id}/acknowledge.

Errors

Related

• Edit: read an uploaded file and change it with tracked changes
• Create: make a new Word document from styled paragraphs
• Data handling: what is kept, and for how long