# Versions and history

## Summary

A file is not one set of bytes. It is a named item with a history of
versions. The first upload makes version 1. Every time the file is replaced,
a new version is added and becomes the current one. Earlier versions are
kept, unchanged, and can be downloaded at any time.

Replacing a file keeps everything that belongs to the file: its name, its
place, its status, its details and its public link. Only the bytes change.
That is the point of replacing instead of uploading a second file: every
link and every reference keeps working and now leads to the new content.

This page covers what a version is, how a file is replaced, what stays and
what changes, the rule that a replacement must be of the same type, the
history, and downloading an earlier version.

## Who can do what

`W` stands for `/v1/workspaces/{workspaceID}` and `L` for
`/v1/organizations/{organizationID}/library`, the organization folder (the
API's library).

| Action | In a workspace | In the organization folder | Session | Credential (scope) |
| --- | --- | --- | --- | --- |
| See a file's history | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Download any version | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Replace a file (add a version) | Every member of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| Delete a single version | Nobody | Nobody | No | No |
| Make an earlier version current again | Nobody, directly. Replace the file with the earlier bytes. | The same | - | - |

- "Member of the workspace" includes organization owners and admins.
- Replacing a file needs no more than the right to change it. That holds
  for a public file too. See
  [Replacing a public file](#replacing-a-public-file).
- A credential must list the workspace. It reaches the organization folder
  of its own organization.
- The full matrix is in
  [Roles and permissions](../reference/permissions.md#files-in-a-workspace).

## How it works

### What a version is

- A version is one exact set of bytes of a file.
- A version never changes. Its bytes, size, type and digest are fixed from
  the moment it exists.
- A version exists only for bytes that passed every upload check: size,
  type, opening and the malware scan. See [Uploading](uploading.md).
- Versions are numbered from 1. Each new version gets the next number.
- A file's versions form one line. There are no branches.
- Exactly one version is the file's current version: the newest.
- A version cannot be deleted by itself. Versions go only when the whole
  file is deleted for good. See [Trash and restore](trash.md).

A version holds:

| Property | Meaning |
| --- | --- |
| `id` | The version's ID. |
| `fileID` | The file it belongs to. |
| `number` | Its place in the history, starting at 1. |
| `parentVersionID` | The version it replaced. `null` for version 1. |
| `digest` | The SHA-256 of its bytes, written `sha256:<hex>`. Two versions with the same digest have the same bytes. |
| `sizeBytes` | Its size in bytes. |
| `mime` | Its type, as confirmed from the bytes. |
| `media` | What is known about its content: width and height of an image, pages of a PDF, and for a video its width, height, duration and codecs. `null` for types that are not opened. |
| `hasLocationData` | `true` when an image's metadata holds a GPS position. See [Sharing and public links](sharing.md). |
| `createdAt` | When it was uploaded. |
| `createdBy` | Who uploaded it: `id` and `fullName`. |

### Replacing a file

Replacing is an upload that names the file it replaces.

- The upload names `targetFileID`, the file, and `baseVersionID`, the
  version you are replacing: the file's current version as you last saw it.
- Both are given together. Naming only one answers `422
  VALIDATION_FAILED`.
- A replacement names no `folderID`. The file stays where it is. Naming one
  answers `422 VALIDATION_FAILED` on `folderID` with the message "a
  replacement stays in its file's folder".
- Everything else is an ordinary upload: start, send the bytes, complete,
  then wait for the checks. The same size limit and the same checks apply.
- When the upload is `ready`, its `fileID` is the file and its `versionID`
  is the new current version.

The file is checked twice.

**When the upload starts:**

1. The file is unknown here: `404 NOT_FOUND`.
2. The file is in the trash: `409 CONFLICT`, reason `IN_TRASH`.
3. The file's current version is no longer `baseVersionID`: `409
   STALE_FILE_VERSION`, with `details.currentVersionID`.
4. The replacement is of another type than the current version: `409
   CONFLICT`, reason `DIFFERENT_TYPE`.

Nothing is created in any of these cases, and no bytes need to be sent.

**When the checks have passed and the version is about to be added:**

- If the file got another version in the meantime, the upload is `rejected`
  with `STALE_FILE_VERSION`.
- If the file was moved to the trash in the meantime, the upload is
  `rejected` with `IN_TRASH`.
- Otherwise the new version is added and becomes current, in one step.

So a replacement never lands on top of a version you have not seen. Of two
replacements based on the same version, exactly one becomes the next
version. The other is rejected, and its bytes become nothing.

### What stays and what changes

| Stays | Changes |
| --- | --- |
| The file's ID | The current version: a new `id`, the next `number` |
| The file's name | The size, the digest and what is known about the content |
| Its folder | The thumbnail and the preview: made anew for the new version |
| Its status | For a video: what its page plays |
| Its general access and its public link | `hasLocationData`, which belongs to the version |
| Its description, caption, alt text and tags | Who last updated the file, and when |
| Its field values | Which other files are its duplicates |
| Everyone's favorites of it | |
| Its `lockVersion` | |
| Every earlier version | |

- **The name stays.** The file keeps its own name, whatever the replacement
  was called on your computer. Replacing `logo.png` with a file called
  `logo-final-v3.png` leaves a file named `logo.png`.
- **The status stays.** The status belongs to the file, not to its bytes. A
  file that was "Approved for public use" before is still approved after.
- **The public link stays.** It always serves the current version, so from
  now on it serves the new bytes.
- **`lockVersion` does not move.** Someone editing the file's details at
  the same time is not interrupted. See
  [Lock versions](organizing.md#lock-versions).
- **The file counts as updated.** It moves to the top of a listing sorted
  by "Recently updated".
- **The preview is new.** Until it is made, `previewStatus` is `pending`
  and the file shows its type icon.
- Replacing a file with the very same bytes still adds a version.

### The type rule

A replacement must be of the same type as the file's current version.

- The type is the stored type of the current version (`mime`), not the
  extension in the file's name.
- A replacement of another type answers `409 CONFLICT` with reason
  `DIFFERENT_TYPE` and a message such as "Replace it with a file of the
  same type (.png)".
- Another extension of the same type is fine: a `.jpeg` file replaces a
  `.jpg` file, `.psb` replaces `.psd`, `.m4v` replaces `.mp4`, `.markdown`
  replaces `.md`.
- A different type is refused even when it looks close: a PDF does not
  replace a JPEG, a PNG does not replace a JPEG, HEIF does not replace
  HEIC, QuickTime does not replace MP4, a Word file does not replace a PDF.
- The reason for the rule is the public link. It keeps its address and its
  name, so it must keep serving the same kind of file.
- To switch type, upload the new file as a new file.
- As with every upload, the replacement's bytes are then checked against
  that type. See [How the type is decided](uploading.md#how-the-type-is-decided).

### Replacing a public file

- Anyone who may change a file may replace it. In a workspace that is every
  member. Making the file public was the decision of an owner or admin;
  replacing its content is not a new decision about access.
- No confirmation is asked.
- The public link serves the new version as soon as it is current.
- A browser that loaded the link shortly before may show the earlier
  version for up to 60 seconds.
- The earlier version is no longer reachable through the public link. It is
  still in the history for the people who can open the file.
- The file's status and general access are untouched.
- If the new version is an image whose metadata holds a GPS position,
  `hasLocationData` is `true` for it, and the app's sharing controls say
  so. See [Sharing and public links](sharing.md).
- The replacement is recorded in the audit trail with the person who did
  it. See [Audit trail](../reference/audit-trail.md#files).

### History

- A file's history lists its versions, newest first.
- It comes 50 versions a page (1 to 100 with `limit`), with a `nextCursor`
  while there are older ones.
- The first entry is the current version.
- Each entry carries the version's number, size, type, digest, who uploaded
  it and when.
- If the uploader's account was deleted since, the entry names "Deleted
  user". See [Deleting an account](../accounts/delete-account.md).
- There is no limit on the number of versions a file can have.
- The history of a file in the trash can still be read.
- Once a file is deleted for good, its history answers `404 NOT_FOUND`.

### Downloading an earlier version

- Every version stays downloadable for as long as the file exists.
- A version is downloaded by its own ID, so the answer is always exactly
  those bytes.
- The download is named after the file's current name, not after what the
  file was called when that version was uploaded.
- A version ID that belongs to another file answers `404 NOT_FOUND`.
- Thumbnails and previews of earlier versions are kept too.
- A temporary link names one version, so what it serves never changes. A
  request that sends the link's `ETag` back in `If-None-Match` answers
  `304 Not Modified` without a body, for as long as the link works.
- How downloads work, and the difference between downloading through the
  API and through a temporary link, is in [Downloading](downloading.md).

### Going back to an earlier version

There is no "restore this version" action. To make earlier bytes current
again:

1. Download the earlier version.
2. Replace the file with it.

The result is a new version with the old bytes. The history keeps every
step: version 3 with the bytes of version 1 follows version 2.

### Versions and the rest of the product

- **Trash.** A trashed file keeps all its versions. It cannot be replaced
  while it is in the trash. A restore brings it back with its whole
  history.
- **Permanent deletion.** Deleting a file for good deletes every version.
- **Export.** An organization export holds each file's current version
  only. See [Export](../organizations/export.md).
- **Duplicates.** Files are compared by their current versions. Earlier
  versions are not compared.
- **Search and filters.** The type filter goes by the current version.
- **Image delivery.** The resized images of a public link follow the
  current version. See [Image delivery](image-delivery.md).

## In the app

### Replacing a file

1. Open the file's page.
2. Choose "Replace file", above the preview.
3. Your system's file picker opens. It offers files of the same type as
   the file.
4. Choose one file.

- There is no confirmation. The upload starts at once.
- The upload tray shows the chosen file with the line "Replacing {name}",
  where `{name}` is the file being replaced. It goes through "Uploading",
  "Verifying" and "Ready" like any upload. See
  [The upload tray](uploading.md#the-upload-tray).
- While the replacement is being sent and checked, "Replace file" shows a
  spinner and is disabled.
- When it is ready, the page updates by itself: the preview, "Download" and
  "History" show the new version.
- "Replace file" is on the file's page only. It is not in the menus of a
  listing, and a file cannot be replaced by dropping a file onto it.
- The button is shown to whoever may change the file: every member in a
  workspace, owners and admins in the organization folder.
- A file in the trash has no "Replace file".

What the tray says when a replacement is refused:

| Text | When |
| --- | --- |
| "Rejected: Someone replaced this file first" | The file got a newer version after you opened its page. |
| "Rejected: Replace it with a PNG file" (or the file's own type, such as "a Markdown file" or "a text file") | The chosen file is of another type. |
| "Rejected: The file is in the trash" | The file was moved to the trash. |

Every other text is the same as for a new upload. See
[Reasons shown on a row](uploading.md#reasons-shown-on-a-row).

### When someone replaced the file first

Your replacement is based on the version the page showed when you opened
it.

- If someone else replaced the file since, yours is refused: the tray says
  "Rejected: Someone replaced this file first".
- The page shows "This file changed since you opened it. Reloading keeps
  your unsaved edits." with the button "Reload latest".
- "Replace file" and "Move to trash" are disabled until you reload.
- After "Reload latest" the history shows the other person's version, and
  you can replace the file again, now on top of theirs.

### History in the app

The "History" section is in "Details" on the file's page.

- It lists the versions, newest first: "Version 3", "Version 2", "Version
  1".
- Under each: "Uploaded by {name}, {date and time} · {size}".
- The top entry is the current version. It has no special label.
- "Load older versions" shows more when the history is long.
- While it loads the section says "Loading the history". If it cannot be
  loaded: "Could not load the history." with "Retry".
- The history is shown for a file in the trash too.

### Downloading an earlier version in the app

- Each entry of the history has a "Download" link, read to screen readers
  as "Download version {n}".
- It saves exactly that version, under the file's current name.
- "Download" above the preview always saves the current version.

## For agents

### Operations

| Operation | Capability ID | MCP tool | Scope |
| --- | --- | --- | --- |
| `GET W/files/{fileID}/versions` | `workspace.files.versions.list` | `workspace_files_versions_list` | `files:read` |
| `GET W/files/{fileID}/versions/{versionID}/content` | `workspace.files.read` | none | `files:read` |
| `POST W/files/{fileID}/versions/{versionID}/signed-url` | `workspace.files.signed_url` | `workspace_files_signed_url` | `files:read` |
| `POST W/uploads` with `targetFileID` and `baseVersionID` | `workspace.uploads.create` | `workspace_uploads_create` | `files:write` |
| `GET L/files/{fileID}/versions` | `library.files.versions.list` | `library_files_versions_list` | `files:read` |
| `GET L/files/{fileID}/versions/{versionID}/content` | `library.files.read` | none | `files:read` |
| `POST L/files/{fileID}/versions/{versionID}/signed-url` | `library.files.signed_url` | `library_files_signed_url` | `files:read` |
| `POST L/uploads` with `targetFileID` and `baseVersionID` | `library.uploads.create` | `library_uploads_create` | `files:write` |

- A file read (`GET W/files/{fileID}`) carries its `currentVersion`. That
  is where `baseVersionID` comes from.
- Over MCP there is no tool that returns bytes. An agent asks for a
  temporary address with `workspace_files_signed_url` and fetches that. See
  [Downloading](downloading.md).

### Worked example: replace a file

Read the file to learn its current version:

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

The answer holds, among the rest:

```json
{
  "id": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
  "name": "logo.png",
  "currentVersion": {
    "id": "0192f0b2-7a40-7133-9c88-5c9a3f4b0e23",
    "number": 1,
    "mime": "image/png",
    "sizeBytes": 20480,
    "digest": "sha256:9f2c..."
  }
}
```

Start the replacement, naming the file and that version:

```sh
curl -s -X POST "$TALEWRIGHT/v1/workspaces/$WORKSPACE/uploads" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "logo.png",
    "sizeBytes": 23110,
    "contentType": "image/png",
    "targetFileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
    "baseVersionID": "0192f0b2-7a40-7133-9c88-5c9a3f4b0e23",
    "requestID": "logo-replace-2026-11-14"
  }'
```

Then send the parts to their addresses, complete the upload with their
`ETag`s and read it until it is `ready`, exactly as for a new file. See
[Worked example](uploading.md#worked-example).

When it is ready, the upload's `versionID` is the file's new current
version, with `number` 2 and `parentVersionID` set to version 1.

If someone replaced the file between your read and your start, the start
answers:

```json
{
  "error": {
    "code": "STALE_FILE_VERSION",
    "message": "This file changed since you opened it",
    "details": {
      "currentVersionID": "0192f0e7-1b22-7c90-8d31-2a4b6c8e0f12"
    }
  },
  "requestID": "..."
}
```

Read the file again, look at the version that is current now, and decide
whether your replacement still applies.

### Worked example: read the history

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/versions" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

```json
{
  "items": [
    {
      "id": "0192f0e7-1b22-7c90-8d31-2a4b6c8e0f12",
      "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "number": 2,
      "parentVersionID": "0192f0b2-7a40-7133-9c88-5c9a3f4b0e23",
      "digest": "sha256:41ab...",
      "sizeBytes": 23110,
      "mime": "image/png",
      "media": { "width": 800, "height": 600 },
      "hasLocationData": false,
      "createdAt": "2026-11-14T10:05:00Z",
      "createdBy": { "id": "0192e7c1-...", "fullName": "Dana Reyes" }
    },
    {
      "id": "0192f0b2-7a40-7133-9c88-5c9a3f4b0e23",
      "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "number": 1,
      "parentVersionID": null,
      "digest": "sha256:9f2c...",
      "sizeBytes": 20480,
      "mime": "image/png",
      "media": { "width": 640, "height": 480 },
      "hasLocationData": false,
      "createdAt": "2026-11-02T09:00:00Z",
      "createdBy": { "id": "0192e7c1-...", "fullName": "Dana Reyes" }
    }
  ],
  "nextCursor": null
}
```

To download version 1:

```sh
curl -s -o logo-v1.png \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/versions/$VERSION_1/content" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| Two people replace the same file at the same moment, both from version 1 | One upload ends `ready` as version 2. The other ends `rejected` with `STALE_FILE_VERSION`. | A replacement lands only on the version it was based on. |
| A replacement is started from a version that is no longer current | `409 STALE_FILE_VERSION` at the start, with `details.currentVersionID`. | Someone replaced the file first. |
| The file gets a new version while your replacement is being checked | Your upload is `rejected` with `STALE_FILE_VERSION`. Your bytes are not kept. | The check is repeated when the version is added. |
| The file is moved to the trash while your replacement is being checked | Your upload is `rejected` with `IN_TRASH`. | A trashed file cannot change. |
| A replacement is started for a file in the trash | `409 CONFLICT`, reason `IN_TRASH`. | Restore the file first. |
| A PDF is used to replace a JPEG | `409 CONFLICT`, reason `DIFFERENT_TYPE`. | A replacement keeps the type. |
| A `.jpeg` file is used to replace a `.jpg` file | It works. | Both are JPEG. |
| A file was renamed from `logo.png` to `logo.jpg` and is then replaced | It must be replaced with a PNG. | The type comes from the current version, not from the name. |
| The replacement is called `banner-new.png` and the file `banner.png` | The file is still called `banner.png`. | Replacing changes the bytes, not the name. |
| A PNG is replaced by a file named `.png` whose content is a JPEG | The upload is `rejected` with `TYPE_MISMATCH`. The file keeps its version. | The content is checked against the type. |
| A file is replaced with the same bytes it already has | A new version is added, with the same digest. | A replacement always adds a version. |
| A replacement holds malware | The upload is `rejected` with `MALWARE`. The file keeps its version. | Every upload is scanned. |
| A replacement names a `folderID` | `422 VALIDATION_FAILED` on `folderID`. | A replacement stays in its file's folder. |
| A replacement names `targetFileID` without `baseVersionID` | `422 VALIDATION_FAILED`. | The two go together. |
| `targetFileID` names a file of another workspace | `404 NOT_FOUND`. | The file must be in the workspace or organization folder the upload is started in. |
| `baseVersionID` names an earlier version of the file | `409 STALE_FILE_VERSION`. | Only the current version can be replaced. |
| A member replaces a file that is public | It works. The public link serves the new version. | Replacing needs only the right to change the file. |
| A member of the organization replaces an organization folder file | `403 FORBIDDEN`. In the app there is no "Replace file" for them. | Only owners and admins change the organization folder. |
| Someone edits the file's description while you replace it | Both succeed. | A new version does not move `lockVersion`. |
| The file's status is "Approved for public use" and it is replaced | The status stays. | The status belongs to the file. |
| A public image without location data is replaced by one with it | The link serves the new image, location data included. `hasLocationData` is `true`. | Bytes are served exactly as uploaded. |
| An earlier version is downloaded after the file was renamed | The download carries the file's current name. | Versions have no names of their own. |
| A version ID of another file is asked for under this file | `404 NOT_FOUND`. | A version belongs to one file. |
| The history of a trashed file is read | It works, and its versions can be downloaded through the API. | A trashed file is kept whole until it is deleted for good. |
| A temporary link is asked for a version of a trashed file | `409 CONFLICT`, reason `IN_TRASH`. | Temporary links are not given for trashed files. |
| The file is deleted for good | Its history and every version answer `404 NOT_FOUND`. | Permanent deletion takes every version. |
| A file is replaced and then its page is opened by someone who had it open | Their page shows the earlier version until it refreshes. A replacement from that page is refused as stale. | Each page works from what it loaded. |
| A QuickTime movie is replaced by another | "Preparing video" shows again until the new playback rendition is ready. | Renditions are made per version. |
| A file is replaced 50 times | It has 51 versions. | There is no limit on versions. |
| A file with several versions is exported | The export holds the current version. | Exports hold current versions only. |
| You want version 2 to be current again after version 3 | Download version 2 and replace the file with it. That makes version 4. | History only grows. |

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
| `FORBIDDEN` | 403 | Replacing an organization folder file without being an owner or admin. | Ask an owner or admin. |
| `FORBIDDEN`, reason `INSUFFICIENT_SCOPE` | 403 | The credential lacks `files:write` to replace, or `files:read` to read the history. | Use a credential with the scope. |
| `NOT_FOUND` | 404 | The file is unknown, out of reach or deleted for good; the version is unknown or belongs to another file. | Check the IDs. |
| `STALE_FILE_VERSION` | 409 | `baseVersionID` is not the file's current version. `details.currentVersionID` names it. Message: "This file changed since you opened it". | Read the file again and start over from the current version. |
| `CONFLICT`, reason `IN_TRASH` | 409 | The file to replace is in the trash. | Restore it first. |
| `CONFLICT`, reason `DIFFERENT_TYPE` | 409 | The replacement is of another type than the current version. | Use a file of the same type, or upload it as a new file. |
| `VALIDATION_FAILED` | 422 | A replacement with `folderID`; only one of `targetFileID` and `baseVersionID`; an invalid `cursor` or `limit` in the history. | Correct the request. |
| `RANGE_NOT_SATISFIABLE` | 416 | A download asks for bytes past the end of the version. | See [Downloading](downloading.md). |

A replacement can also end `rejected`, with `STALE_FILE_VERSION`, `IN_TRASH`
or any of the reasons of an ordinary upload. See
[Uploading](uploading.md#errors). The shape of every error is in
[Errors](../reference/errors.md).

## Limits

| What | Value |
| --- | --- |
| Versions per file | No limit |
| Size of a replacement | The same as any upload: up to 50 GiB, or 2 GiB for an image, PDF, Word, Excel or Figma file |
| Type of a replacement | The type of the file's current version |
| Page size of the history | 1 to 100, default 50 |
| How long earlier versions are kept | As long as the file exists |
| Time a browser may still show the earlier version at a public link | Up to 60 seconds |

## Questions and answers

**What is the difference between replacing a file and uploading it again?**
Uploading again makes a second file with its own name, status and links.
Replacing keeps the one file, with its name, status, details and links, and
gives it new content.

**Does the public link change when I replace a file?**
No. The link stays the same and serves the new version.

**Does the file keep its status when I replace it?**
Yes. An approved file stays approved. If the new content needs a fresh
review, an owner or admin sets another status.

**Can a member replace a file that is public?**
Yes, in a workspace. The file's new content is then what the public link
serves. If that is not what you want for a file, keep it in the organization
folder, which only owners and admins change, or restrict it.

**Can I see who replaced a file and when?**
Yes. The "History" section lists every version with who uploaded it and when.

**Can I get an old version back?**
Yes. Every version can be downloaded from the history. To make it the
current one again, replace the file with it.

**Can I delete one version?**
No. Versions are kept as long as the file exists.

**Is there a limit on versions?**
No.

**Can I replace a JPEG with a PNG?**
No. A replacement must be of the same type, so that every link to the file
keeps serving the same kind of file. Upload the PNG as a new file.

**Why does the file keep its old name after I replaced it?**
Replacing changes the content, not the name. Rename the file if you want
another name.

**Someone replaced the file while I was about to. What happened to mine?**
It was refused, and nothing of it was kept. Choose "Reload latest", look at
their version, and replace the file again if you still want to.

**Do earlier versions count as duplicates?**
No. Files are compared by their current versions only.

**Are earlier versions public?**
No. A public link serves the current version only. Earlier versions are for
people who can open the file.

**Does an export include the history?**
No. An export holds each file's current version.

**What happens to the versions when I move a file to the trash?**
They are kept and come back with a restore. Deleting the file for good
deletes all of them.

**How does an agent replace a file?**
It reads the file, starts an upload with `targetFileID` and `baseVersionID`
set to the file's `currentVersion.id`, sends the bytes and completes the
upload. See [Worked example: replace a file](#worked-example-replace-a-file).

**What should an agent do on `STALE_FILE_VERSION`?**
Read the file again. Someone added a version. The agent should not replace
that version blindly: it starts over from the current version only if its
change still applies.

## Related pages

- [Files & Assets overview](overview.md)
- [Uploading](uploading.md)
- [Downloading](downloading.md)
- [Trash and restore](trash.md)
- [Statuses](statuses.md)
- [Sharing and public links](sharing.md)
- [Image delivery](image-delivery.md)
- [Export](../organizations/export.md)
- [Audit trail](../reference/audit-trail.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

