Migration API Technical Reference
The Migration API endpoint allows developers to upload documents to a Prismic repository.
The Migration API endpoint allows developers to create and update documents in a Prismic repository.
Usage
The data format for the Migration API is described below. The format follows the response format from the Document API, though the Document API includes properties that are unnecessary for the Migration API.
If you query a document object from the Document API and then send it to the Migration API, the Migration API will ignore the unnecessary properties and accept the rest.
Documents will be created as drafts, which you can publish in your repository.
By default, documents created or updated via the Migration API will be added to a migration release, accessible from the Migration Releases
tab in your repository.
To include media (images, files, videos) in your documents, you will need to upload the media to your repository (either via the UI or the Asset API) and then fetch the ID for the media asset to include in your request to the Migration API.
We recommend saving the id
from the POST response for each document upon creation, as you will also require this id
to make updates to existing documents.
Limits
- Each request to the API can contain one document, which will be saved in the repository as a draft.
- Requests are limited to one per second.
Example request body
Here is an example request body with all properties:
{
"title": "Example Document",
"uid": "example-document",
"type": "example_type",
"lang": "en-US",
"tags": ["Red", "Yellow", "Blue"],
"alternate_language_id": "ZRFHsxIAAFYAsY--",
"data": {
"example_boolean": false,
"example_color": "#e0dbfd",
"example_date": "2024-12-23",
"example_timestamp": "2023-02-20T01:12:12+0100",
"example_integration": {
"id": "3"
},
"example_shopify_integration": {
"id": 7505689739510
},
"example_embed": {
"embed_url": "https://www.youtube.com/watch?v=S26CHpcD2zk"
},
"example_geopoint": {
"latitude": "-9",
"longitude": "-160"
},
"example_image_1": {
"id": "ZMgV5hAAAEADVsPS"
},
"example_image_2": {
"id": "ZMgV5hAAAEADVsPS",
"alt": "Example alt text",
"copyright": "Example copyright info",
"dimensions": {
"width": 800,
"height": 200
},
"edit": {
"x": 2,
"y": 28,
"zoom": 3,
"background": "#ffffff"
},
"mobile": {
"id": "ZMgV5hAAAEADVsPS",
"alt": "this is some alt text",
"copyright": "some copyright info"
}
},
"example_web_link": {
"link_type": "Web",
"text": "Click Here",
"url": "http://www.prismic.io"
},
"example_document_link": {
"link_type": "Document",
"id": "ZMI65RQAADkECUFM"
},
"example_media_link": {
"link_type": "Media",
"id": "ZMgV5hAAAEADVsPS"
},
"example_number": 23,
"example_select": "Apples",
"example_content_relationship": {
"link_type": "Document",
"id": "ZMI65RQAADkECUFM"
},
"example_group": [
{
"key_text_description": "Lorem",
"number_price": 55
},
{
"key_text_description": "Ipsum",
"number_price": 60
}
],
"example_rich_text": [
{
"type": "heading3",
"text": "This is a heading3",
"spans": []
},
{
"type": "paragraph",
"text": "Bold and italic example.",
"spans": [
{
"start": 0,
"end": 3,
"type": "strong"
},
{
"start": 8,
"end": 14,
"type": "em"
}
]
},
{
"type": "image",
"id": "ZPrkIhYAACcAYvyB",
"alt": "Example alt text",
"copyright": null,
"dimensions": {
"width": "512",
"height": "512"
}
},
{
"type": "embed",
"oembed": {
"embed_url": "https://prismic.io/"
}
}
],
"//": "The default slice zone is 'slices'",
"slices": [
{
"variation": "default",
"primary": {
"example_number": 11
},
"slice_type": "example_slice_type_1"
}
],
"example_slice_zone": [
{
"variation": "example_variation",
"items": [
{
"example_select": "Dog"
}
],
"slice_type": "example_slice_type_2"
}
]
}
}
Headers
These headers should be included with each request to the Migration API.
Authorization | A permanent token or user session token from the Authentication API. |
repository | The repository ID (e.g. |
x-api-key | A key required for accessing the Migration API Beta. Available demo keys are:
|
Methods
POST
Create a document.
https://migration.prismic.io/documents
The JSON body of every POST request must contain the following required properties:
title
type
uid
(if present on type)lang
data
alternate_language_id
(if creating a localized version of a singleton type)
PUT
Update a document.
https://migration.prismic.io/documents/:id/
:id
is the ID for an existing document.
The JSON body of every PUT request must contain the following required properties:
uid
(if present on type)data
The body can also include the following optional properties:
title
tags
The following properties cannot be modified on PUT requests and will be ignored if they are included in the body:
type
lang
alternate_language_id
Body
title | A display title to appear in the document list. |
type | ID of the document’s type. Required for POST requests. |
lang | The document’s locale. |
data | An object containing the content of the document. Each key in the object should be a field or slice zone, and each value should be the content. (See the structure of the fields below.) |
tags | An optional list of tags for the document. (Existing tags will be deleted if this property is omitted in a PUT request.) |
uid | The document’s UID, which must be unique to that type. Required if present on the type and disallowed if absent on the type. |
alternate_language_id | An optional ID for the document for which you are creating a translation. |
Data
The data
property represents the content of the document. Each key in the data object should be a field
or slice zone
on the document type, and the value should be the content.
The content of data
must conform to the structure of the document type.
Boolean: null | boolean
If the field has a default value configured, the default value will be used for null values.
Color: null | string
The string must be a hexadecimal color value.
Content relationship: object
Same as the value for a link with a link_type
of "Document"
.
Date: null | string
The string must match the format YYYY-MM-DD
.
Embed: object
The object can optionally contain an embed_url
property with a URL as its value. Other properties will be ignored.
Geopoint: object
An empty object or an object with latitude
and longitude
properties, each with a value string representing a number. The value of latitude
must be between -90 and 90. The value of longitude
must be between -180 and 180.
Group: array
An array of field objects.
Image: object
An object with the required property id
and optional properties alt
, copyright
, dimensions
, edit
, x
, y
, zoom
, and background
.
id string (required) | A string that exactly matches the ID of an exiting image in Prismic’s media library. |
alt string | The alt text for the image. |
copyright string | Copyright information for the image. |
dimensions object | An object with optional |
edit object | Parameters for editing the image. The object can
contain: |
The image object can also contain thumbnail properties. The key should be the name of the thumbnail and the value should be an object with properties as described in the table above.
Integration: string | number
The ID of an item from your integration.
For shopify integration, the ID comes from your Shopify catalog. For Custom API format, the ID property is defined by the endpoint and duplicated in blob
. See the Integration docs for more information.
Key text: string
A string of text.
Link: object
An object with the required property link_type
and conditional properties depending on the type.
link_type string (required) | One of |
id string | Required if |
url string | Required if |
target string | Where to open the linked URL (optional). Only
accepts |
text string | The optional display text of the link |
Number: null | number
Value must conform to max
and min
if either is defined in the type.
Rich text: array
An array in which each object represents a block element.
A rich text field must contain an array of content blocks. Every block must have a type
property with one of the following values:
"paragraph"
"o-list-item"
"list-item"
"heading1"
"heading2"
"heading3"
"heading4"
"heading5"
"heading6"
"preformatted"
"embed"
"image"
Every block except for those with a type of embed or image can have the following properties:
text string (required) | The text content of the block. |
spans array | An array of objects describing inline markup. Each
object must have a type with the value of either
|
direction string | Value can only be |
oembed object | Required only for blocks with a |
Blocks with a type of "image"
must have the properties defined for the image field.
Select: null | string
If value is a string, the string must match one of the options defined in the type. If the field has a default value configured, it will be used for null values.
Slice zone: array
Each slice zone property must be an array of zero or more slice objects. By default, all types in Prismic have a slice zone property called slices
, but the developer can change the name of the slice zone and add other slice zones.
Each slice object must have the following properties:
slice_type string (required) | The ID of the slice type (e.g. |
variation string (required) | Must match one of the variations defined in the
configuration for the slice type, even if there is
only one variation. The default variation for slice
types is called |
id string | A optional string in the following format:
|
slice_label string | A label that will appear in the Document API
response. If omitted, it will be set to |
primary object | An object containing the fields of the slice. |
items array | An array of objects containing the fields of the repeatable zone of the slice (deprecated). |
Timestamp: null | string
The string must match the format YYYY-MM-DDTHH:MM:SS+0000
.
Errors
In addition to an error code, detailed error messages are displayed in the JSON body of the response. Enable your user agent to receive the error response body.
[
{
"property": "data.richtext.2.type",
"value": "heading2",
"error": "Invalid block type. Supported block types are: paragraph, embed"
}
]