Import/Export

Prismic provides utilities for importing and exporting documents to and from your repository.

Prismic's Import/Export tool is handy for many use-cases, such as:

• migrating content,
• bulk updates of existing documents,
• importing translations of documents,
• importing new documents,
• and making back-ups.

Prismic's Export tool creates a ZIP file of all published documents in your repository. Here are the steps to perform an export:

1. In your repository, navigate to Settings > Import/Export > Export your document.
2. Click on Export your documents. This will create a downloadable snapshot of your documents.
3. Click the link to download the archive of your documents.
4. The download is a compressed ZIP file. It contains a folder with JSON files for each of your published documents.

If you need an up-to-date Export after you've performed one, click "Done" and click on "Export your document" again. This will generate a fresh snapshot.

An exported JSON filename looks like this:

The hash before the $ character is the filename or document ID.

The import tool accepts a ZIP archive. Select all of the JSON files from an export and compress them together in a new ZIP archive. You can include up to 200 files in an import job. Imports are rate-limited to 10 operations per hour.

Here are the following steps to import one or more new documents to your repository:

1. Prepare each new document as a JSON file according to your custom type for the import, as described in the JSON format section.
2. Select all the JSON files and compress them directly. Do not compress the folder they are in. Directly select all the files and compress them. Give the compressed file any name.
3. In your repository, go to Settings > Import/Export > Import your documents.
4. Click on Choose files and upload the compressed JSON files.
5. Click Import now. All of your documents will be uploaded and added to a new release. You can give a name to the release, or else it will be auto-named.
6. Review your new release before publishing. If anything was not imported correctly, you can either edit the documents directly or delete the release and start again.

Here are the steps to update an existing document:

1. Export the document.
2. Make changes in the exported JSON. Do not change your documents' file names.
3. To re-import documents, select the JSON files and compress them directly. Do not compress the folder they are in. Directly select all the files and compress them.
4. In your repository, go to Settings > Import/Export > Import your documents.
5. Click on Choose files and upload JSON files.
6. Click Import now. All of your documents will be uploaded and added to a new release. You can give a name to the release, or else it will be named automatically.
7. Review your new release before publishing. If anything was not imported correctly, you can either edit the documents directly or delete the release and start again.

To import translated content for an existing document, you need to import JSON files with a naming convention based on the grouplang ID.

The grouplang ID is a common identifier for a document and its translations. A document in the master language and all its translations share the same grouplang ID. You can find the grouplang ID at the end of each JSON file when export documents. It looks like this:

To import translated content for an existing document, you need to import files with this naming convention:

For example: If you want to import an fr-fr translation of an existing en-us document (with the grouplang ID WKq0ph4AACEA4M9B), the JSON file you'll import for the French content needs to be named like this:

The filename must contain the grouplang ID that you can find in the master language document when exporting it.

Also, make sure you have the right locale code set up in the JSON file itself.

You can use the Import and Export feature and some scripting to copy one document to multiple other locales at once. 

• Publish the original document from the Prismic UI
• Export your documents using the Export module (you'll get a ZIP archive containing one JSON file for each published document)

Play the following script on the list of documents you want to duplicate to all locales at once:

• Get the grouplang value from the original document.
• Generate one JSON file for each language you want to duplicate the document.
• In each JSON file, replace the lang value with the target locale code (i.e., "lang": "es-es")
• In each JSON file, insert the grouplang value (the one you grabbed from the original file, i.e.,  "grouplang": "X3dY8hAAACQASEKF")
• Name each generated files following this convention: translate_{grouplang}_{lang}.json. For example, if you need to generate duplicate JSON files for 3 locales, you’ll end up with these files (assuming the group lang ID of the original is X3dY8hAAACQASEKF):

• ZIP the generated files
• Import them using the Import module

Let's say you have a repository with a custom type blog_post that has UID, title, and key text fields.
There are two languages: en-gb and fr-fr where en-gb is the default language.

To import new documents in multiple languages you need to prepare your JSON file in the alternate languages that you'll import.

First, create the files with this naming convention: new_{groupid}_{lang}. Here, groupid is an arbitrary identifier of 16 characters that will be used to match a new document with its translations. Don't use underscore characters in the groupid or else the import will fail.

In our example, filenames should look like:

• new_abcdefghijklmnop_en-gb.json
• new_abcdefghijklmnop_fr-fr.json

Then, add the corresponding fields in the custom type JSON and lang for each one. Please follow the JSON format section to prepare the JSON file for the import.

Here is an example of the new_abcdefghijklmnop_en-gb.json file:

Here is an example of the new_myimports_fr-fr.json file:

1. Export the content to update
2. Modify the JSON files. Make the bulk change(s) you need. For example, you could open the files in a code editor such as Visual Studio Code. Most code editors like this will have find-and-replace functionality to make this straightforward. Don't change any of the documents' file names.
3. Import the updated documents and review the release. Don't forget to re-apply any image cropping or zoom that you had previously as this is lost in the Import and Export process.
4. If all is well, then you just need to do is publish this release and your new updated content will be live!

The API ID of a custom type in the destination repository.

An array of strings representing tags. Even if you are only adding one tag, it must be in an array. Tags that do not already exist in the repository will be created.

The UID is a unique identifier for the document. Each UID must be unique to its custom type.

The value required for the UID field is a string that must not contain any spaces or special characters (only dashes and underscores). If you attempt to import a UID with special characters or spaces, it will be automatically be formatted (spaces are replaced by dashes, and special characters are removed).

If you try to add a document with a UID that is already used on an existing document in the repository, an incremented number will automatically be appended at the end of the UID. (For example, "my-new-page" will automatically become "my-new-page1").

A string containing the content of the key text field.

A string that matches one of the options configured for the select field in the custom type.

If the value provided does not match an available option, no value will be set for the imported content.

A hex color value as a string.

A valid timestamp as a string. If the timestamp format is not valid, no value will be loaded into the field.

A date in the format YYYY-MM-DD as a string. If the date format is not correct, no value will be entered for the field.

Either true or false. This value is boolean, not a string, so it does not require quotation marks.

A number as a string. If the value given is not a number, no value will be imported.

To import a rich text field, you must provide an array of one object per paragraph. Each paragraph has a type property that defines the paragraph's formatting option. Learn about the type options.

Here is a simple example of a rich text field with the API ID of "title". This field takes only a single line of text, which we've defined as a heading1 element.

The following is an example of a multi-paragraph rich text field with the API ID of desc. This assumes that the target field is configured for multiple paragraphs.

The following is an example of a paragraph that contains a link element. The link element is defined with an object in the spans array.

The following is an example of an embed element in a rich text field.

The following is an example of a paragraph section with a hyperlink to an image in the Media Library.

You have a content relationship field with the API ID of category_link. In JSON, there will be two different values id and wioUrl for the object.

An object with two properties:

• id: the ID of the linked document
• wioUrl: a string that takes the format wio://documents/${filename}

To import a content relationship field, the page that you want to link must be already available in your repo.

The following is an example of an image element in a rich text field.

You can bulk upload images from the Media Library UI, or you can import images along with Import jobs. To bulk upload images in the Media Library UI, select all your images and drag and drop them into the Media Library.

There are three ways to reference image files in your import:

• Include images in your ZIP archive
• Reference images in your Media Library
• Include a URL for an image hosted elsewhere

If you include the image in your ZIP archive or link to an external URL, the importer will add the image to your Media Library. If you reference an asset multiple times in one import batch, it will only be added to your Media Library once.

Below is the basic data you need to include in your JSON files to import images without any resizing or cropping options.

To link to images hosted elsewhere, provide the reference URL of the online image in your JSON file.

To link to images hosted elsewhere, in your import JSON, reference the image with a local path.

To use images from your Media Library, provide the URL of the image in your Media Library.

An object with lat and lng properties, each with numbers for their values.

A type property, with a string specifying the type of the embed, and an embed_url property with a URL for the embed.

Refer to a JSON export example of the type of embed you are trying to include to find the embed type.

To link to an internal document, see the following example, which would add a link to an existing document in the repository of the type page with the document ID of V-p_rx4AAB4AmyHa.

To add a link to the web, see the following example.

To link to the media library, see the following example, which would add a link to an existing asset in the repository's Media Library with the ID of V9vHXBgAABgAn9hF.

When linking to a local asset, it is only possible to upload and link to an image file. You must manually upload other file types.

The following example would add a link to a new asset to be loaded into the repository's Media Library. You need to include the asset file in the import ZIP file.

The import module will upload the asset into the Media Library and add the link to this field.

Let's say that you have a repeatable group field with the API ID of "links-group". Inside that group, you have a key text field with the API ID of "label" and a link field with the API ID of "link".

The following example would add two sets of links with labels.

Slices are content blocks that can be freely organized within a Slice Zone. A single Slice can contain several repeatable and non-repeatable items.

If you look at the exported JSON for a Slice that contains several items within a group, you’ll see the following property for each item.

If you want to import several items within a Slice, this property should just contain the Slice ID like this:

The hash after the $ will be automatically assigned by the importer. Other than that, refer to the exported JSON for each of your Slice types to see what the import JSON code needs to be imported.