Types API

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, build your Gatsby Schema dynamically, 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.

How do I build a custom type?

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

Authentication

To authenticate your request with the Custom Type API, you will need two things: your repository ID and a 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.

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:

Copy

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

The API & Security section of a Prismic repository. — 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.

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

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:

Copy

{
  "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:

Copy

{
  "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

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

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

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.

Shared slices

Shared slices are available in Slice Machine repositories only. Reach out to the team to activate it.

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.

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.

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 to build your custom types, 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 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 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, 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:

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": [
    {
      "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"
    }
  ]
}'

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 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:

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": [
    {
      "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"
    }
  ]
}'

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. Specify the 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. Specify the 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? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.