# Files

> Upload a document once, download it as Word or PDF, and accept or reject all of its tracked insertions or deletions into a new file.

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

| | |
| --- | --- |
| Base URL | `https://api.versionstory.com` |
| Auth | `Authorization: Bearer vs_...`. See [Authentication](/developers/authentication) |

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

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

```json
{ "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](/developers/rest/edit).

## GET /v1/files/{file_id}

Signed downloads for one file.

| Parameter | In | Required | Default | Meaning |
| --- | --- | --- | --- | --- |
| `file_id` | path | Yes | — | The file's id |
| `format` | query | No | `docx` | `docx`, `pdf`, or both. Repeatable or comma-separated. A workbook or presentation is served as it is (`xlsx`, `pptx`) |

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

```json
{
  "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`](/developers/rest/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.

```bash
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:

| Kind | Decisions |
| --- | --- |
| Insertions | `accept_all_insertions` or `reject_all_insertions` |
| Deletions | `accept_all_deletions` or `reject_all_deletions` |

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}`](#get-v1filesfileid)
with it until it is `ready`:

```json
{ "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](/developers/rest/edit-operations).

## POST /v1/files/{file_id}/acknowledge

For an organization with [zero-day retention](/developers/reference/data-handling#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.

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

```json
{ "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`](/developers/rest/edit#post-v1editeditidacknowledge).

## Errors

| Status | Code | Cause |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | A missing or empty `document`, or `operations` with two decisions for one kind |
| 400 | `UNSUPPORTED_FILE_TYPE` | The upload is not a `.docx`, `.doc`, `.pdf`, `.xlsx` or `.pptx` |
| 400 | `DOCUMENT_UNREADABLE` | The upload is not a readable Word file, or a revisions source will never have one: its processing or edit failed, or it is a workbook |
| 400 | `UNSUPPORTED_FORMAT` | A `format` is unknown, or not offered for this file |
| 401 | `INVALID_API_KEY` | Missing, malformed, unknown, revoked, or expired key |
| 402 | `USAGE_LIMIT_REACHED` | The organization's monthly upload allowance is exhausted |
| 404 | `FILE_NOT_FOUND` | No such file, or it belongs to another organization |
| 409 | `CONFLICT` | An acknowledgment of a file without zero-day retention, or of an edit's own file |
| 410 | `CONTENT_DELETED` | The file's content was deleted under zero-day retention |
| 413 | `FILE_TOO_LARGE` | The upload exceeds the 100 MB limit |

## Related

- [Edit](/developers/rest/edit): read an uploaded file and change it with tracked changes
- [Create](/developers/rest/create): make a new Word document from styled paragraphs
- [Data handling](/developers/reference/data-handling): what is kept, and for how long