# Downloading

## Summary

Every file in Talewright can be downloaded, exactly as it was uploaded, by
anyone who can open it. An earlier version can be downloaded too. Several
files, or a whole folder, download as one ZIP.

A download comes through the API or through a temporary link. A temporary
link is a web address that serves one thing for 10 minutes and then stops.
It needs no sign-in, so whoever has the address can use it while it works.
The app downloads a single file through the API and makes temporary links
for ZIPs, previews and video. An agent asks for the links it needs.

This page covers downloading one file, an earlier version, a selection or a
folder as a ZIP, how temporary links behave and what makes them stop, the
thumbnail, preview and playback renderings a link can serve, and which
files open in the browser instead of downloading.

Public links, which do not expire, are described in
[Sharing and public links](sharing.md).

## 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) |
| --- | --- | --- | --- | --- |
| Download a version's bytes through the API | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Ask for a temporary link to a version, its thumbnail, its preview or its playback rendition | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Ask for a ZIP of folders and files | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Use a temporary link or a ZIP link | Anyone who has it | Anyone who has it | Not needed | Not needed |

- "Member of the workspace" includes organization owners and admins.
- Downloading needs only the right to read. Every member of the organization
  can download from the organization folder, although only owners and admins
  change it.
- A credential must list the workspace. It reaches the organization folder
  of its own organization.
- There is no role or setting that lets someone see a file but not download
  it.
- The full matrix is in
  [Roles and permissions](../reference/permissions.md#files-in-a-workspace).

## How it works

### Three ways to get a file's bytes

| Way | Needs | Best for |
| --- | --- | --- |
| Through the API, with your session or credential | Sign-in on every request | Scripts and agents that already hold a credential |
| A temporary link | Only the link, for 10 minutes | Browsers, handing a download to another program |
| A public link | Only the link, for as long as the file is public | Sharing outside the team. See [Sharing and public links](sharing.md) |

All three serve the same bytes: the stored original, byte for byte.
Nothing is converted or stripped on the way out.

### Downloading through the API

`GET W/files/{fileID}/versions/{versionID}/content` answers with the bytes
of that version.

- The request must be signed in, like every API request.
- It names the file and the version. The version must belong to the file,
  or the answer is `404 NOT_FOUND`.
- The answer is always a download, never something a browser shows in
  place: it carries `Content-Disposition: attachment`.
- The download is named after the file's current name.
- `Content-Type` is the version's type as confirmed from its bytes.
- `ETag` is the version's digest, written `"sha256:<hex>"`. You can use it
  to check that you received what was stored.
- `Content-Length` is the size in bytes.
- The answer must not be kept by shared caches: it carries `Cache-Control:
  private, no-cache`.
- It works for every version of a file, current or earlier.
- It works for a file in the trash, until that file is deleted for good.

### Parts of a file

A download can ask for a part of the bytes with a `Range` header, to
resume an interrupted download or to seek in a video.

- One range is served: `bytes=0-99`, `bytes=100-` or `bytes=-100` (the last
  100 bytes). The answer is `206` with `Content-Range`.
- A range that reaches past the end is cut off at the end.
- A range that starts past the end answers `416 RANGE_NOT_SATISFIABLE`
  with `details.sizeBytes` and `Content-Range: bytes */<size>`.
- Several ranges in one request, another unit than `bytes`, or a malformed
  range are ignored: the whole content is served with `200`.
- This applies to the API, to temporary links and to public links.
- On temporary and public links, a range sent with `If-Range` is honored
  only when `If-Range` holds the current `ETag`. Otherwise the whole
  content is served. A client that resumes a download of a file that was
  replaced in the meantime therefore gets the new content from the start,
  not a mix of two versions.

### Signed links

A temporary link to a file is called a signed URL.

- You ask for one with the file, the version and a `variant`. The answer
  holds `url` and `expiresAt`.
- It works for 10 minutes.
- It serves exactly one thing: that variant of that version of that file.
- It needs no cookie and no `Authorization` header. The address itself is
  the permission.
- Because of that, treat it like a secret while it works. Anyone you send
  it to can use it, signed in or not, inside or outside the organization.
- It can be used any number of times until it stops.
- It is not checked who uses it. If the person who asked for it loses
  access to the workspace a minute later, the link still works until it
  expires.
- Asking again gives a new link with a new 10 minutes. Earlier links keep
  their own time.
- Making a signed link is not recorded in the audit trail.

The four variants:

| `variant` | Serves | Exists when |
| --- | --- | --- |
| `original` | The version's own bytes | Always |
| `thumb` | A WebP image that fits 320 pixels | The version has a preview. See [Previews](uploading.md#previews). |
| `preview` | A WebP image that fits 1,600 pixels | The same |
| `playback` | A video's MP4 rendition for playing in a browser | The video needed one and it is ready. See [Video playback](uploading.md#video-playback). |

Asking for a variant that does not exist answers `409 CONFLICT` with one of
these reasons:

| Reason | Meaning | What to do |
| --- | --- | --- |
| `PREVIEW_PENDING` | The thumbnail and preview are still being made. | Try again shortly. |
| `PREVIEW_FAILED` | No preview could be made from this file. | Use `original`. |
| `NO_PREVIEW` | This type has no preview, or the file embeds none. | Use `original`. |
| `PLAYBACK_PENDING` | The playback rendition is still being prepared. | Try again shortly, or use `original`. |
| `PLAYBACK_FAILED` | No playback rendition could be made. | Use `original`. |
| `NO_PLAYBACK` | The original plays as it is, or the file is not a video. | Use `original`. |

Other refusals when asking:

- The file is in the trash: `409 CONFLICT`, reason `IN_TRASH`.
- The file or version is unknown, or the file was deleted for good:
  `404 NOT_FOUND`.
- `variant` is none of the four: `422 VALIDATION_FAILED`.

A file read also carries ready-made signed links: `thumbnailURL` on every
file, and `previewURL` when a single file is read. Both are `null` until
the preview is ready and while the file is in the trash. They work for 10
to 15 minutes: they stop on a five-minute mark of the clock, so every read
within the same five minutes carries the same link.

### What makes a signed link stop

| Event | The link |
| --- | --- |
| 10 minutes pass | Stops. Ask for a new one. |
| The file is moved to the trash | Stops at once. |
| The file is restored from the trash | Stays stopped. Links from before the trash never come back. Ask for a new one. |
| The file is deleted for good | Stops. |
| The file's workspace or organization is deleted | Stops. If it is restored before the link's 10 minutes are over, the link works again. |
| The address is altered in any way | Never works. |

What does not stop a signed link:

| Event | The link |
| --- | --- |
| The file is replaced | Keeps serving the version it was made for. |
| The file is renamed | Keeps working. A download now carries the new name. |
| The file is moved to another folder | Keeps working. |
| The file's status changes | Keeps working. |
| The file is made public or restricted | Keeps working. Signed links and public links are independent. |
| The person who asked for it signs out or loses access | Keeps working until it expires. |

A link that has stopped answers `403`. The answer does not say why.

### What a signed link serves

- The bytes of the variant, with the type confirmed from the bytes.
- `ETag` is the digest of what is served.
- The answer may be kept by the browser that asked, for no longer than the
  link works. It is marked private, so shared caches do not keep it.
- A request whose `If-None-Match` names that `ETag` answers `304 Not
  Modified` without a body, for as long as the link works. A signed link
  names one version, so its `ETag` never changes. The weak form
  (`W/"sha256:..."`), a list of tags and `*` match too.
- The link is checked before the tag. An expired or stopped link answers
  `403` whatever the request sends.
- Downloading through the API does not answer `304`. It always sends the
  bytes.
- No cookie is read and none is set.
- A thumbnail, preview or playback rendition is named after the file with
  the rendering's extension: `poster.webp` for the preview of `poster.psd`,
  `clip.mp4` for the playback rendition of `clip.mov`.
- Signed links are for opening and downloading. To use a file from another
  website, for example as a web font or an image on a page, use its public
  link.

### What opens in the browser and what downloads

A signed link or a public link opened in a browser either shows the file in
place or downloads it. That depends on the type alone.

| Shown in place | Always downloads |
| --- | --- |
| JPEG, PNG, GIF, WebP, AVIF, ICO | SVG |
| PDF | HEIC, HEIF |
| MP4, WebM | Photoshop (`.psd`, `.psb`) |
| Every thumbnail, preview and playback rendition | Raw photos |
| | Illustrator, EPS, InDesign, Figma |
| | Fonts |
| | QuickTime (`.mov`, `.qt`) |
| | CSV, Word, Excel, Markdown, plain text |

- "Shown in place" means the link carries `Content-Disposition: inline`.
  "Always downloads" means `attachment`.
- Downloading through the API always downloads, whatever the type.
- A ZIP always downloads.
- An SVG is never shown in place, although browsers can draw it. Its
  preview is a WebP image and is shown.
- A QuickTime original downloads. In the app it plays through its playback
  rendition.
- Whatever is shown in place is shown as a file, never run as a web page.
- To save a file that is shown in place, use the browser's "Save as", or
  download it through the API. In the app, "Download" does the latter and
  always saves.

### ZIP downloads

Several files, or folders with everything in them, download as one ZIP.

- You name `folderIDs`, `fileIDs` or both, all from one workspace or from
  the organization folder. At least one ID is needed.
- The answer holds `url`, `expiresAt`, `name`, `fileCount` and `sizeBytes`.
- `url` is a temporary link to the ZIP. It works for 10 minutes, without a
  sign-in, like a signed link.
- `fileCount` is the number of files in the ZIP. `sizeBytes` is the total
  size of those files. The ZIP is slightly larger.
- Asking for a ZIP is recorded in the audit trail, with the number of
  folders, files and bytes. See
  [Audit trail](../reference/audit-trail.md#files).
- An ID given twice counts once.

What is refused when you ask:

| Situation | Answer |
| --- | --- |
| No folder and no file is named | `422 VALIDATION_FAILED` on `fileIDs` |
| A named folder or file is unknown, belongs to another workspace, or is in the trash | `404 NOT_FOUND`, for the whole request |
| The ZIP would hold more than 10,000 files | `422 VALIDATION_FAILED` on `fileIDs`, message "an archive holds at most 10000 files" |
| The files add up to more than 20 GiB | `413 PAYLOAD_TOO_LARGE`, with `details.limitBytes` |

Both limits are checked when you ask, before anything is downloaded.

### What is inside a ZIP

- Each folder you named sits at the top of the ZIP under its own name, with
  the live folders and files below it, arranged as they are in Talewright.
- Each file you named by itself sits at the top of the ZIP.
- A file you named that is also inside a folder you named appears once, in
  its folder.
- A folder you named that is inside another folder you named appears once,
  in its place inside the other.
- Empty folders are included.
- Every file is its current version, the original bytes.
- Trashed files and trashed folders are left out.
- Files are stored in the ZIP as they are, without compression.
- Each file's date in the ZIP is the time its current version was
  uploaded, in UTC.

The ZIP's own name:

| You asked for | The ZIP is named |
| --- | --- |
| Exactly one folder and nothing else | The folder's name: `Press kit.zip` |
| Anything else in a workspace | `{workspace name} files.zip` |
| Anything else in the organization folder | `Library files.zip` |

Names inside the ZIP are made safe for every operating system:

- `/`, `\`, `:`, `*`, `?`, `"`, `<`, `>`, `|` and control characters in a
  name become `_`. A file named `a\b:c.png` is `a_b_c.png` in the ZIP.
- Spaces at the start, and dots and spaces at the end, are removed.
- A name that is `.` or `..`, or has nothing left, becomes `_`.
- Two entries in one folder with the same name, ignoring case, are told
  apart by a number. `Logo.png` and `logo.PNG` become `Logo.png` and
  `logo (2).PNG`. The number goes before the extension.
- A file with the same name as a folder beside it gets the number: a file
  `Logos` beside a folder `Logos` becomes `Logos (2)`.
- The names in Talewright are not changed by this.

### Between asking for a ZIP and downloading it

The link is made first and the ZIP is put together when the link is opened.

- The ZIP holds the files that were counted when you asked, and no others.
  A file added to a folder afterwards is not in it.
- A file that was moved to the trash since is left out.
- A file that was replaced since downloads as its new current version.
- A file that was renamed since has its new name.
- The link can be opened more than once within its 10 minutes. Each time
  gives the ZIP as things are at that moment.
- If something goes wrong while the ZIP is being sent, the download fails.
  You never get a ZIP that looks complete but is missing files.
- The link stops when its 10 minutes are over, or when the workspace or
  organization is deleted. It then answers `403`.
- A ZIP link is never kept by caches.

### Thumbnails, previews and playback

These renderings exist so a file can be looked at without downloading it.

- A thumbnail is a WebP image that fits 320 pixels. Listings use it.
- A preview is a WebP image that fits 1,600 pixels. A file's page uses it.
- A playback rendition is an MP4 that browsers play. A video's page uses
  it.
- Which types have them, and when they are ready, is in
  [Previews](uploading.md#previews) and
  [Video playback](uploading.md#video-playback).
- They are reached only through signed links. They have no public address.
- They are never what "Download" gives you. Downloads and public links
  always serve the original.
- Resized and reformatted images of a public file are a separate feature.
  See [Image delivery](image-delivery.md).

## In the app

### Downloading one file

- **On a file's page**, "Download" is above the preview.
- **In a listing**, choose "Download" in the file's menu, from "File
  actions for {name}" or a right-click.
- **With one file selected**, "Download" in the bar "Selected files"
  downloads that file.
- **The command palette** offers "Download" for the selection or the open
  file.

In each case the app downloads the original of the current version
through the API, with your session. From a listing it first asks which
version is current, so a file replaced since the listing loaded still
downloads as its newest version. The browser saves it under the file's
name, whatever its type: nothing opens in a tab.

- Everyone who can open the file has "Download", also members in the
  organization folder.
- A file in the trash has no "Download" button. Its earlier versions are
  still in "History".
- The download needs no temporary link, so the button works however long
  the page has been open.

### Downloading an earlier version

- Open the file's page and look at the "History" section in "Details".
- Each version has its own "Download".
- It saves exactly that version, under the file's current name.
- See [Versions and history](versions.md).

### Downloading a folder or a selection

- **A folder**: choose "Download" in the folder's menu. You get a ZIP named
  after the folder.
- **A selection**: tick the items and choose "Download" in the bar
  "Selected files". Files and folders can be mixed. You get one ZIP named
  "{workspace} files" or "Library files".
- The ZIP opens as a download in the browser. The app shows no progress of
  its own; the browser's download list does.
- Selecting is offered where you may change files. In the organization
  folder, members download one file or one folder at a time from its menu.

Messages when a ZIP cannot be made:

| Text | When |
| --- | --- |
| "Too large to download at once. Download fewer files." | The files add up to more than 20 GiB. |
| "Too many files to download at once. Download fewer files." | More than 10,000 files. |
| "Could not download {name}. Try again." | Anything else, for example an item that was trashed in the meantime. |

### Looking instead of downloading

- A file's page shows its preview: the image "Preview of {name}".
- A video's page has a player. See
  [Video in the app](uploading.md#video-in-the-app).
- A file without a preview shows "Preview unavailable" and its type icon.
  "Download" works all the same.

## For agents

### Operations

| Operation | Capability ID | MCP tool | Scope |
| --- | --- | --- | --- |
| `GET W/files/{fileID}/versions/{versionID}/content` | `workspace.files.read` | none | `files:read` |
| `POST W/files/{fileID}/versions/{versionID}/signed-url` | `workspace.files.signed_url` | `workspace_files_signed_url` | `files:read` |
| `POST W/files/archive` | `workspace.files.archive` | none | `files:read` |
| `GET L/files/{fileID}/versions/{versionID}/content` | `library.files.read` | none | `files:read` |
| `POST L/files/{fileID}/versions/{versionID}/signed-url` | `library.files.signed_url` | `library_files_signed_url` | `files:read` |
| `POST L/files/archive` | `library.files.archive` | none | `files:read` |

- Over MCP, bytes never travel through a tool. The agent asks for a signed
  link with `workspace_files_signed_url` and fetches it with an ordinary
  HTTP `GET`. See [MCP](../agents/mcp.md#download-a-file).
- Over REST, an agent can use either the content operation or a signed
  link.
- ZIP downloads are offered over REST only.

### Requests and answers

| Operation | Body | Success |
| --- | --- | --- |
| Download through the API | none. Optional `Range` header. | `200` with the bytes, or `206` with the range |
| Ask for a signed link | `{"variant": "original"}`, or `thumb`, `preview`, `playback` | `200` with `url` and `expiresAt` |
| Ask for a ZIP | `{"folderIDs": [...], "fileIDs": [...]}`, at least one ID | `200` with `url`, `expiresAt`, `name`, `fileCount`, `sizeBytes` |

### Worked example: download a file

Read the file to learn its current version:

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

Take `currentVersion.id` from the answer. Then either download through the
API:

```sh
curl -s -o press-photo.jpg \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/versions/$VERSION/content" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

or ask for a signed link:

```sh
curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/versions/$VERSION/signed-url" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variant": "original"}'
```

```json
{
  "url": "https://.../s/.../press-photo.jpg",
  "expiresAt": "2026-11-14T10:10:00Z"
}
```

and fetch it within 10 minutes, without any `Authorization` header:

```sh
curl -s -o press-photo.jpg "$SIGNED_URL"
```

To check the download, compare its SHA-256 with `currentVersion.digest`.

### Worked example: download a folder as a ZIP

```sh
curl -s -X POST "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/archive" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderIDs": ["0192f0c3-8b50-7244-ad99-6dab4a5c1f34"]}'
```

```json
{
  "url": "https://.../z/.../Press%20kit%202026.zip",
  "expiresAt": "2026-11-14T10:10:00Z",
  "name": "Press kit 2026",
  "fileCount": 42,
  "sizeBytes": 318440112
}
```

```sh
curl -s -o "Press kit 2026.zip" "$ZIP_URL"
```

The ZIP holds one top folder, `Press kit 2026/`, with the folder's content
below it.

### Worked example: resume a download

```sh
curl -s -o part.bin -H "Range: bytes=1048576-" \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/versions/$VERSION/content" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" -i
```

```
HTTP/1.1 206 Partial Content
Content-Range: bytes 1048576-4194303/4194304
```

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A signed link is opened after 10 minutes | `403`. | It expired. Ask for a new one. |
| A signed link is opened after the file was trashed | `403`. | Trashing stops every earlier link. |
| A signed link is opened after the file was trashed and restored | `403`. | Links from before the trash do not come back. |
| A signed link is opened after the file was replaced | It serves the version it was made for, not the new one. | A signed link names one version. |
| A signed link is opened after the file was renamed | It works. The download carries the new name. | The name in the address is only a label. |
| A signed link is opened by someone who is not signed in | It works. | The address is the permission. |
| A signed link is opened after its requester was removed from the workspace | It works until it expires. | It is not checked who uses a link. |
| A signed link is opened after its workspace was deleted | `403`. After a restore within the link's 10 minutes it works again. | Nothing in a deleted workspace is served. |
| One character of a signed link is changed | `403`. | An altered link never works. |
| A signed link is asked for a file in the trash | `409 CONFLICT`, reason `IN_TRASH`. | Restore the file first. Its versions can still be downloaded through the API. |
| `thumb` is asked for a CSV file | `409 CONFLICT`, reason `NO_PREVIEW`. | That type has no preview. |
| `thumb` is asked for right after an upload | `409 CONFLICT`, reason `PREVIEW_PENDING`. | The preview is still being made. |
| `preview` is asked for a raw photo that embeds no image | `409 CONFLICT`, reason `NO_PREVIEW`. | The file embeds none. |
| `playback` is asked for an MP4 that plays as it is | `409 CONFLICT`, reason `NO_PLAYBACK`. | Use `original`. |
| `playback` is asked for a PNG | `409 CONFLICT`, reason `NO_PLAYBACK`. | It is not a video. |
| `playback` is asked for a QuickTime movie right after its upload | `409 CONFLICT`, reason `PLAYBACK_PENDING`. | The rendition is still being prepared. |
| A signed link is asked with a version ID of another file | `404 NOT_FOUND`. | A version belongs to one file. |
| A signed link is asked for an earlier version | It works and serves that version. | Every version can be linked. |
| A signed link to an SVG is opened in a browser | It downloads. | SVG is never shown in place. |
| A signed link to a PDF is opened in a browser | It opens in the browser. | PDF is shown in place. |
| A PDF is downloaded through the API | It downloads. | The API always answers with a download. |
| A request has `Range: bytes=0-9,20-29` | The whole content is served with `200`. | Only one range is served. |
| A request asks for bytes past the end | `416 RANGE_NOT_SATISFIABLE`. | Nothing lies there. |
| A signed link is asked again with `If-None-Match` and the `ETag` it answered before | `304 Not Modified`, no body, while the link works. After it expires or stops: `403`. | The version behind a signed link never changes, and the link is checked before the tag. |
| A resumed download sends `If-Range` with the ETag of an earlier version of a public file | The whole current content is served with `200`. | A resume never mixes two versions. |
| A ZIP is asked for with no IDs | `422 VALIDATION_FAILED` on `fileIDs`. | There is nothing to download. |
| A ZIP is asked for with one trashed file among fifty | `404 NOT_FOUND`. No link is made. | Every named item must exist and be live. |
| A ZIP is asked for a folder that holds trashed files | The link is made. The trashed files are left out. | Only what you name must be live; inside a folder, trashed items are skipped. |
| A ZIP is asked for an empty folder | The link is made. The ZIP holds the empty folder. | Empty folders are included. |
| A ZIP is asked for a folder of another workspace | `404 NOT_FOUND`. | A ZIP holds items of one workspace or of the organization folder. |
| A ZIP is asked for a folder and a file inside it | The file appears once, in the folder. | Nothing is doubled. |
| A ZIP would hold 10,001 files | `422 VALIDATION_FAILED` on `fileIDs`. | The limit is 10,000 files. |
| A ZIP would hold 21 GiB | `413 PAYLOAD_TOO_LARGE`, `details.limitBytes` 21474836480. | The limit is 20 GiB. |
| Two files in a folder are named `Logo.png` and `logo.PNG` | In the ZIP they are `Logo.png` and `logo (2).PNG`. | Many systems treat those names as the same. |
| A file is named `..` | In the ZIP it is `_`. | A name must not lead out of the folder it is unpacked into. |
| A file is trashed after the ZIP link was made | It is missing from the ZIP. | The ZIP is put together when the link is opened. |
| A file is added to the folder after the ZIP link was made | It is not in the ZIP. | The ZIP holds what was counted when you asked. |
| A ZIP link is opened twice | Both downloads work, within 10 minutes. | The link is not used up. |
| A ZIP link is opened after 10 minutes | `403`. | It expired. |
| A member of the organization downloads an organization folder file | It works. | Reading the organization folder includes downloading. |
| Someone outside the workspace asks for a version's content | `404 NOT_FOUND`. | Outsiders cannot tell the file exists. |
| A credential without `files:read` asks for a signed link | `403 FORBIDDEN`, reason `INSUFFICIENT_SCOPE`. | Downloading needs `files:read`. |
| A file was deleted for good | Its content, its links and its versions answer "not found" or `403`. | Nothing of it is left. |
| A file's bytes are also another file's bytes | Each downloads on its own, with its own name. | Files are independent, even when their content is the same. |

## Errors

Answers of the API:

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
| `FORBIDDEN`, reason `INSUFFICIENT_SCOPE` | 403 | The credential lacks `files:read`. | Use a credential with the scope. |
| `NOT_FOUND` | 404 | The file or version is unknown, out of reach or deleted for good; a version of another file; a folder or file named for a ZIP is unknown, foreign or in the trash. | Check the IDs. |
| `CONFLICT`, reason `IN_TRASH` | 409 | A signed link is asked for a file in the trash. | Restore the file, or download through the API. |
| `CONFLICT`, reason `PREVIEW_PENDING`, `PREVIEW_FAILED` or `NO_PREVIEW` | 409 | `thumb` or `preview` does not exist (yet). | Try again shortly, or use `original`. |
| `CONFLICT`, reason `PLAYBACK_PENDING`, `PLAYBACK_FAILED` or `NO_PLAYBACK` | 409 | `playback` does not exist (yet). | Try again shortly, or use `original`. |
| `PAYLOAD_TOO_LARGE` | 413 | A ZIP would hold more than 20 GiB. `details.limitBytes` holds the limit. | Download fewer files at once. |
| `RANGE_NOT_SATISFIABLE` | 416 | A `Range` starts past the end. `details.sizeBytes` holds the size. | Ask for bytes that exist. |
| `VALIDATION_FAILED` | 422 | An unknown `variant`; a ZIP with no IDs or with more than 10,000 files. | Correct the request. |
| `RATE_LIMITED` | 429 | A credential passed its request limit. | Wait for `Retry-After` seconds. |

Answers of the links themselves:

| Status | When |
| --- | --- |
| 403 | A signed link or a ZIP link is altered, expired or was stopped. |
| 416 | A `Range` starts past the end. |

These refusals are never cached. See
[Errors](../reference/errors.md#errors-on-the-files-host).

## Limits

| What | Value |
| --- | --- |
| Lifetime of a signed link | 10 minutes |
| Lifetime of `thumbnailURL` and `previewURL` | 10 to 15 minutes |
| Lifetime of a ZIP link | 10 minutes |
| Files in one ZIP | Up to 10,000 |
| Total size of the files in one ZIP | Up to 20 GiB |
| Ranges in one request | 1 |
| 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) |
| Downloads of one file | No limit |

See [Limits](../reference/limits.md#downloading-and-delivery) for every
limit in one place.

## Questions and answers

**Do I get the original file when I download?**
Yes. The bytes are exactly what was uploaded. Thumbnails and previews are
separate and are never what "Download" gives you.

**Can I download an old version?**
Yes. Every version is in the file's "History", each with its own
"Download".

**Can I download a whole folder?**
Yes. Choose "Download" in the folder's menu. You get a ZIP with the
folder's structure.

**Can I download several files at once?**
Yes. Select them and choose "Download". You get one ZIP.

**Is there a limit on a ZIP?**
10,000 files and 20 GiB. Past either, download in parts.

**Why did my file open in a tab instead of downloading?**
You opened a temporary or public link. Images, PDFs and MP4 or WebM videos
are shown by the browser there. Use the browser's "Save as" to keep the
file, or choose "Download" in the app, which always saves.

**Why does an SVG download instead of showing?**
SVG files are always downloaded. In the app you still see the SVG's
preview.

**Is a download link safe to send to someone?**
It works for anyone who has it, for 10 minutes, without a sign-in. Send it
only to someone who should have the file. For lasting sharing, use a public
link.

**How long does a download link work?**
10 minutes. The app's own "Download" of a file needs no link. For ZIPs,
previews and video the app makes new links as needed.

**Does a download link still work after I trash the file?**
No. It stops at once, and it does not come back when the file is restored.

**Does a download link follow the file when it is replaced?**
No. It keeps serving the version it was made for. The public link is the
one that follows the current version.

**Can a member of the organization download from the organization folder?**
Yes. Everyone who can read a file can download it.

**Can I let someone view a file without letting them download it?**
No. Whoever can open a file can download it.

**Are downloads recorded?**
Asking for a ZIP is recorded in the audit trail. Downloads of single files
are not.

**Are the files in a ZIP compressed?**
No. They are stored as they are, so the ZIP is about as large as the files
together.

**Why is a file named differently inside the ZIP?**
Characters that some systems do not accept in file names are replaced by
`_`, and two files with the same name in one folder get a number. The names
in Talewright stay as they are.

**How does an agent download a file?**
It reads the file, asks for a signed link to `currentVersion.id` with the
variant `original`, and fetches the link. Over REST it can also download
the content directly.

**How can an agent be sure a download is complete and unchanged?**
It compares the SHA-256 of what it received with the version's `digest`.

**Can a download be resumed?**
Yes. Send a `Range` header for the bytes that are missing.

**Can I use a signed link as an image address on my website?**
No. It stops after 10 minutes. Make the file public and use its public
link.

## Related pages

- [Files & Assets overview](overview.md)
- [Uploading](uploading.md)
- [Versions and history](versions.md)
- [Trash and restore](trash.md)
- [Sharing and public links](sharing.md)
- [Image delivery](image-delivery.md)
- [Export](../organizations/export.md)
- [MCP](../agents/mcp.md) and [The REST API](../agents/rest-api.md)
- [Audit trail](../reference/audit-trail.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

