Import and export
Download your capsules as Markdown, what an export leaves out, how a Symbol export restores, and how to retry an import safely.
Settings → Import & Export downloads your capsules as a .zip of Markdown files, and brings a download back in. You can export your personal workspace, one Type, or an organization you administer.
What an export holds
Each capsule is one Markdown file, in a folder named after its Type. The top of each file lists its title, alias, tags, collections, project and field values. A file named symbol-manifest.json describes every Type: its name, guidance, fields and collections.
Some things are left out on purpose:
- Log Types and their capsules. A log's entries are not part of an export, so a download can hold fewer capsules than your account total. The Export panel says so before you download.
- Encrypted capsule contents. Symbol only holds them encrypted, so the file says the capsule is encrypted and carries no body.
- Archived capsules and attachments. Only live content is exported, and attachment files are not.
References keep their meaning
A reference field value is written at the address its capsule has now. A reference written before a Type was renamed, a capsule was moved, or an alias changed still points at the same capsule when you restore the export.
The Type a reference field is limited to is written the same way. After you rename a Type, the field names its new address. After you merge one Type into another, the field names the Type it was merged into, even if its capsules later moved somewhere else. A reference whose capsule now sits in another Type than the field accepts is written with that capsule's full address, and the import tells you it will leave that value out.
Sometimes an export cannot tell which Type a field means, for example when the Type it named was deleted without a record of where it went, or is one you cannot open. The export then keeps the field exactly as it was and marks it. Importing that export is refused before anything is created, and the message names the Type, the field and the old address. Fix the field's Type in the account it came from and export again, or edit that field in symbol-manifest.json yourself and remove its entry from the Type's unresolved_reference_constraints list.
A field still limited to a Type that was deleted together with its capsules cannot be identified either, so it blocks the restore of the whole export until you change or remove that field's limit.
Restoring an export
Import & Export previews a Symbol export first. The preview settles where each Type lands. When you already have a Type with the same address, the restored copy gets its own address, and every reference in the export points at the copy. The preview also checks every Type it would create, so a field limited to a Type neither the export nor your workspace has is reported before anything is imported, not halfway through.
Exports downloaded before this check existed cannot say whether a field limited to a Type outside the export meant your workspace's Type of that address. When your workspace has one, the preview says which field will be matched to it by address alone. When it has none, that Type cannot be restored until you fix the field.
An export that marks a field it could not identify needs the current version of Symbol to import. An older importer ignores the mark.
Trying an import again
An import creates its rows one at a time, so a file with one invalid row still imports the others and lists the row that failed, with the reason. Trying again never copies the rows that already arrived:
- Try again repeats the same import. Rows it already created are listed as already imported and are not created a second time. Only the rows that failed before are tried again.
- Corrected file takes a fixed copy of the same file. Correct only the rows that failed and keep the others and the mapping as they were. The import then creates just the corrected rows. Changing or removing a row that was already imported is refused before anything is written, so the two copies cannot drift apart.
Importing the same files into the same place again is recognized the same way, even later and from a fresh start: nothing is created twice, and the report says how many rows were already imported. When you do want a second copy, choose Import again as new copies in that report. The files are reviewed and imported again as a separate import, and a Symbol export lands in new Types of its own, next to the ones you already have.
The report keeps the two counts apart: how many capsules this attempt created, and how many rows an earlier attempt had already imported. A row that an earlier attempt created, and that you have since deleted or can no longer open, is not created again.
When a row asks for an alias another capsule already has, the row is still imported, without the alias, and the report says so on that row. The capsule that holds the alias is left unchanged. A Type that builds each alias from a field still refuses a row whose alias is taken, because that row would duplicate an existing capsule.
A Symbol export with several Types imports one Type at a time. If you come back to an interrupted export after its preview has expired, preview it again from the same import: the preview renews the run, keeping where each Type lands and the capsules already imported, and references to them still resolve.
Through the API or your AI assistant, every import answers with an import_key. Send it again to retry, including with failed rows corrected, and send a new one only to import the same rows again as new copies on purpose. A new copy of a Symbol export needs a new import_run_id as well as new keys, whether or not you preview it first, because the same export is otherwise recognized as the run it already belongs to. Each call of a split import, one per chunk or per Type of an export, has its own key. See Retrying an import.