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