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.
- A credential must list the workspace. It reaches the organization folder of its own organization.
- The full matrix is in Roles and permissions.
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.
- 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.
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. |
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, andbaseVersionID, 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 answers422 VALIDATION_FAILEDonfolderIDwith 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, itsfileIDis the file and itsversionIDis the new current version.
The file is checked twice.
When the upload starts:
- The file is unknown here:
404 NOT_FOUND. - The file is in the trash:
409 CONFLICT, reasonIN_TRASH. - The file's current version is no longer
baseVersionID:409 STALE_FILE_VERSION, withdetails.currentVersionID. - The replacement is of another type than the current version:
409 CONFLICT, reasonDIFFERENT_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
rejectedwithSTALE_FILE_VERSION. - If the file was moved to the trash in the meantime, the upload is
rejectedwithIN_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.pngwith a file calledlogo-final-v3.pngleaves a file namedlogo.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.
lockVersiondoes not move. Someone editing the file's details at the same time is not interrupted. See 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,
previewStatusispendingand 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 CONFLICTwith reasonDIFFERENT_TYPEand a message such as "Replace it with a file of the same type (.png)". - Another extension of the same type is fine: a
.jpegfile replaces a.jpgfile,.psbreplaces.psd,.m4vreplaces.mp4,.markdownreplaces.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.
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,
hasLocationDataistruefor it, and the app's sharing controls say so. See Sharing and public links. - The replacement is recorded in the audit trail with the person who did it. See Audit trail.
History
- A file's history lists its versions, newest first.
- It comes 50 versions a page (1 to 100 with
limit), with anextCursorwhile 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.
- 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
ETagback inIf-None-Matchanswers304 Not Modifiedwithout 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.
Going back to an earlier version
There is no "restore this version" action. To make earlier bytes current again:
- Download the earlier version.
- 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.
- 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.
In the app
Replacing a file
- Open the file's page.
- Choose "Replace file", above the preview.
- Your system's file picker opens. It offers files of the same type as the file.
- 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. - 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.
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 itscurrentVersion. That is wherebaseVersionIDcomes from. - Over MCP there is no tool that returns bytes. An agent asks for a
temporary address with
workspace_files_signed_urland fetches that. See Downloading.
Worked example: replace a file
Read the file to learn its current version:
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
The answer holds, among the rest:
{
"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:
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
ETags and read it until it is ready, exactly as for a new file. See
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:
{
"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
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/versions" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
"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:
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. |
A replacement can also end rejected, with STALE_FILE_VERSION, IN_TRASH
or any of the reasons of an ordinary upload. See
Uploading. The shape of every error is in
Errors.
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.
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.