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 FORBIDDENwithdetails.reasonSESSION_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
202with the export in statepending. 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>.
- a workspace file at
<extension>comes from the file's type, for examplepng,pdfortxt. A file of an unknown type getsbin.- 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.jsoncarries 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": []
}
}
formatis alwaystalewright-organization-exportandversionis2.requestedAtis when the export was started.workspaceslists the live workspaces in the order they were created.libraryhas the same five lists as a workspace, for the organization folder.assetsare the files, in the order they were created.folderIDis the folder the file is in, ornullat the top level.tagIDsare the file's tags. The names are in the same workspace's or the organization folder'stags.statusIDis the file's status, ornullwithout one. The statuses are in the same workspace's or the organization folder'sstatuses.fieldsholds 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 asYYYY-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,descriptionandcaptionare the file's texts, ornull.currentVersiondescribes the content in the archive: the version's ID and number, the version it replaced (parentVersionID,nullfor a first version), itsdigest(sha256:and 64 hexadecimal characters), its size in bytes, when and by whom it was made, itspathin the archive and its type (mime).
foldersgives each live folder's ID, name and parent (parentID,nullat the top level). The folder tree is rebuilt from these.tagslists every tag of that workspace or the organization folder by name, also tags no file uses.statuseslists 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.fileFieldslists that workspace's or the organization folder's own fields, each with itskind(text,number,date,selectormultiSelect) 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
readyorfailed. A ready export becomesexpired. 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
Authorizationheader. Do not share it. - The answer is the zip file, with type
application/zipand the nameexport-<exportID>.zip.
Retention
- A ready archive is kept for 168 hours, which is 7 days, counted from the
moment it became ready.
expiresAtis that moment. - From
expiresAtthe export reads asexpiredand 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."
- Choose "Start export".
- 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.
- When it is ready the section shows "Export ready: {size}, available until {date}." and the button "Download export".
- "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:
{
"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://..."
}
POSTtakes no body and answers202.GETanswers200. EachGETof a ready export carries a freshdownloadURL.- To wait for an export, read it again every few seconds until
stateis no longerpending.
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
| 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 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.
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.