Talewright Docs Open the app

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

ActionIn a workspaceIn the organization folderSessionCredential (scope)
See a file's historyEvery member of the workspaceEvery member of the organizationYesYes (files:read)
Download any versionEvery member of the workspaceEvery member of the organizationYesYes (files:read)
Replace a file (add a version)Every member of the workspaceOwners and adminsYesYes (files:write)
Delete a single versionNobodyNobodyNoNo
Make an earlier version current againNobody, 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:

PropertyMeaning
idThe version's ID.
fileIDThe file it belongs to.
numberIts place in the history, starting at 1.
parentVersionIDThe version it replaced. null for version 1.
digestThe SHA-256 of its bytes, written sha256:<hex>. Two versions with the same digest have the same bytes.
sizeBytesIts size in bytes.
mimeIts type, as confirmed from the bytes.
mediaWhat 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.
hasLocationDatatrue when an image's metadata holds a GPS position. See Sharing and public links.
createdAtWhen it was uploaded.
createdByWho 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

StaysChanges
The file's IDThe current version: a new id, the next number
The file's nameThe size, the digest and what is known about the content
Its folderThe thumbnail and the preview: made anew for the new version
Its statusFor a video: what its page plays
Its general access and its public linkhasLocationData, which belongs to the version
Its description, caption, alt text and tagsWho last updated the file, and when
Its field valuesWhich 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.
  • 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.

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

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

  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.
  • 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:

TextWhen
"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

OperationCapability IDMCP toolScope
GET W/files/{fileID}/versionsworkspace.files.versions.listworkspace_files_versions_listfiles:read
GET W/files/{fileID}/versions/{versionID}/contentworkspace.files.readnonefiles:read
POST W/files/{fileID}/versions/{versionID}/signed-urlworkspace.files.signed_urlworkspace_files_signed_urlfiles:read
POST W/uploads with targetFileID and baseVersionIDworkspace.uploads.createworkspace_uploads_createfiles:write
GET L/files/{fileID}/versionslibrary.files.versions.listlibrary_files_versions_listfiles:read
GET L/files/{fileID}/versions/{versionID}/contentlibrary.files.readnonefiles:read
POST L/files/{fileID}/versions/{versionID}/signed-urllibrary.files.signed_urllibrary_files_signed_urlfiles:read
POST L/uploads with targetFileID and baseVersionIDlibrary.uploads.createlibrary_uploads_createfiles: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.

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

SituationWhat happensWhy
Two people replace the same file at the same moment, both from version 1One 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 current409 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 checkedYour 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 checkedYour upload is rejected with IN_TRASH.A trashed file cannot change.
A replacement is started for a file in the trash409 CONFLICT, reason IN_TRASH.Restore the file first.
A PDF is used to replace a JPEG409 CONFLICT, reason DIFFERENT_TYPE.A replacement keeps the type.
A .jpeg file is used to replace a .jpg fileIt works.Both are JPEG.
A file was renamed from logo.png to logo.jpg and is then replacedIt 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.pngThe 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 JPEGThe 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 hasA new version is added, with the same digest.A replacement always adds a version.
A replacement holds malwareThe upload is rejected with MALWARE. The file keeps its version.Every upload is scanned.
A replacement names a folderID422 VALIDATION_FAILED on folderID.A replacement stays in its file's folder.
A replacement names targetFileID without baseVersionID422 VALIDATION_FAILED.The two go together.
targetFileID names a file of another workspace404 NOT_FOUND.The file must be in the workspace or organization folder the upload is started in.
baseVersionID names an earlier version of the file409 STALE_FILE_VERSION.Only the current version can be replaced.
A member replaces a file that is publicIt 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 file403 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 itBoth succeed.A new version does not move lockVersion.
The file's status is "Approved for public use" and it is replacedThe status stays.The status belongs to the file.
A public image without location data is replaced by one with itThe 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 renamedThe 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 file404 NOT_FOUND.A version belongs to one file.
The history of a trashed file is readIt 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 file409 CONFLICT, reason IN_TRASH.Temporary links are not given for trashed files.
The file is deleted for goodIts 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 openTheir 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 timesIt has 51 versions.There is no limit on versions.
A file with several versions is exportedThe export holds the current version.Exports hold current versions only.
You want version 2 to be current again after version 3Download version 2 and replace the file with it. That makes version 4.History only grows.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid credential.Sign in or use a valid credential.
FORBIDDEN403Replacing an organization folder file without being an owner or admin.Ask an owner or admin.
FORBIDDEN, reason INSUFFICIENT_SCOPE403The credential lacks files:write to replace, or files:read to read the history.Use a credential with the scope.
NOT_FOUND404The file is unknown, out of reach or deleted for good; the version is unknown or belongs to another file.Check the IDs.
STALE_FILE_VERSION409baseVersionID 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_TRASH409The file to replace is in the trash.Restore it first.
CONFLICT, reason DIFFERENT_TYPE409The replacement is of another type than the current version.Use a file of the same type, or upload it as a new file.
VALIDATION_FAILED422A replacement with folderID; only one of targetFileID and baseVersionID; an invalid cursor or limit in the history.Correct the request.
RANGE_NOT_SATISFIABLE416A 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

WhatValue
Versions per fileNo limit
Size of a replacementThe same as any upload: up to 50 GiB, or 2 GiB for an image, PDF, Word, Excel or Figma file
Type of a replacementThe type of the file's current version
Page size of the history1 to 100, default 50
How long earlier versions are keptAs long as the file exists
Time a browser may still show the earlier version at a public linkUp 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.