Integration Fields write API (BETA)

This new BETA feature is available on request from our team. You can reach out to us on the forum to have this feature activated, as described here.

Getting Started

Once activated, go to your Prismic repository's Settings / Integrations Fields. You will need to have administrator permissions on your repository (or have someone with Admin rights help you do this).

Click to create a new Custom API integration, and you will have two options: "Pull data from my endpoint" and "Push data to Prismic".

Select the "Push" option, enter the name & description for your catalogue, then click to "Create my integration field".

If you don't see the "Push data to Prismic" tab, you'll need to request the Integration Fields write API feature to be activated on your repository. The same is true if you don't see the Integration Fields page in your settings. You can request access via the Prismic community forum.

Once your Integration Field is created, you can click on the Integration Field to view the write API endpoint as well as the access token you'll need to interact with your API.

Add/modify items in the catalog

To add or modify items to your catalog you can send a POST request to the following endpoint:

https://if-api.prismic.io/if/write/:catalogId

The catalogId can be found by viewing the Integration Field settings as shown in the video above. For this example, we will assume that the catalogId is your-repo-name--your_catalog.

https://if-api.prismic.io/if/write/your-repo-name--your_catalog

Authorization Header

You'll need to include a Bearer token authorization header when sending the POST request. Your Bearer token can be found by viewing the Integration Field settings as shown in the video above. Here is an example (note that your token will be longer than the example below).

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Body request example

Here is an example of the request body that will add a new item in the catalog (or modify an existing item based on the "id" attribute). Each item will require the top-level fields shown below. The "blob" attribute is where you add the data for your items that will be returned in the Prismic API.

You can read more about the required fields in our Custom API documentation.

[
  {
    "id": "0",
    "title": "My Item number 0",
    "description": "Lorem ipsum",
    "image_url": "https://if-test-custom-api.herokuapp.com/asset/0",
    "last_update": 1591670070,
    "blob": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  },
  {
    "id": "1",
    "title": "My Item number 1",
    "description": "Lorem ipsum",
    "image_url": "https://if-test-custom-api.herokuapp.com/asset/1",
    "last_update": 1591670070,
    "blob": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  }
]

Putting it all together

Here is an example of a full raw POST request to add items to your Integration Field catalog.

POST /if/write/your-repo-name--your_catalog HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 514
[
  {
    "id": "0",
    "title": "My Item number 0",
    "description": "Lorem ipsum",
    "image_url": "https://if-test-custom-api.herokuapp.com/asset/0",
    "last_update": 1591670070,
    "blob": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  },
  {
    "id": "1",
    "title": "My Item number 1",
    "description": "Lorem ipsum",
    "image_url": "https://if-test-custom-api.herokuapp.com/asset/1",
    "last_update": 1591670070,
    "blob": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  }
]

Body response

If all goes well with your request, you should see a status of 200 (OK) returned from the API.

Delete items from the catalog

To delete items from your catalog you can send a POST request to the following endpoint:

https://if-api.prismic.io/if/write/:catalogId/deleteItems

The catalogId can be found by viewing the Integration Field settings as shown in the video above. For this example, we will assume that the catalogId is your-repo-name--your_catalog.

https://if-api.prismic.io/if/write/your-repo-name--your_catalog/deleteItems

Authorization Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Body request example

Here is an example of the request body that will delete items in the catalog. You need to provide an array of ids corresponding to each item you want to delete.

["id-0", "id-1", "id-2"]

Putting it all together

Here is an example of a full raw POST request to delete items from your Integration Field catalog.

POST /if/write/your-repo-name--your_catalog/deleteItems HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 24
["id-0", "id-1", "id-2"]

Body response

If all goes well with your request, you should see a status of 200 (OK) returned from the API.

Delete all items from the catalog / reset a catalog

To delete all the items from your catalog you can send a POST request to the following endpoint:

https://if-api.prismic.io/if/write/:catalogId/reset

The catalogId can be found by viewing the Integration Field settings as shown in the video above. For this example, we will assume that the catalogId is your-repo-name--your_catalog.

https://if-api.prismic.io/if/write/your-repo-name--your_catalog/reset

Authorization Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Body request example

Nothing is required in the body of the request to reset a catalog. Leave it empty.

Putting it all together

Here is an example of a full raw POST request to reset and empty your Integration Field catalog.

POST /if/write/your-repo-name--your_catalog/reset HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 0

Body response

If all goes well with your request, you should see a status of 200 (OK) returned from the API.