Import/Export

Announcing the deprecation of Import/Export

Import/Export will be deprecated on April 30, 2024. It will be replaced by the new Migration API.

For more information, see the FAQ.

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.

The Import/Export tool is available starting on the Medium Plan. More about pricing.

Export tool

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:

Copy
Xr6nORAAAChEyddW$aefa2a44-fa37-46dc-a4fd-7dbdccdd55a2.json

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

Limitations of Export

  • You can not export releases, drafts, or archived documents.
  • You can not use the Export tool to export custom types, images, or files.
  • We do not recommend this tool to transfer content between the environments or to clone your repository.
  • You can not selectively export documents. All documents are exported.

Import tool

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.

Limitations of the Import tool

Imports must be a ZIP file containing one JSON file for each document.

  • You can import up to 200 documents.
  • Import jobs are limited to 10 per hour.
  • The ZIP file size limit is 100MB.
  • The individual JSON file limit is 250000 bytes.
  • For media files, you can only import image types.
  • You cannot add copyright, private notes, image positioning, or crops to images.
  • When pointing to a media file (media URL or local file path) in your import JSON files, those files will be added to the Media Library of your repository as soon as you launch the Import job. If you delete the Import release after launching the Import job, media files will remain in the Media Library of your repository. Retrying Import jobs several times could lead to duplicates in the Media Library. Find out how to avoid duplicates by referring to the images section.
  • The import automatically regenerates thumbnails based on the `origin` data for the main image specified in the Import JSON file. Thus, the image data you provide in Import JSON files for responsive views of a given image field are ignored in the importing job.
  • Any content relationship or link to another Prismic document will need to be re-added after the import has been done.

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.

Be careful when you publish

Once an Import release is published, there is no bulk rollback. Make sure to do the necessary testing before publishing the release.

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.

Translate content in bulk

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:

Copy
"grouplang": "Xr6nORAAAChEyddY"

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

Copy
translate_{grouplang}_{lang}

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:

Copy
translate_WKq0ph4AACEA4M9B_fr-fr.json

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):
Copy
translate_X3dY8hAAACQASEKF_fr-fr.json
translate_X3dY8hAAACQASEKF_es-es.json
translate_X3dY8hAAACQASEKF_it-it.json
  • ZIP the generated files
  • Import them using the Import module

Troubleshooting Singletons

You might see an error when trying to import a translation for a document that is of a Singleton type. In that case, switch the type from Singleton to Repeatable. Once you're done with the import, you can change it back to Singleton. 

Import new content in multiple languages

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:

Copy
{ 
  "uid": "post",
  "post_title": [
    { "type": "heading1", "content": { "text": "New blog in english", "spans": [] } }
  ],
  "key_text": "This is my Key text in English",
  "type": "blog_post",
  "tags": [],
  "lang": "en-gb"
}

Make sure before importing a set of the localized documents, the corresponding languages/locales are available in your repository. The value of lang in JSON must match the language/locale code in your repository.

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

Copy
{ 
  "uid": "post",
  "post_title": [
    { "type": "heading1", "content": { "text": "New blog in french", "spans": [] } }
  ],
  "key_text": "This is my Key text in french",
  "type": "blog_post",
  "tags": [],
  "lang": "fr-fr"
}

Import a bulk update

  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!

Limitations

  • Draft, Archived, and document in releases aren't included in the process.
  • You will lose image positioning and zoom of images during this process. You will need to re-apply any image cropping and zoom after running the import. 

JSON format

We recommend that you publish and export a sample document to get the full JSON object for that custom type. You can then use this JSON file as your template when you generate your JSON files for import.

Type

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

Copy
"type": "post"

Tags

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.

Copy
"tags": ["foo", "bar"]

UID

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

Copy
"uid": "my-unique-identifier"

Key text

A string containing the content of the key text field.

Copy
"subtitle_text": "This is my subtitle text!"

Select

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.

Copy
"author": "John Doe"

Color

A hex color value as a string.

Warning: Even if an invalid color code is given, it will still be imported.

Copy
"title_color": "#62a9c4"

Timestamp

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

Copy
"event_time": "2016-09-15T22:00:00+00:00"

Date

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.

Copy
"release_date": "2016-09-16"

Boolean

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

Copy
"my_boolean": true

Number

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

Copy
"price": "19"

Rich text

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.

Warning: The content you input will be imported regardless of whether or not it complies with the configuration of the rich text field. If your rich text field is defined in the custom type only to have the type heading1, the importer will not prevent you from uploading text of the type paragraph or heading2 to that field.

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.

Copy
"title": [
  {
    "type": "heading1",
    "content": {
      "text": "This is the document title",
      "spans": []
    }
  }
]

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.

Copy
"desc": [
  {
    "type": "heading1",
    "content": {
      "text": "This is my section title",
      "spans": []
    }
  },
  {
    "type": "paragraph",
    "content": {
      "text": "Here is the text for that section.",
      "spans": []
    }
  }
]

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.

Copy
{
  "type": "paragraph",
  "content": {
    "text": "Donec quis dui at dolor tempor interdum.",
    "spans": [
      {
        "type": "hyperlink",
        "start": 0,
        "end": 40,
        "data": {
          "url": "https://prismic.io",
          "preview": {
            "title": "https://prismic.io"
          }
        }
      }
    ]
  }
}

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

Copy
{
  "type": "embed",
  "data": {
    "type": "video",
    "embed_url": "https://www.youtube.com/watch?v=y6y_4_b6RS8"
  },
  "content": {
    "text": "",
    "spans": []
  }
}

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

Copy
{
  "type": "paragraph",
  "content": {
    "text": "Cras iaculis ultricies nulla.",
    "spans": [
      {
        "type": "hyperlink",
        "start": 5,
        "end": 12,
        "data": {
          "wioUrl": "wio://medias/V9vEGhgAABgAn8s7",
          "url": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg",
          "kind": "image",
          "id": "V9vEGhgAABgAn8s7",
          "height": "480",
          "width": "640",
          "size": "41298",
          "date": "09/16/16 10:03",
          "name": "technics-q-c-640-480-7.jpg",
          "preview": {
            "title": "technics-q-c-640-480-7.jpg",
            "image": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg"
          }
        }
      }
    ]
  }
}

Content relationship

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 filename is the value that comes before $ sign in an exported file, for example, if the JSON file is called YEoT0BEAACMA6dKT$954b6ddd-31e5-45a1-8b60-d215f0e17a5e.json, then the id is YEoT0BEAACMA6dKT.

Copy
"category_link": {
    "id": "YEoUChEAACMA6dOX",
    "wioUrl": "wio://documents/YEoUChEAACMA6dOX"
  },

Image

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

Copy
{
  "type": "image",
  "content": {
    "text": "",
    "spans": []
  },
  "data": {
    "origin": {
      "url": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg"
    }
  }
}

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.

Copy
{
  "image_field1":{
    "origin":{
      "url":"https://images.ladepeche.fr/api/v1/images/view/5c37588b3e454652f74478af/large/image.jpg"
    }
  }
}

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

Copy
{
  "image_field2":{
    "origin":{
      "url":"toto.jpg"
    }
  }
}

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

Copy
{
  "hero_image":{
    "origin":{
      "url":"https://prismic-io.s3.amazonaws.com/slicemachine-blank/6b2bf485-aa12-44ef-8f06-dce6b91b9309_dancing.png"
    }
  }
}

Geopoint

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

Copy
"location": {
  "position": {
    "lat": 47.6205063,
    "lng": -122.3492774
  }
}

Embed

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.

Copy
"soundcloud-player": {
  "type": "rich",
  "embed_url": "https://soundcloud.com/seacastle-1"
}

Links

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.

Copy
"document_link": {
  "id": "V-p_rx4AAB4AmyHa",
  "mask": "page"
}

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

Copy
"web_link": {
  "url": "http://seacastleband.com"
}

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.

Copy
"media-link": {
  "wioUrl": "wio://medias/V9vHXBgAABgAn9hF",
  "url": "https://prismic-io.s3.amazonaws.com/import-test%2F0fcf1760-dce7-4d12-8e20-a3e11472c797_city-q-c-640-480-4.jpg",
  "kind": "image",
  "id": "V9vHXBgAABgAn9hF",
  "height": "480",
  "width": "640",
  "size": "34769",
  "date": "09/16/16 10:04",
  "name": "city-q-c-640-480-4.jpg"
}

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.

Copy
"media_link": {
  "url": "image.png",
  "kind": "image",
  "name": "image name",
  "id": "",
  "size": "",
  "height": "",
  "width": ""
}

Group

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.

Copy
"links-group": [
  {
    "label": "Link This!",
    "link": {
      "url": "http://css-tricks.com"
    }
  },
  {
    "label": "Link That!",
    "link": {
      "url": "http://jurassicpark.com"
    }
  }
]

Slices

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.

Copy
"key": "alternated-highlights$b0b1de36-ffb7-406d-86ca-0855dae17c7e", 

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

Copy
"key": "alternated-highlights",

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.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.