Custom Types API

This guide will teach you the basics of how to query the Custom Types API, which you can use to version and update your Custom Types.


📦 Beta Access

The Custom Types API is currently in the BETA stage of its development cycle and because of this fact, you must request activation of this feature on your repo. You can do so by contacting the team on the Forum as described here.

What is it?

The custom types API is a long-requested tool that will allow you to hit an endpoint to retrieve and post your full Custom Types and/or Slices i.e. JSON content models. The use cases for this tool include programmatically creating backups for your custom types, automatic creation of Typescript Types, and building your Gatsby Schema dynamically.

To do this you will need to perform HTTPS Requests using something like Curl or similar. You can do this by hitting our Custom Types API Endpoint https://customtypes.prismic.io, passing the route of exactly what you need, and adding the authentication in the headers of your request. You can see full examples of this below.

How do I build a Custom Type?

If you're new to Prismic and want to learn how to easily build Custom Type JSON, then check out our Introduction to Custom Type Building article.


Authentication

To authenticate your request with the Custom Type API you will need 2 things. Your repository ID & bearer access token.

Be Careful!

Your bearer access tokens carry many privileges, so be sure to keep them secure! Do not share your secret bearer access tokens in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your repository ID & bearer access token as the basic auth values. You do not need to provide a password. You can provide this information to your request in headers as shown below:

Copy
--header 'repository: repo-name' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Permanent Token (Recommended)

This is the recommended token that you should use if, for example, you're building an app to backup your Custom Types. You can find this token information in the API & Security section of your repository settings. Here you will be able to generate a new access token, you can use multiple bearer access tokens for different applications, this is recommended.

The API & Security section of a Prismic repository
Navigate to the Custom Types API tab to find your repo ID and generate a bearer access token.

User Session Token (Advanced)

This more advanced and complicated token is one you might use in a case where you want to track which repository member made changes and when. One complication of this token is that since it's based on the user session it will expire and therefore needs to be updated once it does if you wish to make changes.

To retrieve this token you will need to perform an HTTPS request to the Prismic Authentication Server. You'll need to send a POST request to the https://auth.prismic.io/login route. Within the body of this request, you'll need to provide the email & password of the relevant Prismic account.

Copy
curl --location --request POST 'https://auth.prismic.io/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "john.doe@prismic.io",
    "password": "yourPassword"
}'

Expected response:

200 OK containing the User Session Token.


Custom Types Status

One thing you need to be aware of in the JSON response of your Custom Types is the Status field. The Status is a boolean field that indicates whether the Custom Type is currently disabled or active for use in the Prismic Repository.

This is important to know in case you don't want to make a Custom Type active right away or can't seem to find a Custom Type once you've pushed it.

Active Custom Types

"status": true

Active Types appear like above Prismic Dashboard and like below in the JSON response:
Copy
{
    "id": "page",
    "label": "Page",
    "repeatable": true,
    "json": {
        "Page": {
            "uid": {
                "type": "UID",
                "config": {
                    "label": "UID",
                    "placeholder": "unique-identifier-eg-homepage"
                }
            }
        }
    },
    "status": true
}

Disabled Custom Types

"status": false

Disabled Types appear like above Prismic Dashboard and like below in the JSON response:
Copy
{
    "id": "about_page",
    "label": "About Page",
    "repeatable": true,
    "json": {
        "Page": {
            "uid": {
                "type": "UID",
                "config": {
                    "label": "UID",
                    "placeholder": "unique-identifier-eg-homepage"
                }
            },
        }
    },
    "status": false
}

Retrieve Custom Types (GET requests)

Below you can see examples of how to use GET requests to retrieve all of the Custom Types in your repo, all Custom Types of a specific Type, all Shared Slices, and specific Shared Slices.

All Custom Types

This one is quite simple. Here you will specify the location, the Custom Types API Endpoint with the /customtypes route, and the authentication as headers.

Copy
curl --location --request GET 'https://customtypes.prismic.io/customtypes' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

Expected result:

200 OK status code with all the custom types from the repository returned in a JSON array.

Custom Type by ID

To get a certain type of Custom Type we perform a similar query to the one above, but we add the /customtypes/{customTypeId} to the route. This is the API ID of the Custom Type which you can find in your Prismic repository.

Custom Types Screen in Prismic
You can find the API ID of your Custom Types in the Custom Types tab of your Prismic repo.
Copy
curl --location --request GET 'https://customtypes.prismic.io/customtypes/page' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

Expected result:

200 OK status code with the specified custom type returned as a JSON object.

All Shared Slices

Another simple one. To get all Shared Slices (i.e. Slices created with Slice Machine) you will specify the location, the Custom Types API Endpoint with the /slices route, and the authentication as headers.

Shared Slices

Shared Slices are available of Slice Machine enabled repositories only. Reach out to the team to activate this.

Copy
curl --location --request GET 'https://customtypes.prismic.io/slices' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

Expected result:

200 OK status code with all your Shared Slices from the repository returned in a JSON array.

Slice by ID

To get a specific Shared Slice we perform a similar query to the one above, but we add /slices/{sliceId} to the route. This is the API ID of the Shared Slice which you can find in your Prismic repository in the Custom Type builder where you add new Slices, under the Shared Slice tab.

Enter any of your Custom Types, select + New Slice and you will find the Shared Slices tab.
Copy
curl --location --request GET 'https://customtypes.prismic.io/slices/TextSlice \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

Expected result:

200 OK status code with the specified Shared Slice returned as a JSON object.


Add Custom Types (POST requests)

Below you can see examples of how to use POST requests to send Custom Types and Shared Slices to your repository. These POST requests are slightly different than the GET requests as you can't make group edits.

*You will only be able to send singular Custom Types by ID. You will not need to specify the Custom Type ID or Slice ID in these requests as that information will be read from the JSON model.

How do I build a Custom Type?

If you're new to Prismic and want to learn how easily build Custom Type JSON, then check out our Introduction to Custom Type Building article.

Insert a new Custom Type

The /customtypes/insert route is for adding new Custom Types to your repository. You will specify the Custom Types API Endpoint with the /customtypes/insert route, the authentication, and the Custom Type JSON as shown below:

Copy
curl --location --request POST 'https://customtypes.prismic.io/customtypes/insert' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "page",
    "label": "Page",
    "repeatable": true,
    "json": { JSON-OF-THE-CUSTOM-TYPE },
    "status": true
}'

Expected result:

201 (Created) code: This means the Custom Type was successfully created.
409 code: This means a Custom Type with the same ID already exists in the repository.

Update a Custom Type

The /customtypes/update route is for updating Custom Types in your repository. You will specify the Custom Types API Endpoint with the /customtypes/update route, the authentication, and the Custom Type JSON as shown below:

Copy
curl --location --request POST 'https://customtypes.prismic.io/customtypes/update' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "page",
    "label": "Page",
    "repeatable": true,
    "json": { JSON-OF-THE-CUSTOM-TYPE },
    "status": true
}'

Expected result:

204 No Content code: This means the Custom Type was successfully updated.

422 code: This means no Custom Types with that ID exist in the repository, and so it cannot be updated.

Insert a new Shared Slice

The /slices/insert route is for adding new Shared Slices to your repository. To do so simply specify the Custom Types API Endpoint with the /slices/insert route, the authentication, and the Shared Slice JSON as shown below:

Copy
curl --location --request POST 'https://customtypes.prismic.io/slices/insert' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "image_gallery",
    "type": "SharedSlice",
    "name": "ImageGallery",
    "description": "ImageGallery",
    "variations": [
        {
          VARIATIONS-JSON
        }
    ],
    "imageUrl": "https://images.prismic.io/tutorial-series/shared-slices/image_gallery/preview.png"
}'

Expected result:

201 (Created) code: This means the Shared Slice was successfully created.

409 code: This means a Shared Slice with the same ID already exists in the repository.

Update a Shared Slice

The /slices/update route is for updating Shared Slices in your repository. To do this you will need to specify the Custom Types API Endpoint with the /slices/update routes, the authentication, and the Shared Slice JSON as shown below:

Copy
curl --location --request POST 'https://customtypes.prismic.io/slices/update' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "image_gallery",
    "type": "SharedSlice",
    "name": "ImageGallery",
    "description": "ImageGallery",
    "variations": [
        {
          VARIATIONS-JSON
        }
    ],
    "imageUrl": "https://images.prismic.io/tutorial-series/shared-slices/image_gallery/preview.png"
}'

Expected result:

204 No Content code: This means the Shared Slice was successfully updated.

422 code: This means no Shared Slices with that ID exist in the repository, and so it cannot be updated.


Remove Custom Types (DELETE requests)

Below you can see examples of how to use DELETE requests to remove Custom Types and Shared Slices from your repository. With DELETE requests you can't do group deletions, you MUST specify the Custom Type's or Shared Slice's ID.

Remove a Custom Type

To remove a Custom Type you will need to make a DELETE request. Simply specify the Custom Types API Endpoint with the /customtypes/{customTypeId} routes, and the authentication as shown below:

Copy
curl --location --request DELETE 'https://customtypes.prismic.io/customtypes/page \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

Expected result:

204 No Content code: This means the Custom Type was successfully deleted.

Remove a Shared Slice

To remove a Shared Slice you will need to make a DELETE request. Simply specify the Custom Types API Endpoint with the /slices/{sliceId} routes and the authentication as shown below:

Copy
curl --location --request DELETE 'https://customtypes.prismic.io/slices/TextSlice \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

Expected result:

204 No Content code: This means the Shared Slice was successfully deleted.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.