# 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](versions.md).

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

| Action | In a workspace | In the organization folder | Session | Credential (scope) |
| --- | --- | --- | --- | --- |
| Start an upload (new file or replacement) | Every member of the workspace | Organization owners and admins | Yes | Yes (`files:write`) |
| Get addresses for parts of your upload | Every member of the workspace | Organization owners and admins | Yes | Yes (`files:write`) |
| List the parts of your upload already stored | Whoever started it | Whoever started it | Yes | Yes (`files:read`) |
| Complete your upload | Every member of the workspace | Organization owners and admins | Yes | Yes (`files:write`) |
| Cancel your upload | Every member of the workspace | Organization owners and admins | Yes | Yes (`files:write`) |
| Read one of your uploads | Whoever started it | Whoever started it | Yes | Yes (`files:read`) |
| List your uploads | Everyone, for their own | Everyone, for their own | Yes | Yes (`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](../reference/permissions.md#uploads-in-a-workspace).

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

| Field | Rule |
| --- | --- |
| `fileName` | Required. 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. |
| `sizeBytes` | Required. 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. |
| `contentType` | Required. The type of the file, or an empty string, or `application/octet-stream` to go by the extension alone. |
| `folderID` | Optional. A live folder of the same workspace or organization folder. Left out, the file goes to the top level. Not allowed with a replacement. |
| `sha256` | Optional. The SHA-256 of the bytes as 64 hexadecimal digits, with or without the prefix `sha256:`. If given, other bytes are rejected. |
| `targetFileID` and `baseVersionID` | Optional, always together. They make the upload a replacement. See [Versions and history](versions.md). |
| `requestID` | Optional 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](../agents/rest-api.md#safe-retries-with-requestid). |

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

| Group | Type | Extensions | Stored as (`mime`) |
| --- | --- | --- | --- |
| Images | JPEG | `.jpg`, `.jpeg` | `image/jpeg` |
| Images | PNG | `.png` | `image/png` |
| Images | GIF | `.gif` | `image/gif` |
| Images | WebP | `.webp` | `image/webp` |
| Images | AVIF | `.avif` | `image/avif` |
| Images | SVG | `.svg` | `image/svg+xml` |
| Images | ICO | `.ico` | `image/x-icon` |
| Images | HEIC | `.heic` | `image/heic` |
| Images | HEIF | `.heif`, `.hif` | `image/heif` |
| Images | Photoshop | `.psd`, `.psb` | `image/vnd.adobe.photoshop` |
| Raw photos | Adobe DNG | `.dng` | `image/x-adobe-dng` |
| Raw photos | Canon | `.cr2`, `.cr3` | `image/x-canon-cr2`, `image/x-canon-cr3` |
| Raw photos | Nikon | `.nef` | `image/x-nikon-nef` |
| Raw photos | Sony | `.arw` | `image/x-sony-arw` |
| Raw photos | Fujifilm | `.raf` | `image/x-fuji-raf` |
| Raw photos | Olympus | `.orf` | `image/x-olympus-orf` |
| Raw photos | Panasonic | `.rw2` | `image/x-panasonic-rw2` |
| Design files | Illustrator | `.ai` | `application/illustrator` |
| Design files | EPS | `.eps`, `.epsf` | `application/postscript` |
| Design files | InDesign | `.indd` | `application/x-indesign` |
| Design files | Figma | `.fig` | `application/x-figma` |
| Fonts | WOFF | `.woff` | `font/woff` |
| Fonts | WOFF2 | `.woff2` | `font/woff2` |
| Fonts | TrueType | `.ttf` | `font/ttf` |
| Fonts | OpenType | `.otf` | `font/otf` |
| Video | MP4 | `.mp4`, `.m4v` | `video/mp4` |
| Video | WebM | `.webm` | `video/webm` |
| Video | QuickTime | `.mov`, `.qt` | `video/quicktime` |
| Documents | PDF | `.pdf` | `application/pdf` |
| Documents | CSV | `.csv` | `text/csv` |
| Documents | Word | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| Documents | Excel | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| Documents | Markdown | `.md`, `.markdown` | `text/markdown` |
| Documents | Plain text | `.txt` | `text/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:

| Type | Also accepted as `contentType` |
| --- | --- |
| JPEG | `image/pjpeg` |
| ICO | `image/vnd.microsoft.icon` |
| HEIC | `image/heic-sequence` |
| HEIF | `image/heif-sequence` |
| Photoshop | `image/photoshop`, `image/x-photoshop`, `image/psd`, `application/photoshop`, `application/x-photoshop`, `application/psd` |
| Adobe DNG | `image/dng` |
| Fujifilm | `image/x-fujifilm-raf` |
| Panasonic | `image/x-panasonic-raw` |
| Illustrator | `application/postscript`, `application/pdf`, `application/vnd.adobe.illustrator` |
| EPS | `application/eps`, `application/x-eps`, `image/eps`, `image/x-eps` |
| WOFF | `application/font-woff` |
| WOFF2 | `application/font-woff2` |
| TrueType | `application/x-font-ttf`, `application/font-sfnt` |
| OpenType | `application/x-font-otf`, `application/vnd.ms-opentype` |
| MP4 | `video/x-m4v` |
| CSV | `application/vnd.ms-excel` |
| Markdown | `text/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 `ETag`s.
- 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

| State | Meaning | What comes next |
| --- | --- | --- |
| `pending` | Started. Waiting for the parts and for you to complete it. | `verifying`, `cancelled` or `expired` |
| `verifying` | Completed. The checks are running. | `ready` or `rejected` |
| `ready` | The checks passed. `fileID` and `versionID` name the file and the version it made. | Final |
| `rejected` | The checks refused the bytes. `rejectReason` says why. No file or version was made. | Final |
| `expired` | It was never completed. | Final |
| `cancelled` | You 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.

| Check | Rejected 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](statuses.md) and [Sharing and public links](sharing.md).
- 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-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](library-and-suggestions.md#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:

| `previewStatus` | Meaning |
| --- | --- |
| `pending` | Being made. |
| `ready` | Both exist, or the image service makes them when shown. `thumbnailURL` and `previewURL` are set. |
| `unsupported` | This type has no preview, or the file embeds none. |
| `failed` | A preview could not be made from this file. |

What the preview shows, by type:

| Type | Preview |
| --- | --- |
| JPEG, PNG, GIF, WebP, AVIF, SVG | The image |
| HEIC, HEIF | The image |
| Photoshop (`.psd`, `.psb`) | The flattened image the file holds |
| Raw photos | The largest JPEG the file embeds. `unsupported` when it embeds none |
| Illustrator | Page 1, when the file is PDF-based. `unsupported` for a PostScript-based file |
| EPS | The preview image the file embeds. `unsupported` when it embeds none |
| InDesign | The thumbnail the file embeds. `unsupported` when it embeds none |
| Figma | The thumbnail the file holds |
| PDF | Page 1 |
| MP4, WebM, QuickTime | One frame, 10% into the video and at most 3 seconds in |
| ICO, fonts, CSV, Word, Excel, Markdown, text | None (`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](versions.md).
- Previews are never public. They are served through temporary addresses.
  See [Downloading](downloading.md#signed-links).

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

| `playbackStatus` | Meaning |
| --- | --- |
| `original` | The original plays as it is, or the file is not a video. |
| `pending` | The playback rendition is being prepared. |
| `ready` | The playback rendition exists. |
| `failed` | No 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](sharing.md#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](#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:

| Status | Meaning |
| --- | --- |
| "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:

| Text | When |
| --- | --- |
| "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:

| Text | `rejectReason` |
| --- | --- |
| "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](library-and-suggestions.md#the-duplicate-notice-on-a-files-page).
- To find duplicates later, use Filter > "Show" > "Duplicates". See
  [Folders, moving and finding](organizing.md).

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

| Operation | Capability ID | MCP tool | Scope |
| --- | --- | --- | --- |
| `POST W/uploads` | `workspace.uploads.create` | `workspace_uploads_create` | `files:write` |
| `GET W/uploads` | `workspace.uploads.list` | `workspace_uploads_list` | `files:read` |
| `GET W/uploads/{uploadID}` | `workspace.uploads.get` | `workspace_uploads_get` | `files:read` |
| `POST W/uploads/{uploadID}/part-urls` | `workspace.uploads.sign_parts` | `workspace_uploads_sign_parts` | `files:write` |
| `GET W/uploads/{uploadID}/parts` | `workspace.uploads.list_parts` | `workspace_uploads_list_parts` | `files:read` |
| `POST W/uploads/{uploadID}/complete` | `workspace.uploads.complete` | `workspace_uploads_complete` | `files:write` |
| `DELETE W/uploads/{uploadID}` | `workspace.uploads.cancel` | `workspace_uploads_cancel` | `files:write` |
| `POST L/uploads` | `library.uploads.create` | `library_uploads_create` | `files:write` |
| `GET L/uploads` | `library.uploads.list` | `library_uploads_list` | `files:read` |
| `GET L/uploads/{uploadID}` | `library.uploads.get` | `library_uploads_get` | `files:read` |
| `POST L/uploads/{uploadID}/part-urls` | `library.uploads.sign_parts` | `library_uploads_sign_parts` | `files:write` |
| `GET L/uploads/{uploadID}/parts` | `library.uploads.list_parts` | `library_uploads_list_parts` | `files:read` |
| `POST L/uploads/{uploadID}/complete` | `library.uploads.complete` | `library_uploads_complete` | `files:write` |
| `DELETE L/uploads/{uploadID}` | `library.uploads.cancel` | `library_uploads_cancel` | `files: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](../agents/mcp.md#uploads).

### What an upload holds

| Property | Meaning |
| --- | --- |
| `id` | The upload's ID. |
| `state` | `pending`, `verifying`, `ready`, `rejected`, `expired` or `cancelled`. |
| `fileName`, `sizeBytes` | As declared. |
| `contentType` | The type the extension names. |
| `sha256` | `sha256:<hex>` when declared, else `null`. |
| `folderID` | The destination folder, or `null`. |
| `targetFileID`, `baseVersionID` | Set for a replacement, else `null`. |
| `partSizeBytes` | The size of every part but the last. |
| `partCount` | How many parts the file is sent in, at most 10,000. |
| `partURLs` | The addresses of the first 100 parts, answered when the upload starts. `null` when you read it later. |
| `expiresAt` | When a pending upload expires unless completed. |
| `rejectReason` | Why it was rejected, else `null`. |
| `fileID`, `versionID` | The file and the version it made, once `ready`. Otherwise `null`. |
| `duplicates` | Up to 10 other live files with the same bytes. |
| `createdAt`, `completedAt`, `finishedAt` | When it was started, completed and finished. |

### Worked example

Start the upload:

```sh
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"
  }'
```

```json
{
  "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.

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

```sh
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 `ETag`s,
`GET .../uploads/{uploadID}/parts` lists them.

Then read it until `state` is `ready` or `rejected`:

```sh
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](../agents/mcp.md#upload-a-file).

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| The file is named `Photo.JPG` | It is accepted as a JPEG. | Extensions are compared without regard to case. |
| The file has no extension, such as `README` | `415 UNSUPPORTED_MEDIA_TYPE`. | The extension decides the type, and there is none. |
| The name has two extensions, such as `logo.svg.png` | It is treated as a PNG. | Only the last extension counts. |
| `fileName` is `folder/logo.png` | `422 VALIDATION_FAILED` on `fileName`. | A name must not contain a path. Put the file in a folder with `folderID`. |
| `fileName` ends in a line break | `422 VALIDATION_FAILED` on `fileName`. | Control characters are refused, also at the very end. |
| `fileName` is 201 characters long | `422 VALIDATION_FAILED` on `fileName`. | Names are 1 to 200 characters. |
| `sizeBytes` is 0 | `422 VALIDATION_FAILED` on `sizeBytes`. The app shows "Rejected: The file is empty". | An empty file cannot be uploaded. |
| A 3 GiB PNG is uploaded | `413 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 uploaded | It is accepted. It is sent in 2,560 parts of 16 MiB. | Videos go up to 50 GiB. |
| A 51 GiB video is uploaded | `413 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 uploaded | `413 PAYLOAD_TOO_LARGE`, not `415`. | The size is checked before the type. |
| A 3 GiB `.exe` is uploaded | `415 UNSUPPORTED_MEDIA_TYPE`. | Within 50 GiB, the type decides. |
| `page.png` is declared with `contentType: text/html` | `415 UNSUPPORTED_MEDIA_TYPE`. | The declared type does not match the extension. |
| A `.csv` is declared as `application/vnd.ms-excel` | It is accepted. | Some systems label CSV files as Excel documents. |
| `contentType` is `image/png; charset=binary` | It is accepted for a `.png`. | Only the part before `;` counts. |
| A PNG is named `photo.jpg` | The upload is `rejected` with `TYPE_MISMATCH`. | The bytes are another accepted type than the name claims. |
| An HTML page is named `banner.png` | The upload is `rejected` with `TYPE_NOT_ALLOWED`. | The bytes are no accepted type. |
| A ZIP archive is renamed to `report.docx` | The 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.docx` | The upload is `rejected` with `TYPE_MISMATCH`. | Its content is Figma, another accepted type. |
| A plain TIFF is renamed to `scan.dng` | The 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 `.csv` | The 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.txt` | It is accepted as plain text. | Any text passes as `.txt` or `.md`. |
| An SVG is uploaded as `icon.txt` | It 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.txt` | The upload is `rejected` with `TYPE_MISMATCH`. | The bytes are an image, not text. |
| A file with random binary content is named `data.md` | The upload is `rejected` with `TYPE_NOT_ALLOWED`. | It does not read as text. |
| An image has 20,000 pixels on one side | The upload is `rejected` with `MEDIA_INVALID`. | Images may have at most 16,384 pixels a side. |
| A PDF has 600 pages | The upload is `rejected` with `MEDIA_INVALID`. | PDFs may have at most 500 pages. |
| A truncated or damaged image is uploaded | The upload is `rejected` with `MEDIA_INVALID`. | It does not decode. |
| A `.mp4` holds only sound | The 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 malware | The upload is `rejected` with `MALWARE`. The bytes are never stored as a file. | Every upload is scanned. |
| You declare a `sha256` and send other bytes | The upload is `rejected` with `DIGEST_MISMATCH`. | The declared digest is a promise about the bytes. |
| `sha256` is 63 digits long | `422 VALIDATION_FAILED` on `sha256` at the start. | It must be 64 hexadecimal digits. |
| You `PUT` fewer or more bytes than a part's `sizeBytes` | The storage refuses the `PUT` with `403`. | Each address accepts exactly its part's length. |
| You send the parts in the order 3, 1, 2 | It works. | Parts are joined by number. |
| You complete before sending every part | `409 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 3 | `409 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 three | `422 VALIDATION_FAILED` on `parts`. | Every part is named once. |
| You send a part twice | The 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 file | List 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 sent | The 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 resume | The 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 sent | A 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 twice | Both answer `202`. The checks run once. | Completing again changes nothing. |
| You complete 24 hours and 3 minutes after starting, having sent the parts in time | It works. | Completing is possible for 5 minutes after `expiresAt`. |
| You complete 25 hours after starting | `409 CONFLICT`, reason `EXPIRED`. | The upload expired. Start a new one. |
| You never complete | The 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 made | The storage refuses with `403`. Ask for a new address with `part-urls`. | An address lives 15 minutes. |
| You cancel, then complete | Complete answers `409 CONFLICT`, reason `NOT_PENDING`. | A cancelled upload can never be completed. |
| You cancel twice | The second answers `409 CONFLICT`, reason `NOT_PENDING`. | Only a pending upload can be cancelled. |
| You cancel a `ready` or `rejected` upload | `409 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 ID | `404 NOT_FOUND`, for reading, part addresses, listing parts, completing and cancelling alike. | An upload belongs to whoever started it. |
| A 2 GiB video is uploaded | It 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 folder | `403 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 upload | `403 FORBIDDEN`, reason `INSUFFICIENT_SCOPE`. | Starting needs `files:write`. |
| `folderID` names a folder of another workspace | `422 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 trash | `422 VALIDATION_FAILED` on `folderID`. | The folder must be live. |
| The folder is trashed while the upload is being checked | The 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 `requestID` | The upload from the first request is returned. No second upload is made. | Safe retries. |
| The same `requestID` is sent with another body | `409 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 folder | `201` 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 API | Two 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 app | The 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 open | They are not named as a duplicate. | Duplicates only name files you can open. |
| A file is uploaded into a public folder | It 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 status | New files have no status. | The default status is optional. |
| A raw photo embeds no JPEG | The 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 rendered | The file exists. `previewStatus` is `failed`. | Previews are made after the file exists and do not decide whether it is accepted. |
| A QuickTime movie is uploaded | It 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 uploaded | `playbackStatus` is `original`. It plays as it is. | No rendition is needed. |
| An MP4 with HEVC video is uploaded | A playback rendition is prepared. | Not every browser plays it. |
| Verification cannot finish | The 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 minutes | It 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 twice | One folder, with every file in it twice. | The existing folder is reused; files are never merged by name. |
| A dropped folder holds `.DS_Store` | It is skipped. | Names that start with a dot are not uploaded from the app. |
| Uploads are paused | `503 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 checked | The checks finish. The file is there if the workspace is restored. | See [Workspaces](../organizations/workspaces.md#restoring). |

## Errors

Answers to the upload operations:

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
| `FORBIDDEN` | 403 | Starting, 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_SCOPE` | 403 | The credential lacks `files:write` (or `files:read` for reading). | Use a credential with the scope. |
| `NOT_FOUND` | 404 | The 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_VERSION` | 409 | A 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_TRASH` | 409 | A replacement's file is in the trash. | Restore the file first. |
| `CONFLICT`, reason `DIFFERENT_TYPE` | 409 | A 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_MISSING` | 409 | Completing 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_MISMATCH` | 409 | Completing 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 `ETag`s. |
| `CONFLICT`, reason `OBJECT_MISSING` | 409 | Completing when the parts are gone. Message: "The upload's parts are gone; start a new upload". | Start a new upload. |
| `CONFLICT`, reason `EXPIRED` | 409 | Completing, 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_PENDING` | 409 | Cancelling 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_REUSED` | 409 | A `requestID` repeated with another body. | Use a new `requestID`. |
| `PAYLOAD_TOO_LARGE` | 413 | `sizeBytes` 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_TYPE` | 415 | The extension is not accepted, or `contentType` does not match it. | See [Accepted types](#accepted-types). |
| `VALIDATION_FAILED` | 422 | `fileName`, `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_LIMITED` | 429 | A credential passed its request limit. | Wait for `Retry-After` seconds. |
| `UNAVAILABLE`, reason `UPLOADS_DISABLED` | 503 | Uploads are paused. | Try again later. |

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

| `rejectReason` | Meaning | What to do |
| --- | --- | --- |
| `OBJECT_MISSING` | No joined bytes were found. | Start again and send the parts. |
| `SIZE_MISMATCH` | The joined bytes are not the declared size. This cannot happen when every part was accepted. | Declare the exact size. |
| `DIGEST_MISMATCH` | The bytes do not have the declared `sha256`. | Declare the right digest, or none. |
| `TYPE_NOT_ALLOWED` | The content is no accepted type. | See [Accepted types](#accepted-types). |
| `TYPE_MISMATCH` | The content is another accepted type than the name claims. | Give the file its real extension. |
| `MEDIA_INVALID` | The image, PDF or video does not open, or is over its limits. | Export the file again, or make it smaller. |
| `MALWARE` | The scan found malware. | Do not upload the file. |
| `STALE_FILE_VERSION` | The file being replaced got a newer version meanwhile. | Start again from the current version. |
| `IN_TRASH` | The file being replaced was trashed meanwhile. | Restore it, then start again. |
| `INGEST_FAILED` | Verification could not be finished. | Upload again. |

The shape of every error is in [Errors](../reference/errors.md).

## Limits

| What | Value |
| --- | --- |
| Size of one file | 1 byte to 50 GiB (53,687,091,200 bytes) |
| Size of an image, PDF, Word, Excel or Figma file | At most 2 GiB (2,147,483,648 bytes) |
| Part size | 16 MiB, larger only past 156 GiB; the last part holds the rest |
| Parts of one upload | At most 10,000 |
| Part addresses answered at once | Up to 100 |
| File name | 1 to 200 characters, no control characters, no `/` or `\` |
| Accepted types | 35 types, 42 extensions |
| Part address | Valid for 15 minutes, or until the upload expires |
| Time to complete (`expiresAt`) | 24 hours after the start, plus 5 minutes |
| A pending upload expires | 24 hours and 5 minutes after it was started |
| Malware scan | The first 100 MiB of a file |
| Versions made by one upload | At 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 pages | At most 500 |
| Video frame size | At most 16,384 pixels a side |
| `sha256` | 64 hexadecimal digits, with or without `sha256:` |
| Duplicates named on an upload | Up to 10 |
| Files sent at once by the app | 3 |
| Parts sent at once by the app | 4, across the files being sent |
| Tries per part in the app | 5, after waits of 1, 2, 4 and 8 seconds |
| Time the tray follows a "Verifying" row | 10 minutes, plus a minute per GiB |
| File size up to which the app computes the SHA-256 first | 256 MiB |
| Thumbnail | WebP that fits 320 pixels |
| Preview | WebP that fits 1,600 pixels |
| Playback rendition | MP4, at most 1,920 by 1,080 (or 1,080 by 1,920) |
| Preparing a playback rendition | At most 30 minutes and 2 GiB |
| Page size when listing uploads | 1 to 100, default 50 |
| `requestID` is remembered | 24 hours |

See [Limits](../reference/limits.md#uploads) 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](#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](versions.md).

**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' `ETag`s, and read it until it is `ready`. See
[Worked example](#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.

## Related pages

- [Files & Assets overview](overview.md)
- [Versions and history](versions.md)
- [Folders, moving and finding](organizing.md)
- [Downloading](downloading.md)
- [Statuses](statuses.md)
- [Sharing and public links](sharing.md)
- [MCP](../agents/mcp.md) and [The REST API](../agents/rest-api.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

