# Export

## Summary

An export is a copy of an organization's files that you can download and
keep. It is one zip archive. It holds the current version of every live file
in every workspace and in the organization folder, and a file `manifest.json`
that describes them: names, folders, tags, statuses, fields and version
details.

Owners and admins start an export. It is built in the background. When it is
ready, the person who started it gets an email, and the archive can be
downloaded for 7 days.

An export is a way to take your content with you or to keep an offline copy.
It does not change anything in the organization.

## Who can do what

| Action | Owner | Admin | Member | Session | Credential |
| --- | --- | --- | --- | --- | --- |
| Start an export | Yes | Yes | No | Yes | No |
| Read an export's state | Yes | Yes | No | Yes | No |
| Download a ready export | Yes | Yes | No | Yes | No |
| Get the "export ready" email | The person who started it | | | | |

- The organization role is what counts. Being owner or admin of one
  workspace is not enough.
- Any owner or admin can read and download any export of the organization,
  not only the one they started.
- A verified email is not needed.
- A credential that calls an export operation gets `403 FORBIDDEN` with
  `details.reason` `SESSION_REQUIRED`.
- The download itself needs no sign-in: it is a link that carries its own
  proof and works for a short time. See [Downloading](#downloading).

## How it works

### Starting

- Owners and admins start an export of the whole organization. There is
  nothing to choose: an export always covers everything listed below.
- Starting answers `202` with the export in state `pending`. Building
  happens in the background and can take a while for a large organization.
- An organization builds one export at a time. Starting again while one is
  pending does not start a second one. It returns the pending export, also
  when someone else started it.
- Once an export is ready, failed or expired, a new one can be started.
  Earlier ready exports stay downloadable until they expire, so several
  archives can exist side by side.
- There is no limit on how many exports an organization makes over time.
- An export cannot be cancelled.
- An export is started by a person each time. There is no scheduled or
  recurring export.
- There is no import. An archive cannot be loaded into this or another
  organization.
- An export of a deleted organization cannot be started.

### What the archive holds

The archive holds, for the organization as it is at the moment the export is
built:

- **Every live file in every live workspace**, as its current version.
- **Every live file in the organization folder**, as its current version.
- **`manifest.json`**, described in the next section.

It leaves out:

- files and folders in the trash,
- deleted workspaces, with everything in them,
- earlier versions of a file - only the current version's content is
  included, though the manifest gives its version number,
- previews and other derived images or video renditions,
- uploads that are not finished,
- members, roles, invitations, API keys and connected apps,
- public links and sharing settings,
- favorites and organization folder suggestions,
- the audit trail.

All of it is read at one moment. A file added while the export is being
built is either in it completely or not in it at all.

While the archive is built, each file's stored content is checked against
its recorded digest. If a file fails that check, the export fails instead of
handing out a damaged copy.

### The layout of the archive

- The archive is a zip file. Its download name is `export-<exportID>.zip`.
- The first entry is `manifest.json`.
- Each file is one entry:
  - a workspace file at
    `workspaces/<workspaceID>/assets/<fileID>/current.<extension>`,
  - an organization folder file at
    `library/assets/<fileID>/current.<extension>`.
- `<extension>` comes from the file's type, for example `png`, `pdf` or
  `txt`. A file of an unknown type gets `bin`.
- The entry path uses IDs, not names. The file's name, its folder and
  everything else are in `manifest.json`. Each file's manifest entry names
  its archive path, so the two are easy to match.
- Entries are compressed.
- Each file entry carries the date its version was made. `manifest.json`
  carries the date the export was requested.

### The manifest

`manifest.json` is JSON with this shape:

```json
{
  "format": "talewright-organization-export",
  "version": 2,
  "exportID": "01928f70-aaaa-7bbb-8ccc-0000000000e1",
  "requestedAt": "2026-11-01T10:00:00Z",
  "organization": { "id": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17", "name": "Acme" },
  "workspaces": [
    {
      "id": "01928f40-1111-7aaa-8bbb-000000000001",
      "name": "Brand",
      "assets": [
        {
          "id": "01928f60-0000-7000-8000-0000000000f1",
          "name": "logo.png",
          "folderID": "01928f61-0000-7000-8000-0000000000d1",
          "tagIDs": ["01928f62-0000-7000-8000-0000000000c1"],
          "fields": { "01928f63-0000-7000-8000-0000000000b1": "Spring campaign" },
          "statusID": "01928f64-0000-7000-8000-0000000000a1",
          "altText": "The Acme logo",
          "description": null,
          "caption": null,
          "currentVersion": {
            "id": "01928f65-0000-7000-8000-000000000091",
            "number": 2,
            "parentVersionID": "01928f65-0000-7000-8000-000000000090",
            "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
            "sizeBytes": 48211,
            "createdAt": "2026-10-20T08:15:00Z",
            "createdBy": { "id": "01928f3e-0000-7000-8000-00000000000a", "fullName": "Ada Aziz" },
            "path": "workspaces/01928f40-1111-7aaa-8bbb-000000000001/assets/01928f60-0000-7000-8000-0000000000f1/current.png",
            "mime": "image/png"
          }
        }
      ],
      "folders": [
        { "id": "01928f61-0000-7000-8000-0000000000d1", "parentID": null, "name": "Logos" }
      ],
      "tags": [
        { "id": "01928f62-0000-7000-8000-0000000000c1", "name": "brand" }
      ],
      "statuses": [
        { "id": "01928f64-0000-7000-8000-0000000000a1", "name": "Approved for public use", "allowsPublic": true, "isDefault": false }
      ],
      "fileFields": [
        { "id": "01928f63-0000-7000-8000-0000000000b1", "name": "Campaign", "kind": "text", "choices": [] }
      ]
    }
  ],
  "library": {
    "assets": [],
    "folders": [],
    "tags": [],
    "statuses": [
      { "id": "01928f66-0000-7000-8000-0000000000a2", "name": "Approved for public use", "allowsPublic": true, "isDefault": false }
    ],
    "fileFields": []
  }
}
```

- `format` is always `talewright-organization-export` and `version` is `2`.
- `requestedAt` is when the export was started.
- `workspaces` lists the live workspaces in the order they were created.
- `library` has the same five lists as a workspace, for the organization folder.
- `assets` are the files, in the order they were created.
  - `folderID` is the folder the file is in, or `null` at the top level.
  - `tagIDs` are the file's tags. The names are in the same workspace's or
    the organization folder's `tags`.
  - `statusID` is the file's status, or `null` without one. The statuses are
    in the same workspace's or the organization folder's `statuses`.
  - `fields` holds the file's values of its workspace's or the organization
    folder's own fields, by field ID. A text field's value is a string, a
    number field's a number, a date field's a date as `YYYY-MM-DD`, a
    single-choice field's the ID of the chosen choice, and a multiple-choice
    field's a list of choice IDs. A file with no values has `{}`.
  - `altText`, `description` and `caption` are the file's texts, or `null`.
  - `currentVersion` describes the content in the archive: the version's ID
    and number, the version it replaced (`parentVersionID`, `null` for a
    first version), its `digest` (`sha256:` and 64 hexadecimal characters),
    its size in bytes, when and by whom it was made, its `path` in the
    archive and its type (`mime`).
- `folders` gives each live folder's ID, name and parent (`parentID`, `null`
  at the top level). The folder tree is rebuilt from these.
- `tags` lists every tag of that workspace or the organization folder by
  name, also tags no file uses.
- `statuses` lists that workspace's or the organization folder's statuses in
  their order, each with whether it allows public use and whether it is the
  default.
- `fileFields` lists that workspace's or the organization folder's own
  fields, each with its `kind` (`text`, `number`, `date`, `select` or
  `multiSelect`) and, for the two choice kinds, its choices.

To check a downloaded file, compute the SHA-256 of the archive entry at
`currentVersion.path` and compare it with `currentVersion.digest`.

### States

| State | Meaning | `completedAt` | `expiresAt` | `sizeBytes` | `downloadURL` |
| --- | --- | --- | --- | --- | --- |
| `pending` | Being built. | `null` | `null` | `null` | `null` |
| `ready` | The archive can be downloaded. | set | set | set | set |
| `failed` | It could not be built. Start a new one. | set | `null` | `null` | `null` |
| `expired` | The archive's 7 days are over and it is deleted. | set | set | set | `null` |

- A pending export becomes `ready` or `failed`. A ready export becomes
  `expired`. Nothing else changes state.
- An export fails when it cannot be built after repeated attempts, when a
  file's stored content does not match its digest, when the organization is
  deleted before the archive is ready, or when it is still pending 24 hours
  after it was started.
- A failed export is not retried by itself. Start a new one.
- No email is sent for a failed export.

### The email

- When an export becomes ready, the person who started it gets one email.
  Nobody else does.
- Subject: "Your {organization} export is ready".
- Heading: "Your export is ready".
- Text: "Hi {name}," and then "The export of "{organization}" from
  Talewright is ready to download."
- Button: "Download export".
- Below the button: "The export is kept for 7 days."
- The button does not download directly. It opens the organization's General
  settings page in the app with this export shown. You must be signed in as
  an owner or admin of the organization to see it. There you choose
  "Download export".
- If the person who started the export is no longer an owner or admin of
  the organization when it becomes ready, or has deleted their account, no
  email is sent. The export is still ready for the owners and admins.

### Downloading

- Reading a ready export gives a `downloadURL`.
- The link is valid for at most 15 minutes, and never past the moment the
  export expires.
- Reading the export again gives a fresh link. You can do that as often as
  you like while the export is ready.
- The link carries its own proof. Anyone who has it can download the archive
  while it is valid, without signing in. Fetch it without cookies and without
  an `Authorization` header. Do not share it.
- The answer is the zip file, with type `application/zip` and the name
  `export-<exportID>.zip`.

### Retention

- A ready archive is kept for 168 hours, which is 7 days, counted from the
  moment it became ready. `expiresAt` is that moment.
- From `expiresAt` the export reads as `expired` and gives no link.
- The archive is deleted shortly afterwards, and links handed out earlier
  stop working.
- An expired export cannot be revived. Start a new one.
- An export cannot be deleted early. A ready archive stays until its 7 days
  end.
- When the organization is removed for good, its exports and archives are
  removed with it. See [Deleting and restoring](delete-and-restore.md).

### Finding an export again

- An export is found by its ID. There is no list of an organization's
  exports.
- The ID is in the answer when the export is started, in the address of the
  settings page while you look at it (`?export=<exportID>`), and in the
  link of the "export ready" email.
- Starting an export while one is pending returns that pending export, so
  its ID can always be found again until it finishes.

## In the app

The section "Export" is on **Settings > Organization > General**, for owners
and admins. Members do not see it.

It says "Download every file as its current version, with a JSON manifest of
folders, tags, statuses and fields. Archives are kept for 7 days."

1. Choose "Start export".
2. The section shows "Preparing the export. We will email you when it is
   ready." The status updates by itself; you do not have to reload. You can
   leave the page.
3. When it is ready the section shows "Export ready: {size}, available until
   {date}." and the button "Download export".
4. "Download export" fetches a fresh link and starts the download of
   `export-<exportID>.zip`.

- While an export is pending, "Start export" is disabled.
- The page's address holds the export (`?export=...`), so reloading or
  bookmarking the page shows the same export again.
- Opening the page without an export in its address shows only "Start
  export", also when earlier exports exist.
- Choosing "Start export" when an export is ready starts a new one, and the
  section then shows the new one.

Status lines:

| Line | When |
| --- | --- |
| "Checking the export." | The page is reading the export's state. |
| "Preparing the export. We will email you when it is ready." | `pending` |
| "Export ready: {size}, available until {date}." | `ready` |
| "The export failed. Start a new one." | `failed` |
| "This export has expired. Start a new one." | `expired` |
| "This export is not available. Start a new one." | The export in the address does not exist in this organization. |
| "Could not check the export. Reload the page to try again." | The state could not be read. |

Other messages:

| Message | When |
| --- | --- |
| "Could not start the export. Try again." | Starting failed. |
| "Could not start the download. Try again." | A fresh link could not be fetched. |
| "Your role no longer allows that. The page now shows what you can do." | Your role was lowered since the page loaded. |

## For agents

Exports are for people. Both operations need a browser session, and neither
is an MCP tool.

| Operation | Capability ID | Access |
| --- | --- | --- |
| `POST /v1/organizations/{organizationID}/exports` | `organizations.exports.create` | session only |
| `GET /v1/organizations/{organizationID}/exports/{exportID}` | `organizations.exports.get` | session only |

Both answer with the export:

```json
{
  "id": "01928f70-aaaa-7bbb-8ccc-0000000000e1",
  "state": "ready",
  "createdAt": "2026-11-01T10:00:00Z",
  "completedAt": "2026-11-01T10:02:10Z",
  "expiresAt": "2026-11-08T10:02:10Z",
  "sizeBytes": 73110822,
  "downloadURL": "https://..."
}
```

- `POST` takes no body and answers `202`.
- `GET` answers `200`. Each `GET` of a ready export carries a fresh
  `downloadURL`.
- To wait for an export, read it again every few seconds until `state` is no
  longer `pending`.

### Handing a download to a script

A person can pass the `downloadURL` to a script or an agent. It needs no
credential, but it must be used within 15 minutes:

```sh
curl -L -o export.zip "$DOWNLOAD_URL"
unzip -p export.zip manifest.json | head
```

### What an agent can do instead

An agent that needs the files uses the file tools with its own credential:
it lists files and downloads the versions it needs. See
[Downloading](../files/downloading.md) and [MCP](../agents/mcp.md).

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A member starts or reads an export | `403 FORBIDDEN`. | Exports are for owners and admins. |
| Someone outside the organization starts or reads an export | `404 NOT_FOUND`. | Outsiders cannot tell the organization exists. |
| A member who is admin of one workspace starts an export | `403 FORBIDDEN`. | The organization role decides. |
| "Start export" is chosen twice, or by two admins at once | One export is built. Both get the same pending export. | An organization builds one export at a time. |
| A second admin starts an export while the first admin's is pending | They get the first admin's export. Only the first admin gets the email. | The email goes to the person who started the export. |
| An export finishes at the very moment another start arrives | Rarely, the start answers `409 CONFLICT` with "an export just finished; request again". | The pending export it was about to return is no longer pending. Starting again works. |
| The export ID belongs to another organization | `404 NOT_FOUND`. The app says "This export is not available. Start a new one." | An export is read only within its own organization. |
| A file is uploaded while the export is being built | It is in the archive completely, or not at all. | Everything is read at one moment. |
| A file gets a new version while the export is being built | The archive holds the version that was current at the moment the export read the organization. | Same reason. |
| A file is in the trash | It is not in the archive and not in `assets`. | Only live files are exported. |
| A folder is in the trash | It is not in the manifest's `folders`, and its files are not in `assets`. | The archive holds what is live. |
| A workspace is deleted | It is not in the archive: no entry in `workspaces`, none of its files. | Deleted workspaces are left out with everything in them. |
| A workspace is deleted while the export is pending | The archive holds whatever was live at the moment the export read the organization. | Everything is read at one moment. |
| A file has older versions | Only the current version's content is exported. Its `number` and `parentVersionID` show that earlier versions exist. | An export is a copy of the current state. |
| Two files have the same name in one folder, or names a zip cannot hold | No clash. Entries are named by file ID. | Names live only in the manifest. |
| A file has no status, no tags, no field values | `statusID` is `null`, `tagIDs` is `[]`, `fields` is `{}`. | Empty values are written, not left out. |
| A file's type is not one Talewright knows | Its entry ends in `.bin`. Its real type is in `mime`. | The extension comes from the known types. |
| The organization has no files | The export still becomes ready. The archive holds only `manifest.json`. | An empty organization is a valid export. |
| The uploader of a file has deleted their account | `createdBy.fullName` reads "Deleted user". | Deleted accounts are anonymized everywhere. |
| A file's stored content does not match its digest | The export fails. | A damaged copy is never handed out. |
| An export is still pending after 24 hours | It becomes `failed`. | Something went wrong and it will not finish. |
| The download link is used after 15 minutes | The download is refused. | Links are short-lived. Read the export again for a fresh one. |
| A link is requested seconds before the export expires | The link is valid only until the expiry, less than 15 minutes. With under a second left the export reads `expired`. | A link never outlives its archive. |
| The export expired but the page still shows "Export ready" | "Download export" fetches the state first, finds it expired and starts no download. The section then shows "This export has expired. Start a new one." | The button never reuses an old link. |
| A link was copied before the export expired | It stops working once the archive is deleted. | The archive is gone. |
| The person who started the export is removed from the organization before it is ready | No email is sent. The export still becomes ready, and the owners and admins can download it if they have its ID. | The email goes only to someone who can open the export. |
| The person who started the export is made a plain member before it is ready | No email is sent. The export still becomes ready. | Members do not see exports. |
| The person who started the export deletes their account before it is ready | No email is sent. The export still becomes ready. | There is no address to send it to. |
| The organization is deleted while an export is pending | The export becomes `failed`. No archive is kept and no email is sent. After a restore, start a new one. | Nobody can open an export of a deleted organization. |
| The organization is deleted while an export is ready | The export cannot be read: `404 NOT_FOUND`. Its 7 days keep running. After a restore it can be downloaded again if it has not expired. | A deleted organization answers nobody. |
| The organization is removed for good | Its exports and archives are removed with it. | Nothing of a removed organization is kept. |
| The page is opened from the email by someone signed in as another account | They see "Not found" unless that account is an owner or admin of the organization. | The email's link is a page of the app, not a download. |
| A credential calls an export operation | `403 FORBIDDEN`, reason `SESSION_REQUIRED`. | Exports need a person in a browser. |

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Not signed in. | Sign in. |
| `FORBIDDEN` | 403 | A member starts or reads an export. | Ask an owner or admin. |
| `FORBIDDEN`, reason `SESSION_REQUIRED` | 403 | A credential calls an export operation. | A person does this in a browser. |
| `NOT_FOUND` | 404 | The organization is unknown, deleted or not yours; or the export does not exist in it. | Check the IDs, or start a new export. |
| `CONFLICT` | 409 | The pending export finished at the moment of the request. | Start again. |

An export that could not be built is not an error answer. It is an export in
state `failed`. See [Errors](../reference/errors.md) for the shape of every
error.

## Limits

| What | Value |
| --- | --- |
| Exports being built per organization | 1 |
| How long a ready archive is kept | 168 hours (7 days) from the moment it is ready |
| How long a download link works | At most 15 minutes, never past the archive's expiry |
| How long an export may stay pending | 24 hours, then it is failed |
| Exports per organization over time | No limit |
| Manifest format | `talewright-organization-export`, version 2 |

## Questions and answers

**What is in an export?**
The current version of every live file in every workspace and in the
organization folder, plus `manifest.json` with names, folders, tags,
statuses, fields and version details.

**What is not in it?**
Trashed files and folders, deleted workspaces, older versions, previews,
members, invitations, credentials, sharing settings and the audit trail.

**Who can export?**
Owners and admins of the organization.

**Can I export a single workspace or folder?**
An export always covers the whole organization. To download one folder or a
selection of files, see [Downloading](../files/downloading.md).

**How long does it take?**
It depends on how much there is to copy. You do not have to wait on the
page: you get an email when it is ready.

**How do I know it is ready?**
The section shows "Export ready" by itself, and the person who started it
gets the email "Your {organization} export is ready".

**How long can I download it?**
For 7 days after it became ready. The section shows the date.

**The download link stopped working. Why?**
Each link works for at most 15 minutes. Choose "Download export" again for a
fresh one, as long as the export has not expired.

**The export expired. Can I get it back?**
No. Start a new one.

**The export failed. What now?**
Start a new one. A failed export is not retried by itself.

**Why are the files in the zip named by ID and not by name?**
So that two files with the same name never clash and no name can be invalid
in an archive. `manifest.json` gives each file's name, folder and its path
in the zip.

**How do I rebuild my folder structure from an export?**
Read `folders` to build the tree from `id` and `parentID`. Then place each
entry of `assets` in its `folderID` under its `name`, taking the content
from `currentVersion.path`.

**How do I check that a file arrived intact?**
Compute the SHA-256 of the zip entry and compare it with
`currentVersion.digest`.

**Does an export include older versions of a file?**
No, only the current one. The manifest shows its version number.

**Does an export include the trash?**
No.

**Can two people export at the same time?**
One export is built at a time. The second person gets the export that is
already being built.

**I started the export but my colleague did not get an email. Why?**
Only the person who started it is emailed. Any owner or admin can download
it from the page if they have its address.

**Where is the list of earlier exports?**
There is none. Keep the email or the page's address to return to an export.

**Does exporting change or lock anything?**
No. People keep working while an export is built.

**Can an agent start an export?**
No. A person starts it in a browser. An agent downloads the files it needs
with the file tools.

**Can I import an export into another organization?**
There is no import. The archive is a copy to keep.

**Is the download link safe to share?**
No. Anyone with the link can download the whole archive while it is valid.

**Should I export before deleting an organization?**
If you want to keep the files, yes. A deleted organization cannot be
exported, and after 30 days its files are gone for good.

## Related pages

- [Organizations](organizations.md)
- [Deleting and restoring](delete-and-restore.md)
- [Workspaces](workspaces.md)
- [Files & Assets overview](../files/overview.md)
- [Downloading](../files/downloading.md)
- [Versions and history](../files/versions.md)
- [Trash and restore](../files/trash.md)
- [Statuses](../files/statuses.md) and
  [Fields and tags](../files/fields-and-tags.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

