Talewright Docs Open the app

Uploading

Summary

Uploading brings a file's bytes into a workspace or into the organization folder. Every upload is checked before it becomes a file: its size, its type, whether it opens, and whether it holds malware. Until those checks pass, nobody can open the bytes, and no file exists.

An upload makes either a new file or a new version of an existing file. This page covers new files and everything the two have in common. Replacing a file is described in Versions and history.

In the app you choose files, choose a folder, or drag them in, and follow each one in the upload tray. Through the API an upload is three steps: start it, send the bytes in parts, complete it. A file can be up to 50 GiB, and an upload that stopped half way resumes from the parts already sent.

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)
Start an upload (new file or replacement)Every member of the workspaceOrganization owners and adminsYesYes (files:write)
Get addresses for parts of your uploadEvery member of the workspaceOrganization owners and adminsYesYes (files:write)
List the parts of your upload already storedWhoever started itWhoever started itYesYes (files:read)
Complete your uploadEvery member of the workspaceOrganization owners and adminsYesYes (files:write)
Cancel your uploadEvery member of the workspaceOrganization owners and adminsYesYes (files:write)
Read one of your uploadsWhoever started itWhoever started itYesYes (files:read)
List your uploadsEveryone, for their ownEveryone, for their ownYesYes (files:read)
  • "Member of the workspace" includes organization owners and admins, who reach every workspace.
  • An upload belongs to the person who started it. Nobody else can read it, get addresses for its parts, list its parts, complete it or cancel it, admins included. They get 404 NOT_FOUND.
  • An upload started through a credential belongs to the member the credential acts for.
  • A credential must list the workspace. It reaches the organization folder of its own organization.
  • files:write includes files:read.
  • No verified email is needed to upload.
  • The full matrix is in Roles and permissions.

How it works

The three steps

  1. Start. You declare the file's name, its size in bytes and its content type. The answer is an upload in the state pending, with the size of its parts (partSizeBytes), how many there are (partCount), an address for each of the first 100 parts (partURLs) and the time the upload expires unless completed (expiresAt).
  2. Send. You cut the file into parts: every part is partSizeBytes long except the last, which holds the rest. You send each part with one HTTP PUT to its address and keep the ETag header of each answer. The address accepts exactly that part's number of bytes. Anything else is refused by the storage with 403. Parts can be sent in any order, several at once, and again.
  3. Complete. You tell Talewright the parts are there, naming each part with its ETag. Talewright checks them against the parts it holds and joins them into the file's bytes. The upload becomes verifying and the checks start. You then read the upload until it is ready or rejected.
  • A small file is one part: start, one PUT, complete.
  • Nothing is a file before step 3 has finished with ready. A file never appears in a listing while it is still being sent or checked.
  • The bytes are stored exactly as they were sent. Nothing is stripped, converted or recompressed.
  • One upload makes at most one version, however often it is completed or retried behind the scenes.

What you declare when starting

FieldRule
fileNameRequired. 1 to 200 characters after trimming spaces at both ends. No control characters, no / and no \. The extension decides the file type. It becomes the new file's name.
sizeBytesRequired. Exactly the number of bytes you will send. At least 1, at most the upload limit: 50 GiB, or 2 GiB for images, PDFs, Word, Excel and Figma files.
contentTypeRequired. The type of the file, or an empty string, or application/octet-stream to go by the extension alone.
folderIDOptional. A live folder of the same workspace or organization folder. Left out, the file goes to the top level. Not allowed with a replacement.
sha256Optional. The SHA-256 of the bytes as 64 hexadecimal digits, with or without the prefix sha256:. If given, other bytes are rejected.
targetFileID and baseVersionIDOptional, always together. They make the upload a replacement. See Versions and history.
requestIDOptional over REST, required for the MCP tool. Your own ID for this start. Repeating the same request with the same requestID within 24 hours returns the upload the first request made instead of a second one. See Safe retries.

The checks at the start happen in this order. The first that fails decides the answer, and no upload is created:

  1. Not signed in: 401 UNAUTHENTICATED.
  2. The workspace or organization is unknown or out of your reach: 404 NOT_FOUND.
  3. The organization folder, and you are not an owner or admin: 403 FORBIDDEN.
  4. Uploads are paused: 503 UNAVAILABLE with details.reason UPLOADS_DISABLED.
  5. fileName breaks its rule: 422 VALIDATION_FAILED on fileName.
  6. sizeBytes is 0 or negative: 422 VALIDATION_FAILED on sizeBytes.
  7. sizeBytes is over the limit: 413 PAYLOAD_TOO_LARGE with details.limitBytes.
  8. The extension is not accepted, or contentType does not match it: 415 UNSUPPORTED_MEDIA_TYPE.
  9. An image, PDF, Word, Excel or Figma file is over 2 GiB: 413 PAYLOAD_TOO_LARGE with details.limitBytes.
  10. sha256 is not 64 hexadecimal digits: 422 VALIDATION_FAILED on sha256.
  11. A replacement names a folderID, or only one of targetFileID and baseVersionID: 422 VALIDATION_FAILED.
  12. A replacement's file is unknown (404), in the trash (409 CONFLICT IN_TRASH), already has a newer version (409 STALE_FILE_VERSION) or is of another type (409 CONFLICT DIFFERENT_TYPE).
  13. folderID is not a live folder here: 422 VALIDATION_FAILED on folderID.

Because the size is checked before the type, a file that is both over 50 GiB and of an unaccepted type is refused for its size.

Accepted types

The extension of fileName picks the type. Upper and lower case do not matter: .JPG is .jpg. A name without an accepted extension is refused with 415 UNSUPPORTED_MEDIA_TYPE.

GroupTypeExtensionsStored as (mime)
ImagesJPEG.jpg, .jpegimage/jpeg
ImagesPNG.pngimage/png
ImagesGIF.gifimage/gif
ImagesWebP.webpimage/webp
ImagesAVIF.avifimage/avif
ImagesSVG.svgimage/svg+xml
ImagesICO.icoimage/x-icon
ImagesHEIC.heicimage/heic
ImagesHEIF.heif, .hifimage/heif
ImagesPhotoshop.psd, .psbimage/vnd.adobe.photoshop
Raw photosAdobe DNG.dngimage/x-adobe-dng
Raw photosCanon.cr2, .cr3image/x-canon-cr2, image/x-canon-cr3
Raw photosNikon.nefimage/x-nikon-nef
Raw photosSony.arwimage/x-sony-arw
Raw photosFujifilm.rafimage/x-fuji-raf
Raw photosOlympus.orfimage/x-olympus-orf
Raw photosPanasonic.rw2image/x-panasonic-rw2
Design filesIllustrator.aiapplication/illustrator
Design filesEPS.eps, .epsfapplication/postscript
Design filesInDesign.inddapplication/x-indesign
Design filesFigma.figapplication/x-figma
FontsWOFF.wofffont/woff
FontsWOFF2.woff2font/woff2
FontsTrueType.ttffont/ttf
FontsOpenType.otffont/otf
VideoMP4.mp4, .m4vvideo/mp4
VideoWebM.webmvideo/webm
VideoQuickTime.mov, .qtvideo/quicktime
DocumentsPDF.pdfapplication/pdf
DocumentsCSV.csvtext/csv
DocumentsWord.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
DocumentsExcel.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
DocumentsMarkdown.md, .markdowntext/markdown
DocumentsPlain text.txttext/plain

That is 35 types and 42 extensions. Everything else is refused. In particular:

  • Archives such as .zip are refused.
  • Older Office formats such as .doc, .xls and .ppt are refused.
  • Programs such as .exe are refused.
  • HTML is refused.
  • Plain TIFF images are refused. Only the raw photo formats above are accepted among TIFF-based files.
  • Matroska video (.mkv) is refused, also when it is named .webm.

How the type is decided

The type is decided twice: once from what you declare, once from the bytes.

From what you declare, when starting:

  • The extension names the type.
  • contentType must agree with it. It agrees when it is empty, when it is application/octet-stream, when it is the stored type from the table, or when it is one of the other names browsers and operating systems use for that type.
  • Anything after a ; in contentType is ignored, and case does not matter.
  • If it does not agree, the answer is 415 UNSUPPORTED_MEDIA_TYPE with a message such as "contentType text/html does not match a .png file".

Other content types accepted for a type:

TypeAlso accepted as contentType
JPEGimage/pjpeg
ICOimage/vnd.microsoft.icon
HEICimage/heic-sequence
HEIFimage/heif-sequence
Photoshopimage/photoshop, image/x-photoshop, image/psd, application/photoshop, application/x-photoshop, application/psd
Adobe DNGimage/dng
Fujifilmimage/x-fujifilm-raf
Panasonicimage/x-panasonic-raw
Illustratorapplication/postscript, application/pdf, application/vnd.adobe.illustrator
EPSapplication/eps, application/x-eps, image/eps, image/x-eps
WOFFapplication/font-woff
WOFF2application/font-woff2
TrueTypeapplication/x-font-ttf, application/font-sfnt
OpenTypeapplication/x-font-otf, application/vnd.ms-opentype
MP4video/x-m4v
CSVapplication/vnd.ms-excel
Markdowntext/x-markdown, text/plain

From the bytes, during verification:

  • The content is read and must be the type the extension claims.
  • Content of another accepted type is rejected with TYPE_MISMATCH. A PNG named photo.jpg is an example.
  • Content of no accepted type is rejected with TYPE_NOT_ALLOWED. An HTML page named banner.png is an example.
  • The stored mime of a version is always the type that was confirmed from the bytes.

Rules for particular types:

  • HEIC and HEIF overlap. A .heic file may hold HEIF content and the other way round.
  • An Illustrator file may be PDF-based or PostScript-based. Both are accepted as .ai.
  • An EPS file must be EPS. Other PostScript named .eps is rejected.
  • Word, Excel and Figma files are containers. A container that is none of the three is rejected, whatever it is named.
  • CSV and SVG files must be UTF-8 text. A CSV file that is empty of anything but blank space is rejected.
  • A file whose text starts with markup is SVG only when its root element is svg. Any other markup is not an accepted type.
  • Markdown and plain text have no signature. Any content that reads as text passes as .md, .markdown or .txt: UTF-8, text in an older 8-bit encoding, UTF-16 with a byte order mark, text that looks like a table and text that starts with markup. Binary content is rejected.
  • A QuickTime movie named .mp4 is rejected with TYPE_MISMATCH. Name it .mov.

Size limits

  • A file is at least 1 byte.
  • A file is at most 50 GiB, which is 53,687,091,200 bytes, on every plan. A file of 53,687,091,201 bytes is refused.
  • Images (JPEG, PNG, GIF, WebP, AVIF, SVG, ICO aside, HEIC, HEIF and Photoshop), PDFs, Word, Excel and Figma files are at most 2 GiB, which is 2,147,483,648 bytes. Checking them means opening the whole file. Videos, raw photos, Illustrator, EPS, InDesign, fonts, CSV, Markdown, text and ICO go up to 50 GiB.
  • A GiB is 1,073,741,824 bytes and a MiB 1,048,576. Sizes in listings are in MB and GB of 1,000,000 and 1,000,000,000 bytes, so the largest file that fits shows there as 53.7 GB.
  • The limits are settings of the service. A refusal always states the limit in force, in bytes, in details.limitBytes. The tray's message is made from that number: in GiB from 1 GiB up, otherwise in MiB, rounded down. The sentence an empty folder shows always reads "up to 50 GiB (images, PDF, Word, Excel and Figma up to 2 GiB)".
  • A larger declared size answers 413 PAYLOAD_TOO_LARGE. details.limitBytes holds the limit in bytes.
  • The limits are checked when the upload starts, before any byte is sent.
  • An empty file cannot be uploaded.

Parts and their addresses

  • partSizeBytes is 16 MiB. A file that would need more than 10,000 parts of that size gets larger parts instead: the smallest whole number of MiB that keeps it within 10,000. A file of up to 156 GiB needs no larger parts, so at the 50 GiB limit parts are always 16 MiB.
  • Every part but the last is exactly partSizeBytes. The last holds the rest. partCount says how many there are, at most 10,000.
  • Part sizes are fixed when the upload starts. A file of 1 byte to 16 MiB is one part.
  • Each part has its own address. Starting the upload answers the addresses of the first 100 parts in partURLs, each with partNumber, sizeBytes, url and expiresAt. Reading the upload later answers partURLs: null.
  • POST .../uploads/{uploadID}/part-urls with {"partNumbers": [...]} answers the addresses of 1 to 100 more parts. Ask again for a part whose address expired. Part numbers run from 1 to partCount; others are refused with 422 VALIDATION_FAILED on partNumbers.
  • An address works for 15 minutes, or until the upload expires when that is sooner. Its expiresAt says when.
  • A PUT must send exactly the part's sizeBytes bytes. It needs no other header: no Content-Type and no Authorization. A part of another length is refused with 403, and so is a PUT after the address expired.
  • The storage answers each PUT with an ETag header, such as "9b2cf535f27731c974343645a3985328". Keep it: completing names it.
  • Sending a part again replaces it. The storage keeps the last bytes sent for each part number.
  • An address is a secret for as long as it works. Whoever has it can send that part. It never lets anyone read anything.

Resuming

  • GET .../uploads/{uploadID}/parts lists the parts the storage already holds for a pending upload, by part number, each with partNumber, sizeBytes and etag (without quotes).
  • To resume after a crash or a lost connection, list the parts, send only the ones missing, and complete with all of them. The listed etag values are the ones to name.
  • Listing or asking for addresses answers 409 CONFLICT with reason NOT_PENDING once the upload is completed or cancelled, and EXPIRED once it expired.

Completing

  • Completing sends {"parts": [{"partNumber": 1, "etag": "..."}, ...]}: every part from 1 to partCount once, in any order, with the ETag its PUT answered, with or without the quotes. A list that skips or repeats a part, or a part without an ETag, is refused with 422 VALIDATION_FAILED on parts.
  • Completing answers 202 with the upload, now verifying.
  • Completing an upload that is already verifying, ready or rejected answers 202 with the upload unchanged. Completing twice is harmless and starts the checks only once.
  • Completing before every part arrived answers 409 CONFLICT with reason PARTS_MISSING and details.partNumbers naming the parts the storage does not hold. The upload stays pending: send them and complete again.
  • Naming an ETag the storage does not hold for that part, or a part of another size than it must have, answers 409 CONFLICT with reason PART_MISMATCH and details.partNumbers. Send those parts again, then complete with the new ETags.
  • If the parts are gone altogether, completing answers 409 CONFLICT with reason OBJECT_MISSING. Start a new upload.
  • Completing a cancelled upload answers 409 CONFLICT with reason NOT_PENDING.
  • Completing is still possible for 5 minutes after expiresAt, for parts that finished just in time. After that it answers 409 CONFLICT with reason EXPIRED.

States

StateMeaningWhat comes next
pendingStarted. Waiting for the parts and for you to complete it.verifying, cancelled or expired
verifyingCompleted. The checks are running.ready or rejected
readyThe checks passed. fileID and versionID name the file and the version it made.Final
rejectedThe checks refused the bytes. rejectReason says why. No file or version was made.Final
expiredIt was never completed.Final
cancelledYou cancelled it while it was pending.Final
  • A pending upload expires 24 hours after it was started: expiresAt. One that is not completed by then becomes expired 5 minutes later. That is room for a 50 GiB file on a connection of about 5 Mbit/s.
  • An upload never stays verifying for good. If the checks cannot be finished, it becomes rejected with the reason INGEST_FAILED.
  • completedAt is set when the upload is completed. finishedAt is set when it reaches a final state.

Verification

After you complete an upload, these checks run in this order. The first that fails rejects the upload with the reason shown.

CheckRejected with
The joined bytes are there.OBJECT_MISSING
The bytes are exactly the declared sizeBytes.SIZE_MISMATCH
The bytes have the declared sha256, when one was declared.DIGEST_MISMATCH
The content is an accepted type.TYPE_NOT_ALLOWED
The content is the type the file name claims.TYPE_MISMATCH
An image, PDF or video opens and is within its limits.MEDIA_INVALID
The scan finds no malware.MALWARE
For a replacement: the file still has the version you based it on.STALE_FILE_VERSION
For a replacement: the file is not in the trash.IN_TRASH

What "opens and is within its limits" means:

  • JPEG, PNG, GIF, WebP, AVIF, SVG, HEIC, HEIF and Photoshop files must decode. They may have at most 100 million pixels and at most 16,384 pixels a side.
  • A PDF must open and may have at most 500 pages.
  • A video must hold a video stream of at most 16,384 pixels a side.
  • A file that cannot be opened within the time and memory the check allows is rejected the same way.
  • A video of any size is read where it is stored, so a 50 GiB video is checked like a small one.
  • ICO files, raw photos, design files, fonts, CSV, Word, Excel, Markdown and text are recognized by their content and not opened further.

Every upload is scanned for malware, whatever its type. A file in which the scan finds something is rejected with MALWARE and never becomes a file.

The scan reads the first 100 MiB of a file. A file up to 100 MiB is scanned whole. Of a larger file, such as a long video, only its first 100 MiB are scanned and the rest is not. This is recorded, never hidden: the version's scannedBytes says how many bytes the scan read (equal to sizeBytes when it read them all), and the file's page lists "Malware scan" with "First 100 MiB" under its properties.

If the scan or another part of verification is temporarily unavailable, the upload waits in verifying and is tried again. If it keeps failing, the upload is rejected with INGEST_FAILED. Uploading the same file again may then pass.

What a new file starts with

  • Its name is fileName, extension included.
  • It sits in the folder named by folderID, or at the top level.
  • If that folder was moved to the trash while the upload was being checked, the file is created at the top level instead.
  • Its status is the organization's default status, when one is set. Otherwise it has no status.
  • It is never public at once. The default status never allows public use, and a file without a status is never public. This holds for an upload into a public folder too: the file appears in the folder, restricted, until an owner or admin gives it a status that allows public use. See Statuses and Sharing and public links.
  • It has version 1, with the size, type and SHA-256 digest of its bytes, which Talewright computes itself for every upload.
  • It has no description, caption, alt text or tags.
  • The person who uploaded it is recorded as its creator.
  • File names need not be unique. Uploading logo.png twice into one folder gives two files named logo.png.

Duplicates

  • Talewright compares files by their bytes, not by their names.
  • An upload carries duplicates: up to 10 other live files in the organization with the same bytes that you can open.
  • While the upload is pending or verifying, the comparison uses the sha256 you declared. Without a declared sha256 there are no duplicates yet.
  • Once the upload is ready, the comparison uses the stored digest. The file the upload made, or the file it replaced, is left out.
  • A rejected, expired or cancelled upload has no duplicates.
  • Only files you can open are named: files of the same workspace or organization folder, files of the organization folder, and files of your other workspaces. A credential sees only the workspaces it lists, and the organization folder.
  • The order is: the upload's own workspace or organization folder first, then the organization folder, then other workspaces. Within each, oldest file first.
  • Each duplicate has id, name, workspaceID (null for the organization folder), fileSpaceName (the workspace's name, or "Library"; the app shows "Organization folder") and folderPath.
  • Trashed files are never named as duplicates.
  • The API never stops an upload for a duplicate: both files exist afterwards. The app asks first, see The "Already in ..." notice.
  • The groups of duplicate files of a workspace or the organization folder can be listed, and each person can hide a group's warning for themselves. See Duplicate groups.

Cancelling

  • Only a pending upload can be cancelled. The answer is 204. The parts sent so far are discarded.
  • Cancelling an upload in any other state answers 409 CONFLICT with reason NOT_PENDING.
  • A cancelled upload can never be completed, even if bytes were sent.
  • A cancelled upload accepts no more parts.
  • An upload that is verifying cannot be stopped. It ends ready or rejected.

Bytes that never became a file

  • Bytes of a pending, rejected, expired or cancelled upload cannot be opened by anyone, through any link.
  • They are deleted once the upload is finished, and the parts of a cancelled or expired upload are discarded.
  • A rejected upload leaves no file, no version and no trace in listings.

Previews

A JPEG, PNG, GIF, WebP or AVIF image of up to 64 MiB (and within 16,384 pixels a side and 100 million pixels) has its thumbnail and preview at once: the image service makes them from the original the first time they are shown, and keeps them. For every other type, a thumbnail and a preview are made from the new version once the upload is ready, so the file is listed a moment before its thumbnail appears.

  • The thumbnail (thumb) is a WebP image that fits 320 pixels.
  • The preview (preview) is a WebP image that fits 1,600 pixels.
  • previewStatus on a file says where this stands:
previewStatusMeaning
pendingBeing made.
readyBoth exist, or the image service makes them when shown. thumbnailURL and previewURL are set.
unsupportedThis type has no preview, or the file embeds none.
failedA preview could not be made from this file.

What the preview shows, by type:

TypePreview
JPEG, PNG, GIF, WebP, AVIF, SVGThe image
HEIC, HEIFThe image
Photoshop (.psd, .psb)The flattened image the file holds
Raw photosThe largest JPEG the file embeds. unsupported when it embeds none
IllustratorPage 1, when the file is PDF-based. unsupported for a PostScript-based file
EPSThe preview image the file embeds. unsupported when it embeds none
InDesignThe thumbnail the file embeds. unsupported when it embeds none
FigmaThe thumbnail the file holds
PDFPage 1
MP4, WebM, QuickTimeOne frame, 10% into the video and at most 3 seconds in
ICO, fonts, CSV, Word, Excel, Markdown, textNone (unsupported)
  • A file with unsupported or failed shows its type icon instead.
  • A video of any size gets its preview. A raw photo, Illustrator, EPS or InDesign file over 2 GiB gets none: its previewStatus is failed.
  • A preview that failed is not tried again by itself.
  • Previews are made per version. A new version gets its own. See Versions and history.
  • Previews are never public. They are served through temporary addresses. See Downloading.

Video playback

Browsers cannot play every video. For a video that browsers may not play, a playback rendition is prepared after the upload is ready.

  • The playback rendition is an MP4 with H.264 video and stereo AAC audio, at most 1,920 by 1,080 pixels (or 1,080 by 1,920 for a portrait video).
  • playbackStatus on a file says what its page plays:
playbackStatusMeaning
originalThe original plays as it is, or the file is not a video.
pendingThe playback rendition is being prepared.
readyThe playback rendition exists.
failedNo playback rendition could be made. The original may still play.

A playback rendition is prepared for:

  • every QuickTime movie (.mov, .qt),
  • an MP4 whose video is not 8-bit 4:2:0 H.264, or whose audio is something other than AAC,
  • a WebM whose video is not VP8, VP9 or AV1, or whose audio is something other than Opus or Vorbis.

A video without sound needs no rendition for that reason alone.

  • Preparing takes at most 30 minutes and yields at most 2 GiB. Past either, playbackStatus is failed. A long, large original, such as an hour of 4K video, can pass 30 minutes; it still downloads and plays where the browser can play it.
  • The rendition is only for playing in the app. Downloads and public links always serve the original file.

In the app

Where you upload

Uploading is offered to everyone in a workspace, and to organization owners and admins in the organization folder. Other members see no upload controls in the organization folder.

  • The "Upload" button at the top of the file browser opens a menu with "Files" and "Folder".
    • "Files" opens your system's file picker for one or more files. The picker suggests the accepted extensions.
    • "Folder" opens your system's folder picker.
  • Right-click on empty space in the browser offers "New folder", "Upload files" and "Upload folder".
  • The command palette offers "Upload files" and "Upload folder" while the file browser is open.
  • Drag and drop. Drag files or folders from your computer onto the browser. While you drag, the browser dims and shows "Drop files to upload" and "to {name}": where the files will land.
    • Dropping on the open area uploads into the folder you have open. At the top level, {name} is the workspace, or the organization folder.
    • Dropping on a folder's row uploads into that folder. While you hold the files over it, the row is highlighted and {name} is that folder.
    • When the folder is public, itself or through a folder above, the message adds "Anyone with the link can open files here once their status allows public use." The upload itself is not public at once. See Public folders.
    • The message does not say whether a file is a duplicate: a browser cannot read files before they are dropped. The tray says so once the upload starts. See The "Already in ..." notice.
    • If a dropped folder cannot be read, the app says "Could not read the dropped folder."

Files go into the folder you have open, or to the top level when no folder is open. An empty folder or an empty top level shows what can be uploaded: "Images, raw photos, design files, PDF, video, fonts, CSV, Word, Excel, Markdown and text up to 50 GiB (images, PDF, Word, Excel and Figma up to 2 GiB)."

Uploading a folder

"Folder" in the Upload menu, "Upload folder", and dropping a folder all work the same way:

  • The folder itself is recreated under the open folder (or the folder you dropped on), with its subfolders, and each file is uploaded into its own folder.
  • If a folder of the same name already exists there, ignoring case, it is reused and filled. Choosing the same folder twice gives one folder with the files uploaded twice.
  • Files at the top of the chosen folder are queued at once. Folders are created a level at a time, parents before children, up to six at once, and each folder's files are queued as soon as that folder exists, so sending starts before the whole tree is made.
  • Only folders that hold at least one file to upload are created. Empty folders are not.
  • Files and folders whose names start with a dot, such as .DS_Store, are skipped without a message. This also applies to single files chosen with "Files" or dropped.
  • If a folder cannot be created, the app says "Could not create {path}. {reason} Nothing in it was uploaded." Everything inside that folder is skipped. The rest of the upload continues. Reasons include "Folders nest at most 16 levels deep." and "Enter a name of 1 to 200 characters without a slash."

The upload tray

The tray "Uploads" appears at the bottom of the window as soon as you upload something. It lists each file, newest first.

Each row shows the file's name and its status:

StatusMeaning
"Waiting"In line. Three files are sent at a time, in the order they were chosen.
"Interrupted. Choose the same file to resume."The page was closed or reloaded while the file was being sent. "Resume" continues it.
"Uploading"Being sent, with a progress bar.
"Verifying"Sent. The checks are running.
"Still verifying. Look for it in its folder later."The checks did not finish within 10 minutes and the tray stopped following the upload. It becomes a file if the checks pass.
"Ready"It is a file now. The name becomes a link, "Open {name}", to the file's page.
"Rejected: {reason}"Refused. The file was not added.
"Failed: {reason}"Something went wrong on the way. "Retry" is offered.
"Cancelled"You cancelled it.
  • The heading shows a summary: "{n} in progress" while anything is waiting, uploading or verifying; "{n} interrupted" while rows wait to be resumed; then "All done" when every row is ready, "{ready} of {total} ready" when some are or a row is still verifying, or "None uploaded" when none is.
  • A replacement's row also says "Replacing {name}".
  • "Cancel" is offered on rows that are waiting, uploading or interrupted.
  • "Resume" is offered on interrupted rows.
  • "Retry" is offered on every "Failed" row, and on a row that reads "Rejected: Could not be checked".
  • A verifying row and a finished row have a button "Dismiss {name}" that removes the row.
  • "Clear finished" removes every ready, rejected, failed and cancelled row. Interrupted rows stay until resumed or cancelled.
  • "Collapse uploads" folds the tray down to its heading. "Expand uploads" opens it again.
  • The tray floats over the bottom of the window. While it is open, the file browser leaves that much room below its last rows, so they scroll clear of the tray.
  • Dismissing a row that is "Verifying" only removes the row. The checks go on, and the file appears in its folder when they pass.
  • The tray follows a "Verifying" row for 10 minutes, and a minute longer for each GiB of the file: a large file takes longer to check. Then the row reads "Still verifying. Look for it in its folder later." and the tray stops asking about it.
  • A file is sent in parts of 16 MiB. Four parts are on their way at a time, shared by the files being sent. The progress bar counts the parts stored and the bytes of those on their way.

The app never checks size or type itself. Every file is offered to the server, which answers at once for a file that is too large or of the wrong type. No bytes are sent for those.

The Uploads page

"Uploads" in the Files & Assets navigation, below "Trash", opens a table of the same uploads as the tray, for a batch too long to follow there.

  • Its link counts the uploads still waiting, uploading or verifying.
  • Each row shows the file's name (a link once it is ready), where it goes (the workspace or "Organization folder", then the folder it sat in when a folder was chosen), and its status: progress while it uploads, the reason in red when it was refused or failed.
  • Each row offers what the tray's row offers: "Resume", "Cancel", "Retry" and "Dismiss".
  • "Resume all" and "Clear finished" sit at the top of the page.
  • The tray stays hidden while the page is open.
  • Like the tray, it lists the uploads of this browser only: a retry needs the file on this computer. With none, it says "No uploads in this browser."

Reasons shown on a row

Refused when the upload starts or completes:

TextWhen
"Rejected: Larger than the 50 GiB limit"The file is over the size limit.
"Rejected: Larger than the 2 GiB limit"An image, PDF, Word, Excel or Figma file is over its size limit.
"Rejected: This type of file cannot be uploaded"The extension is not accepted, or the browser reports a type that does not match it.
"Rejected: The file name is not allowed"The name is longer than 200 characters or otherwise breaks the naming rule.
"Rejected: The file is empty"The file has no bytes.
"Rejected: The folder no longer exists"The destination folder was trashed or deleted.
"Rejected: The file or folder no longer exists"The workspace, the file being replaced or the folder is gone.
"Rejected: Only organization owners and admins can change the organization folder."The upload was refused in the organization folder.
"Rejected: You cannot upload here"The upload was refused in a workspace.
"Rejected: Someone replaced this file first"A replacement was based on a version that is no longer current.
"Rejected: Replace it with a PNG file" (or the file's own type, such as "a Markdown file" or "a text file")A replacement is of another type than the file.
"Rejected: The file is in the trash"The file being replaced is in the trash.
"Rejected: You were signed out"Your session ended.
"Failed: Uploads are paused. Try again later"Uploads are paused for everyone.
"Failed: The upload expired"The upload was not completed within 24 hours.
"Failed: The file never arrived"The upload was completed, but its parts were gone.
"Failed: Some parts did not arrive"Completing found parts missing or different. "Retry" sends them again.
"Failed: Storage refused the file"The storage did not accept a part.
"Failed: Storage did not confirm a part"The storage stored a part without confirming it to the browser.
"Failed: Connection lost"A part could not be sent, five tries in a row.
"Failed: The upload could not continue"Another conflict.
"Failed: The server had a problem"An unexpected failure.

Refused by verification:

TextrejectReason
"Rejected: Contains malware"MALWARE
"Rejected: Contents are not an allowed file type"TYPE_NOT_ALLOWED
"Rejected: Contents do not match the file extension"TYPE_MISMATCH
"Rejected: Could not be opened, or too large to process"MEDIA_INVALID
"Rejected: Changed while uploading"SIZE_MISMATCH or DIGEST_MISMATCH
"Rejected: The file never arrived"OBJECT_MISSING
"Rejected: Someone replaced this file first"STALE_FILE_VERSION
"Rejected: The file is in the trash"IN_TRASH
"Rejected: Could not be checked" (with "Retry")INGEST_FAILED

The "Already in ..." notice

  • Before sending a file of up to 256 MiB, the app computes its SHA-256 and declares it. If the same bytes already exist somewhere you can open, the row reads "Already exists" with "Already in {place} as {name}", a link to that file, and nothing is sent yet.
  • The row offers "Skip" and "Keep both". "Skip" cancels the upload and the row reads "Skipped". "Keep both" sends the file, which ends up beside the other one.
  • With two or more rows waiting on that answer, the tray and the Uploads page show "{n} already exist" with "Skip all" and "Keep all", which answer every one of them.
  • A waiting row does not hold up the others: the next files start sending.
  • Rows waiting on an answer are listed first, in the tray and on the Uploads page, so a long upload never buries one.
  • While rows wait, the tray's header turns to the warning color and its summary reads "1 needs a choice" or "{n} need a choice".
  • A new question opens a collapsed tray and scrolls its list to the top. Collapsed again, the tray keeps "Skip all" and "Keep all" in view.
  • Replacing a file, and resuming an upload, never ask.
  • Reloading the page while a row waits on an answer leaves it "Interrupted"; choosing the file again sends it without asking.
  • {place} is the other file's folder, or its workspace's name, or "Organization folder".
  • The notice names the first duplicate only.
  • Files larger than 256 MiB, or files chosen in a browser that cannot compute SHA-256, are sent without the early check and without asking: reading a very large file twice would cost too long. The notice can still appear once the upload is ready, from the digest Talewright computes itself; move the copy to the trash if you do not need it.
  • The notice is not shown on rows that were rejected, failed, cancelled or skipped.
  • On the file's page, a notice marked "Duplicate" under the file's name reads "Same file as {name} in {place}" for each duplicate, with a link to it.
  • "Hide" on that notice hides it for you alone, until a new copy appears. See The duplicate notice on a file's page.
  • To find duplicates later, use Filter > "Show" > "Duplicates". See Folders, moving and finding.

Cancel and retry

  • "Cancel" on a waiting row stops it before anything is sent.
  • "Cancel" on an uploading row stops the transfer and cancels the upload. The row reads "Cancelled" and no file is made.
  • If you cancel at the very moment the upload was completed, the row returns to "Verifying" and may still end "Ready". An upload that is being verified cannot be stopped.
  • A part that fails to send is tried again by itself after 1, 2, 4 and 8 seconds. A part whose address expired gets a new one. Only when the fifth try fails does the row read "Failed: Connection lost".
  • "Retry" on a failed row continues the same upload: the app asks which parts are stored and sends only the others. If the upload expired meanwhile, a new one starts. After "Failed: Some parts did not arrive" because the storage holds other bytes for a part, a new upload starts.
  • When the connection comes back, rows that read "Failed: Connection lost" resume by themselves.
  • A rejected file is not offered "Retry", except for "Could not be checked": trying the same bytes again would be refused again. That retry starts a new upload.

Uploads and navigation

  • The tray stays while you move around the app. You can open other pages, other folders and other tabs inside the app, and the uploads continue.
  • Reloading the page or closing the browser tab stops files that are still being sent. Files that already reached "Verifying" are safe: they finish on the server and appear in the folder.
  • When you come back in the same browser, each file that was being sent or still waiting is back in the tray as "Interrupted. Choose the same file to resume." The browser cannot reopen a file by itself, so "Resume" asks you to choose it again. The app checks the name and size: another file is refused and the row reads "Choose {name} ({size}) to resume it." The app also compares the chosen file with the parts already sent (by their SHA-256, remembered as each part was stored): the same file continues where it stopped, sending only the parts not yet stored, while a file of that name and size that changed since starts a new upload and the old one is cancelled, so a file never mixes old and new bytes.
  • "Resume all", in the tray's header while any row is interrupted, picks a folder and resumes every interrupted row whose file is in it, matched by its path in the folder that was uploaded and its size. Choose the same folder you uploaded: rows whose file is not found, or whose size changed, stay interrupted. This is how a large folder continues after a reload.
  • An interrupted upload can be resumed until it expires, 24 hours after it started. Resuming it later starts a new upload of the same file.
  • The app remembers interrupted and waiting uploads in this browser only, and only for the account that started them. It keeps their names, paths, sizes and destinations, never their bytes. A file that never started sending was not opened on the server, so it has nothing to expire.
  • While a row is "Waiting" or "Uploading", reloading or closing the tab makes the browser ask whether to leave. Rows that are "Verifying" or "Interrupted" do not make it ask: nothing is being sent, and an interrupted row comes back after the reload.
  • Thumbnails and previews start loading when they come near the screen, six at a time, so a folder of hundreds of new images stays quick. One the image service is still busy with is asked for again after 1, 3 and 8 seconds before the file's type icon shows.
  • Signing out ends running transfers and empties the tray.
  • If you lose access to a workspace while uploading into it, its rows disappear from the tray.
  • When a file becomes ready, the folder listing updates by itself.

Previews in the app

  • In the grid and in the list, a file shows its thumbnail once it is ready. Until then, and for types without a preview, it shows its type icon.
  • On a file's page, the preview is the image "Preview of {name}". A photo or a video fills the width of the page, never larger than the original and never taller than most of the window. Any other preview, such as a PDF's first page, keeps a fixed height.
  • While the preview is being made, the page says "Preparing preview".
  • For a type without a preview, or when it failed, the page says "Preview unavailable".
  • A PDF shows its first page. A CSV shows "Preview unavailable".
  • The page checks again every 3 seconds while a preview is being made.

Video in the app

  • A video's page has a player with the video's preview frame as its poster.
  • While the playback rendition is being prepared, the page says "Preparing video".
  • While the player fetches its address, it says "Loading video".
  • The player plays the playback rendition once it is ready. Otherwise it plays the original.
  • If playing fails, the player fetches a fresh address once and continues where it stopped.
  • If it fails again, the page says "This video cannot play here. Download it instead."

For agents

Operations

OperationCapability IDMCP toolScope
POST W/uploadsworkspace.uploads.createworkspace_uploads_createfiles:write
GET W/uploadsworkspace.uploads.listworkspace_uploads_listfiles:read
GET W/uploads/{uploadID}workspace.uploads.getworkspace_uploads_getfiles:read
POST W/uploads/{uploadID}/part-urlsworkspace.uploads.sign_partsworkspace_uploads_sign_partsfiles:write
GET W/uploads/{uploadID}/partsworkspace.uploads.list_partsworkspace_uploads_list_partsfiles:read
POST W/uploads/{uploadID}/completeworkspace.uploads.completeworkspace_uploads_completefiles:write
DELETE W/uploads/{uploadID}workspace.uploads.cancelworkspace_uploads_cancelfiles:write
POST L/uploadslibrary.uploads.createlibrary_uploads_createfiles:write
GET L/uploadslibrary.uploads.listlibrary_uploads_listfiles:read
GET L/uploads/{uploadID}library.uploads.getlibrary_uploads_getfiles:read
POST L/uploads/{uploadID}/part-urlslibrary.uploads.sign_partslibrary_uploads_sign_partsfiles:write
GET L/uploads/{uploadID}/partslibrary.uploads.list_partslibrary_uploads_list_partsfiles:read
POST L/uploads/{uploadID}/completelibrary.uploads.completelibrary_uploads_completefiles:write
DELETE L/uploads/{uploadID}library.uploads.cancellibrary_uploads_cancelfiles:write
  • GET .../uploads lists your own uploads, newest first, 50 a page (1 to 100 with limit). active=true keeps those that are pending or verifying. Use it to find your uploads again after a restart.
  • The bytes never go through the API or MCP. Each part goes straight to its address with an ordinary HTTP PUT.
  • The tools' arguments are listed in MCP.

What an upload holds

PropertyMeaning
idThe upload's ID.
statepending, verifying, ready, rejected, expired or cancelled.
fileName, sizeBytesAs declared.
contentTypeThe type the extension names.
sha256sha256:<hex> when declared, else null.
folderIDThe destination folder, or null.
targetFileID, baseVersionIDSet for a replacement, else null.
partSizeBytesThe size of every part but the last.
partCountHow many parts the file is sent in, at most 10,000.
partURLsThe addresses of the first 100 parts, answered when the upload starts. null when you read it later.
expiresAtWhen a pending upload expires unless completed.
rejectReasonWhy it was rejected, else null.
fileID, versionIDThe file and the version it made, once ready. Otherwise null.
duplicatesUp to 10 other live files with the same bytes.
createdAt, completedAt, finishedAtWhen it was started, completed and finished.

Worked example

Start the upload:

curl -s -X POST "$TALEWRIGHT/v1/workspaces/$WORKSPACE/uploads" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "press-photo.jpg",
    "sizeBytes": 482113,
    "contentType": "image/jpeg",
    "folderID": "0192f0a1-6f2d-7a40-8a13-9b1c4d2e6f77",
    "requestID": "press-photo-2026-11-14-a"
  }'
{
  "id": "0192f0d4-2c10-7e55-9a01-7f3b2c1d4e56",
  "state": "pending",
  "fileName": "press-photo.jpg",
  "sizeBytes": 482113,
  "contentType": "image/jpeg",
  "sha256": null,
  "folderID": "0192f0a1-6f2d-7a40-8a13-9b1c4d2e6f77",
  "targetFileID": null,
  "baseVersionID": null,
  "rejectReason": null,
  "fileID": null,
  "versionID": null,
  "partSizeBytes": 16777216,
  "partCount": 1,
  "partURLs": [
    {
      "partNumber": 1,
      "sizeBytes": 482113,
      "url": "https://...",
      "expiresAt": "2026-11-14T10:15:00Z"
    }
  ],
  "expiresAt": "2026-11-15T10:00:00Z",
  "createdAt": "2026-11-14T10:00:00Z",
  "completedAt": null,
  "finishedAt": null,
  "duplicates": []
}

The file is one part. Send it to the part's url and keep the ETag the answer carries. Send no Authorization header: the address is the permission.

curl -s -X PUT "$PART_URL" --data-binary @press-photo.jpg \
  -D - -o /dev/null | grep -i '^etag'
etag: "9b2cf535f27731c974343645a3985328"

Complete it, naming the part with its ETag:

curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE/uploads/$UPLOAD/complete" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts": [{"partNumber": 1, "etag": "9b2cf535f27731c974343645a3985328"}]}'

A larger file is sent the same way, part by part. With partSizeBytes of 16 MiB, part n is the bytes from (n - 1) × 16 MiB, for example with dd if=film.mov bs=16M skip=$((n - 1)) count=1. Ask for the addresses of parts past the first 100 with POST .../uploads/{uploadID}/part-urls and {"partNumbers": [101, 102, ...]}. If you lost the ETags, GET .../uploads/{uploadID}/parts lists them.

Then read it until state is ready or rejected:

curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/uploads/$UPLOAD" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
  • When ready, fileID and versionID name the new file and its version.
  • When rejected, rejectReason says why. Nothing was added.
  • Wait a little longer between reads each time.
  • If the complete call times out, send it again.
  • If a part's address stopped working before you sent the part, ask for a new one with part-urls. Past expiresAt, start a new upload.
  • The same steps over MCP are shown in MCP.

Edge cases

SituationWhat happensWhy
The file is named Photo.JPGIt is accepted as a JPEG.Extensions are compared without regard to case.
The file has no extension, such as README415 UNSUPPORTED_MEDIA_TYPE.The extension decides the type, and there is none.
The name has two extensions, such as logo.svg.pngIt is treated as a PNG.Only the last extension counts.
fileName is folder/logo.png422 VALIDATION_FAILED on fileName.A name must not contain a path. Put the file in a folder with folderID.
fileName ends in a line break422 VALIDATION_FAILED on fileName.Control characters are refused, also at the very end.
fileName is 201 characters long422 VALIDATION_FAILED on fileName.Names are 1 to 200 characters.
sizeBytes is 0422 VALIDATION_FAILED on sizeBytes. The app shows "Rejected: The file is empty".An empty file cannot be uploaded.
A 3 GiB PNG is uploaded413 PAYLOAD_TOO_LARGE with details.limitBytes 2,147,483,648. No bytes are sent.Images are opened whole to be checked, so they are limited to 2 GiB.
A 40 GiB QuickTime movie is uploadedIt is accepted. It is sent in 2,560 parts of 16 MiB.Videos go up to 50 GiB.
A 51 GiB video is uploaded413 PAYLOAD_TOO_LARGE with details.limitBytes 53,687,091,200. No bytes are sent.The size is checked at the start.
A 51 GiB .exe is uploaded413 PAYLOAD_TOO_LARGE, not 415.The size is checked before the type.
A 3 GiB .exe is uploaded415 UNSUPPORTED_MEDIA_TYPE.Within 50 GiB, the type decides.
page.png is declared with contentType: text/html415 UNSUPPORTED_MEDIA_TYPE.The declared type does not match the extension.
A .csv is declared as application/vnd.ms-excelIt is accepted.Some systems label CSV files as Excel documents.
contentType is image/png; charset=binaryIt is accepted for a .png.Only the part before ; counts.
A PNG is named photo.jpgThe upload is rejected with TYPE_MISMATCH.The bytes are another accepted type than the name claims.
An HTML page is named banner.pngThe upload is rejected with TYPE_NOT_ALLOWED.The bytes are no accepted type.
A ZIP archive is renamed to report.docxThe upload is rejected with TYPE_NOT_ALLOWED.A container that is not a Word, Excel or Figma file is not accepted.
A Figma file is named design.docxThe upload is rejected with TYPE_MISMATCH.Its content is Figma, another accepted type.
A plain TIFF is renamed to scan.dngThe upload is rejected with TYPE_NOT_ALLOWED.Only real raw photos are accepted among TIFF-based files.
A CSV in an older encoding with accented letters is uploaded as .csvThe upload is rejected with TYPE_NOT_ALLOWED.CSV files must be UTF-8 text. Save it as UTF-8, or upload it as .txt.
A text file that looks like a table is uploaded as notes.txtIt is accepted as plain text.Any text passes as .txt or .md.
An SVG is uploaded as icon.txtIt is accepted as plain text.It reads as text. It is stored and served as text, not as an image.
A JPEG is renamed to notes.txtThe upload is rejected with TYPE_MISMATCH.The bytes are an image, not text.
A file with random binary content is named data.mdThe upload is rejected with TYPE_NOT_ALLOWED.It does not read as text.
An image has 20,000 pixels on one sideThe upload is rejected with MEDIA_INVALID.Images may have at most 16,384 pixels a side.
A PDF has 600 pagesThe upload is rejected with MEDIA_INVALID.PDFs may have at most 500 pages.
A truncated or damaged image is uploadedThe upload is rejected with MEDIA_INVALID.It does not decode.
A .mp4 holds only soundThe upload is rejected, with MEDIA_INVALID or TYPE_NOT_ALLOWED depending on how the file is built.A video must hold a video stream.
The file holds malwareThe upload is rejected with MALWARE. The bytes are never stored as a file.Every upload is scanned.
You declare a sha256 and send other bytesThe upload is rejected with DIGEST_MISMATCH.The declared digest is a promise about the bytes.
sha256 is 63 digits long422 VALIDATION_FAILED on sha256 at the start.It must be 64 hexadecimal digits.
You PUT fewer or more bytes than a part's sizeBytesThe storage refuses the PUT with 403.Each address accepts exactly its part's length.
You send the parts in the order 3, 1, 2It works.Parts are joined by number.
You complete before sending every part409 CONFLICT, reason PARTS_MISSING, with details.partNumbers naming the missing ones. The upload stays pending.There is nothing whole to check yet.
You complete with part 2's ETag given for part 3409 CONFLICT, reason PART_MISMATCH, with details.partNumbers: [3].The storage holds other bytes for part 3 than you named.
You complete naming parts 1 and 3 of three422 VALIDATION_FAILED on parts.Every part is named once.
You send a part twiceThe second replaces the first. Name the ETag of the second.The storage keeps the last bytes per part.
Your connection drops half way through a 20 GiB fileList the stored parts, send the others, complete. In the app, the parts are tried again, and "Retry" or the connection coming back resumes the upload.Parts already stored are kept until the upload expires.
You reload the page while a file is being sentThe tray shows it "Interrupted. Choose the same file to resume." Choosing the same file sends only the missing parts.The browser cannot reopen a file without you.
You choose another file to resumeThe row reads "Choose {name} ({size}) to resume it." Nothing is sent.The name and size must match.
You choose a file of the same name and size that changed since the parts were sentA new upload starts with every part; the interrupted one is cancelled.Stored parts are reused only while the file holds the same bytes.
You complete the same upload twiceBoth answer 202. The checks run once.Completing again changes nothing.
You complete 24 hours and 3 minutes after starting, having sent the parts in timeIt works.Completing is possible for 5 minutes after expiresAt.
You complete 25 hours after starting409 CONFLICT, reason EXPIRED.The upload expired. Start a new one.
You never completeThe upload becomes expired 24 hours and 5 minutes after it was started, and its parts are discarded.A pending upload does not wait forever.
You PUT a part more than 15 minutes after its address was madeThe storage refuses with 403. Ask for a new address with part-urls.An address lives 15 minutes.
You cancel, then completeComplete answers 409 CONFLICT, reason NOT_PENDING.A cancelled upload can never be completed.
You cancel twiceThe second answers 409 CONFLICT, reason NOT_PENDING.Only a pending upload can be cancelled.
You cancel a ready or rejected upload409 CONFLICT, reason NOT_PENDING. The file, if any, stays.To remove the file, move it to the trash.
Another member asks for your upload by its ID404 NOT_FOUND, for reading, part addresses, listing parts, completing and cancelling alike.An upload belongs to whoever started it.
A 2 GiB video is uploadedIt is scanned for its first 100 MiB. The version's scannedBytes is 104,857,600 and its page says "Malware scan" "First 100 MiB".The scan reads at most 100 MiB of a file.
A member starts an upload in the organization folder403 FORBIDDEN. In the app there is no upload control for them.Only owners and admins change the organization folder.
A credential without files:write starts an upload403 FORBIDDEN, reason INSUFFICIENT_SCOPE.Starting needs files:write.
folderID names a folder of another workspace422 VALIDATION_FAILED on folderID, the same as for an unknown ID.A file goes into a folder of its own workspace or organization folder.
folderID names a folder in the trash422 VALIDATION_FAILED on folderID.The folder must be live.
The folder is trashed while the upload is being checkedThe file is created at the top level.A new file is never placed in a trashed folder.
The same request is repeated with the same requestIDThe upload from the first request is returned. No second upload is made.Safe retries.
The same requestID is sent with another body409 CONFLICT, reason REQUEST_REUSED.A requestID names one request.
A requestID used to start an upload in a workspace is used to start one in the organization folder201 with a new upload.Starting an upload in a workspace and in the organization folder are two operations, and each keeps its own request IDs.
The same bytes are uploaded twice through the APITwo files exist. Each names the other in duplicates.The API reports duplicates; it does not prevent them.
The same bytes are chosen again in the appThe row waits as "Already exists" with "Skip" and "Keep both".Nothing is sent until you answer.
The same bytes exist in a workspace you cannot openThey are not named as a duplicate.Duplicates only name files you can open.
A file is uploaded into a public folderIt is created restricted, with the default status or none. It is not listed in the folder's public gallery.An upload is never public at once.
The organization has no default statusNew files have no status.The default status is optional.
A raw photo embeds no JPEGThe file is accepted. previewStatus is unsupported.The preview of a raw photo is the image it embeds.
A damaged Photoshop file passes the checks but cannot be renderedThe file exists. previewStatus is failed.Previews are made after the file exists and do not decide whether it is accepted.
A QuickTime movie is uploadedIt is accepted. Its page says "Preparing video" until the playback rendition is ready.Browsers may not play QuickTime originals.
An MP4 with H.264 and AAC is uploadedplaybackStatus is original. It plays as it is.No rendition is needed.
An MP4 with HEVC video is uploadedA playback rendition is prepared.Not every browser plays it.
Verification cannot finishThe upload becomes rejected with INGEST_FAILED. The app shows "Rejected: Could not be checked" with "Retry".An upload never stays verifying for good.
You reload the page during "Uploading"The browser asks whether to leave. If you leave, sending stops and the row comes back as "Interrupted. Choose the same file to resume."Transfers run in the page; the parts already stored are kept.
A row is still "Verifying" after 10 minutesIt reads "Still verifying. Look for it in its folder later." with "Dismiss". No "Retry" is offered.The upload is not refused: it becomes a file if the checks pass, and a retry would add it twice.
You dismiss a row that is "Verifying"The row is gone. The file appears in its folder when the checks pass.Verification runs on the server.
You reload the page during "Verifying"The tray is empty, but the file appears in its folder when the checks pass.Verification runs on the server.
You drop the same folder twiceOne folder, with every file in it twice.The existing folder is reused; files are never merged by name.
A dropped folder holds .DS_StoreIt is skipped.Names that start with a dot are not uploaded from the app.
Uploads are paused503 UNAVAILABLE, reason UPLOADS_DISABLED. The app shows "Failed: Uploads are paused. Try again later".New uploads are refused for the time being. Existing files are unaffected.
The workspace is deleted while an upload is being checkedThe checks finish. The file is there if the workspace is restored.See Workspaces.

Errors

Answers to the upload operations:

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid credential.Sign in or use a valid credential.
FORBIDDEN403Starting, completing or cancelling in the organization folder without being an owner or admin.Ask an owner or admin, or upload into a workspace.
FORBIDDEN, reason INSUFFICIENT_SCOPE403The credential lacks files:write (or files:read for reading).Use a credential with the scope.
NOT_FOUND404The workspace or organization is unknown or out of reach; the upload is unknown or someone else's; a replacement's targetFileID is unknown.Check the IDs.
STALE_FILE_VERSION409A replacement's baseVersionID is no longer the file's current version. details.currentVersionID names the current one.Read the file again and start over.
CONFLICT, reason IN_TRASH409A replacement's file is in the trash.Restore the file first.
CONFLICT, reason DIFFERENT_TYPE409A replacement is of another type than the file's current version.Use a file of the same type, or upload it as a new file.
CONFLICT, reason PARTS_MISSING409Completing before every part arrived. details.partNumbers names the missing parts. Message: "Some parts were never uploaded; send them, then complete again".Send those parts, then complete again.
CONFLICT, reason PART_MISMATCH409Completing with an ETag or size the storage does not hold for a part. details.partNumbers names them. Message: "The store holds other bytes for some parts; send them again".Send those parts again and complete with the new ETags.
CONFLICT, reason OBJECT_MISSING409Completing when the parts are gone. Message: "The upload's parts are gone; start a new upload".Start a new upload.
CONFLICT, reason EXPIRED409Completing, listing parts or asking for addresses after the upload expired. Message: "The upload expired; start a new one".Start a new upload.
CONFLICT, reason NOT_PENDING409Cancelling an upload that is not pending, completing a cancelled one, or listing parts or asking for addresses once it is completed or cancelled.Start a new upload if you still need one.
CONFLICT, reason REQUEST_REUSED409A requestID repeated with another body.Use a new requestID.
PAYLOAD_TOO_LARGE413sizeBytes is over the limit: 50 GiB, or 2 GiB for an image, PDF, Word, Excel or Figma file. details.limitBytes holds it.Upload a smaller file.
UNSUPPORTED_MEDIA_TYPE415The extension is not accepted, or contentType does not match it.See Accepted types.
VALIDATION_FAILED422fileName, sizeBytes, sha256 or folderID breaks its rule; folderID with a replacement; only one of targetFileID and baseVersionID; partNumbers empty, over 100 or out of range; parts that skip or repeat a part; an invalid active, cursor or limit when listing. details.field names the field.Correct the field.
RATE_LIMITED429A credential passed its request limit.Wait for Retry-After seconds.
UNAVAILABLE, reason UPLOADS_DISABLED503Uploads are paused.Try again later.

An upload that fails verification is not an HTTP error. Its state becomes rejected and rejectReason is one of:

rejectReasonMeaningWhat to do
OBJECT_MISSINGNo joined bytes were found.Start again and send the parts.
SIZE_MISMATCHThe joined bytes are not the declared size. This cannot happen when every part was accepted.Declare the exact size.
DIGEST_MISMATCHThe bytes do not have the declared sha256.Declare the right digest, or none.
TYPE_NOT_ALLOWEDThe content is no accepted type.See Accepted types.
TYPE_MISMATCHThe content is another accepted type than the name claims.Give the file its real extension.
MEDIA_INVALIDThe image, PDF or video does not open, or is over its limits.Export the file again, or make it smaller.
MALWAREThe scan found malware.Do not upload the file.
STALE_FILE_VERSIONThe file being replaced got a newer version meanwhile.Start again from the current version.
IN_TRASHThe file being replaced was trashed meanwhile.Restore it, then start again.
INGEST_FAILEDVerification could not be finished.Upload again.

The shape of every error is in Errors.

Limits

WhatValue
Size of one file1 byte to 50 GiB (53,687,091,200 bytes)
Size of an image, PDF, Word, Excel or Figma fileAt most 2 GiB (2,147,483,648 bytes)
Part size16 MiB, larger only past 156 GiB; the last part holds the rest
Parts of one uploadAt most 10,000
Part addresses answered at onceUp to 100
File name1 to 200 characters, no control characters, no / or \
Accepted types35 types, 42 extensions
Part addressValid for 15 minutes, or until the upload expires
Time to complete (expiresAt)24 hours after the start, plus 5 minutes
A pending upload expires24 hours and 5 minutes after it was started
Malware scanThe first 100 MiB of a file
Versions made by one uploadAt most 1
Image size (JPEG, PNG, GIF, WebP, AVIF, SVG, HEIC, HEIF, Photoshop)At most 100 million pixels and 16,384 pixels a side
PDF pagesAt most 500
Video frame sizeAt most 16,384 pixels a side
sha25664 hexadecimal digits, with or without sha256:
Duplicates named on an uploadUp to 10
Files sent at once by the app3
Parts sent at once by the app4, across the files being sent
Tries per part in the app5, after waits of 1, 2, 4 and 8 seconds
Time the tray follows a "Verifying" row10 minutes, plus a minute per GiB
File size up to which the app computes the SHA-256 first256 MiB
ThumbnailWebP that fits 320 pixels
PreviewWebP that fits 1,600 pixels
Playback renditionMP4, at most 1,920 by 1,080 (or 1,080 by 1,920)
Preparing a playback renditionAt most 30 minutes and 2 GiB
Page size when listing uploads1 to 100, default 50
requestID is remembered24 hours

See Limits for every limit in one place.

Questions and answers

Which files can I upload? Images, raw photos, design files, PDF, video, fonts, CSV, Word, Excel, Markdown and text. The full list of 42 extensions is under Accepted types.

How large can a file be? 50 GiB, which is 53,687,091,200 bytes, on every plan. Images, PDFs, Word, Excel and Figma files are at most 2 GiB.

What if my upload stops half way? It resumes. In the app, a failed part is tried again and "Retry" continues from the parts already stored; after a reload, choose the same file again. Through the API, list the stored parts and send the rest.

Can I upload a ZIP file? No. Archives are not accepted. Upload the files themselves, or upload a folder: the app recreates its structure.

Can I upload a whole folder? Yes. Choose "Upload" > "Folder", or drag the folder onto the browser. Its subfolders are recreated and each file lands in its own folder.

Why was my file rejected although it has the right extension? The content is checked too. A file whose content is not what its name claims is rejected. Give the file its real extension.

My file says "Contents do not match the file extension". What now? The file is of another type than its name says, for example a PNG named .jpg. Rename it with the right extension and upload it again.

My file says "Could not be opened, or too large to process". What now? The image, PDF or video is damaged, or it is over a limit: 16,384 pixels a side, 100 million pixels, or 500 pages for a PDF. Export it again or make it smaller.

My file says "Could not be checked". Is something wrong with it? Not necessarily. The checks could not be finished. Choose "Retry".

Are uploads scanned for viruses? Yes, every one. A file in which the scan finds malware is rejected and never becomes a file. The scan reads the first 100 MiB of each file; for a larger file the version's scannedBytes and its page say how much was scanned.

Does Talewright change my files? No. The bytes are stored exactly as sent. Thumbnails, previews and playback renditions are made beside the original, never instead of it.

Is a new upload public? Never at once, not even in a public folder. It starts with the organization's default status, which does not allow public use, or with no status. An owner or admin decides what becomes public.

What happens if I upload a file that is already there? The tray asks first: "Already in {place} as {name}", with "Skip" and "Keep both". Files over 256 MiB are not checked before sending, so you get a second file and the notice afterwards.

What happens if I upload a file with the same name as another? Both files exist. Names need not be unique. To put new bytes into an existing file, use "Replace file" on its page. See Versions and history.

Can I close the tab while files upload? It stops them while they read "Waiting" or "Uploading", and the browser asks before it leaves. When you come back, choose the same file again to resume it. Once they read "Verifying" they are safe.

Can I keep working while files upload? Yes. Move around the app freely. The tray follows you.

Can I cancel an upload? Yes, while it reads "Waiting" or "Uploading". Once it reads "Verifying" it finishes by itself. If you did not want the file, move it to the trash.

Why can't I upload into the organization folder? Only organization owners and admins change the organization folder. Everyone else reads it.

Why is there no thumbnail? The thumbnail is made a moment after the file appears. Some types have none: fonts, CSV, Word, Excel, Markdown, text and ICO. Raw photos and design files have one only when the file embeds a preview.

Why does my video say "Preparing video"? Its format is one that browsers may not play, so a playable copy is being made. The original is kept and is what downloads.

How does an agent upload a file? Start the upload, PUT each part to its address, complete it with the parts' ETags, and read it until it is ready. See Worked example.

How long does an agent have to send the bytes? 24 hours for the whole upload. Each part's address lives 15 minutes; ask for a new one with part-urls when it expires.

Can someone else finish my upload? No. Only the person who started an upload can read, complete or cancel it.

Where do rejected files go? Nowhere. Their bytes cannot be opened and are deleted.