Talewright Docs Open the app

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

ActionOwnerAdminMemberSessionCredential
Start an exportYesYesNoYesNo
Read an export's stateYesYesNoYesNo
Download a ready exportYesYesNoYesNo
Get the "export ready" emailThe 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.

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:

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

StateMeaningcompletedAtexpiresAtsizeBytesdownloadURL
pendingBeing built.nullnullnullnull
readyThe archive can be downloaded.setsetsetset
failedIt could not be built. Start a new one.setnullnullnull
expiredThe archive's 7 days are over and it is deleted.setsetsetnull
  • 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.

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:

LineWhen
"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:

MessageWhen
"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.

OperationCapability IDAccess
POST /v1/organizations/{organizationID}/exportsorganizations.exports.createsession only
GET /v1/organizations/{organizationID}/exports/{exportID}organizations.exports.getsession only

Both answer with the export:

{
  "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:

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 and MCP.

Edge cases

SituationWhat happensWhy
A member starts or reads an export403 FORBIDDEN.Exports are for owners and admins.
Someone outside the organization starts or reads an export404 NOT_FOUND.Outsiders cannot tell the organization exists.
A member who is admin of one workspace starts an export403 FORBIDDEN.The organization role decides.
"Start export" is chosen twice, or by two admins at onceOne 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 pendingThey 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 arrivesRarely, 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 organization404 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 builtIt 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 builtThe archive holds the version that was current at the moment the export read the organization.Same reason.
A file is in the trashIt is not in the archive and not in assets.Only live files are exported.
A folder is in the trashIt is not in the manifest's folders, and its files are not in assets.The archive holds what is live.
A workspace is deletedIt 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 pendingThe archive holds whatever was live at the moment the export read the organization.Everything is read at one moment.
A file has older versionsOnly 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 holdNo clash. Entries are named by file ID.Names live only in the manifest.
A file has no status, no tags, no field valuesstatusID is null, tagIDs is [], fields is {}.Empty values are written, not left out.
A file's type is not one Talewright knowsIts entry ends in .bin. Its real type is in mime.The extension comes from the known types.
The organization has no filesThe 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 accountcreatedBy.fullName reads "Deleted user".Deleted accounts are anonymized everywhere.
A file's stored content does not match its digestThe export fails.A damaged copy is never handed out.
An export is still pending after 24 hoursIt becomes failed.Something went wrong and it will not finish.
The download link is used after 15 minutesThe download is refused.Links are short-lived. Read the export again for a fresh one.
A link is requested seconds before the export expiresThe 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 expiredIt 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 readyNo 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 readyNo 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 readyNo email is sent. The export still becomes ready.There is no address to send it to.
The organization is deleted while an export is pendingThe 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 readyThe 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 goodIts 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 accountThey 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 operation403 FORBIDDEN, reason SESSION_REQUIRED.Exports need a person in a browser.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in.Sign in.
FORBIDDEN403A member starts or reads an export.Ask an owner or admin.
FORBIDDEN, reason SESSION_REQUIRED403A credential calls an export operation.A person does this in a browser.
NOT_FOUND404The organization is unknown, deleted or not yours; or the export does not exist in it.Check the IDs, or start a new export.
CONFLICT409The 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 for the shape of every error.

Limits

WhatValue
Exports being built per organization1
How long a ready archive is kept168 hours (7 days) from the moment it is ready
How long a download link worksAt most 15 minutes, never past the archive's expiry
How long an export may stay pending24 hours, then it is failed
Exports per organization over timeNo limit
Manifest formattalewright-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.

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.