Go to prismic.ioDeveloper Docs

Types API

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

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

What is it?

The Types API is a tool that allows you to hit an endpoint to retrieve and post your types and or slices. For example, your_ _JSON content models. There are many use cases for this tool: programmatically create backups for your types, automatically create Typescript Types, to name a few.

To do this, perform HTTPS Requests using Curl or similar to hit our Types API Endpoint https://customtypes.prismic.io, pass the route of what you need, and add the necessary authentication headers of your request. You can see complete examples of this below.

Authentication

To authenticate your request with the Custom Type API, you will need two things: your repository ID and a bearer access token.

HTTP Basic Auth performs the Authentication to the API. Provide your repository ID and bearer access token as the basic auth values to your request in headers as shown below:

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

Make all the API requests with HTTPS. Calls made over plain HTTP and without authentication will fail.

Permanent token (recommended)

Find this token in your repository’s Settings > API & Security section. Click the Write APIs tab. Here you can generate your access tokens. You can use multiple bearer access tokens for different applications.

Screenshot of the API & Security settings page

Navigate to the Write API tab to find your repository ID and generate a bearer access token.

User session token (advanced)

This advanced 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 it expires since it depends on the user session. Therefore it needs to be updated once if you wish to make changes afterward.

To retrieve this token, perform an HTTPS request to the Prismic Authentication Server. Then, send a POST request to the https://auth.prismic.io/login route. And finally, provide the email and password of your Prismic account within the body of this request.

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

Custom types status

The JSON response of your custom types has a Status field. The Status is a boolean field that indicates whether the custom type is currently active or disabled in the Prismic Repository.

The Status is helpful if 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

The active custom type list in the Prismic UI

Active Types appear like above Prismic Dashboard and like below in the JSON response:

{
  "id":"page",
  "label":"Page",
  "repeatable":true,
  "json":{
    "Page":{
      "uid":{
        "type":"UID",
        "config":{
          "label":"UID",
          "placeholder":"example-unique-identifier"
        }
      }
    }
  },
  "status":true
}

Disabled custom types

"status": false

The disabled custom type list in the Prismic UI

Disabled Types appear like above Prismic Dashboard and like below in the JSON response:

{
  "id":"about_page",
  "label":"About Page",
  "repeatable":true,
  "json":{
    "Page":{
      "uid":{
        "type":"UID",
        "config":{
          "label":"UID",
          "placeholder":"example-unique-identifier"
        }
      }
    }
  },
  "status":false
}

New to CURL?

An excellent way to test and work with CURL for the first time is to use a tool like Postman. Click the button below to follow our instructions for querying the Types API with Postman.

Open the Postman instructions

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 repository, all custom types of a specific Type, all shared slices, and specific shared slices.

All custom types

Specify the following parameters as headers to retrieve all the custom types from your Prismic repository:

  • Types API Endpoint (with the /customtypes route)
  • location
  • authentication
curl --location --request GET 'https://customtypes.prismic.io/customtypes' \
--header 'repository: tutorial-series' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjM2M3MTAzMTEwMDAwMWYwMGExYTZhMiIsInR5cGUiOiJ1c2VyIiwiZGF0ZSI6MTYxMzczNTY2NzIxNSwiaWF0IjoxNjEzNzM1NjY3fQ.Ex18_cuNtHes69me4pHQGLpiQ-OUbi42-qFxkZCG-yw'

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 repository.

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

All shared slices

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

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

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.

The Shared Slice tab in the custom type builder in the Prismic UI

Enter any of your custom types, select + New slice and you will find the Shared Slices tab.

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

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.

Insert a new custom type

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

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
}'

Update a custom type

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

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
}'

Insert a new Shared slice

The /slices/insert route is for adding new shared slices to your repository. To do so, specify the Types API Endpoint with the /slices/insert route, the authentication, and the Shared slice JSON.

In the example below we have one slice with a text field. The screenshots can be found in the imageUrl field of each variation as shown below:

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": [
    {
      "id": "default",
      "name": "Default",
      "docURL": "...",
      "version": "sktwi1xtmkfgx8626",
      "description": "Text",
      "primary": {
        "text": {
          "type": "StructuredText",
          "config": {
            "label": "Text",
            "placeholder": "Text with rich formatting",
            "allowTargetBlank": false,
            "multi": "paragraph"
          }
        }
      },
      "items": {},
      "imageUrl": "https://images.prismic.io/tutorial-series/shared-slices/image_gallery/preview.png"
    }
  ]
}'

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 Types API Endpoint with the /slices/update routes, the authentication, and the Shared slice JSON.

In the example below we have one slice with a text field. The screenshots can be found in the imageUrl field of each variation as shown below:

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": [
    {
      "id": "default",
      "name": "Default",
      "docURL": "...",
      "version": "sktwi1xtmkfgx8626",
      "description": "Text",
      "primary": {
        "text": {
          "type": "StructuredText",
          "config": {
            "label": "Text",
            "placeholder": "Text with rich formatting",
            "allowTargetBlank": false,
            "multi": "paragraph"
          }
        }
      },
      "items": {},
      "imageUrl": "https://images.prismic.io/tutorial-series/shared-slices/image_gallery/preview.png"
    }
  ]
}'

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. Specify the Types API Endpoint with the /customtypes/{customTypeId} routes, and the authentication as shown below:

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

Remove a Shared slice

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

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