Plasmic CMS - API Reference

Overview

Plasmic CMS includes a RESTful HTTP API that allows you to create, read, update, and delete data in code; it enables integrating and using the data in Plasmic’s CMS with other platforms.

Authentication

The HTTP API can only be requested if you have authorization to access the requested CMS. The request for the endpoint must include a header x-plasmic-api-cms-tokens with a value of <CMS_ID>:<TOKEN>.

  • CMS_ID is the ID of the Plasmic CMS that you are accessing the data from.
  • TOKEN depends on which type of operation you’re making:
    • For read operations (e.g. Get Items), use your public token.
    • For write operations (e.g. Create Item), use your secret token.
      • WARNING: Anyone with your secret token can edit the content in your CMS. Only use your secret token in secure server environments, not in public websites.

Your CMS ID, Public Token, and Secret can be found on the “CMS Settings” tab. For step-by-step instructions, see Appendix.

API: Get Items

Method: GET

https://studio.plasmic.app/api/v1/cms/databases/CMS_ID/tables/CMS_MODEL_ID/query

ArgumentDescription
CMS_IDID of the CMS to read data from.
CMS_MODEL_IDID of the model to read data from.
Querystring ParamsRequired?Description
qNoURL encoded string of a JSON object for specifying the query parameters (e.g. {"where":{"slug":"first-post"}, limit: 1}).
draftNoPass draft=1 to load draft/unpublished items. Requires secret token.
localeNoLocale tag for loading localized/translated fields (e.g. locale=ar-JO).
HeaderValue
x-plasmic-api-cms-tokensCMS_ID:CMS_PUBLIC_TOKEN

Example: Load all items of a model

e.g. load all the testimonials

Response:

Copy
{
"rows": [
{
"id": "7vfFX4Ywen2fCBkzGH2J3x",
"createdAt": "2022-03-08T00:57:40.270Z",
"updatedAt": "2022-03-12T09:04:52.227Z",
"identifier": "First User",
"data": {
"author": "First User",
"message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"imageUrl": "https://picsum.photos/200/200?image=1"
}
},
{
"id": "nWsULzngbPha2RLtxAsYaW",
"createdAt": "2022-03-08T00:57:01.251Z",
"updatedAt": "2022-03-12T09:05:00.268Z",
"identifier": "Second User",
"data": {
"author": "Second User",
"message": "Phasellus a massa fermentum, consequat orci at.",
"imageUrl": "https://picsum.photos/200/200?image=2"
}
},
{
"id": "hN7Dw8h2FM6VRYJDcGsJyo",
"createdAt": "2022-03-08T00:57:20.789Z",
"updatedAt": "2022-04-15T17:48:24.101Z",
"identifier": "Third User",
"data": {
"author": "Third User",
"message": "Nam viverra dignissim arcu, eget ultrices elit aliquet.",
"imageUrl": "https://picsum.photos/200/200?image=3"
}
}
]
}

Example: Load a specific item

e.g. load a single blog post using its slug

Copy
// Find your CMS ID and Public Token from the settings page.
const CMS_ID = 'YOUR_CMS_ID';
const CMS_PUBLIC_TOKEN = 'YOUR_CMS_PUBLIC_TOKEN';
// Find your model's unique identifier from its model schema page.
const modelId = 'blogPosts';
// Construct the API Url
const apiUrl = new Url(`https://studio.plasmic.app/api/v1/cms/databases/${CMS_ID}/tables/${modelId}/query`);
// Set a filter to load entries with "slug" field value = "my-first-blog-post".
apiUrl.search = new URLSearchParams({
q: JSON.stringify({
where: {
slug: 'my-first-blog-post'
},
// Load one item only
limit: 1
})
}).toString();
// Load filtered entries
const response = await fetch(apiUrl.toString(), {
headers: {
// Your CMS ID and CMS Public API token
'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_PUBLIC_TOKEN}`
}
});
const parsedResponse = await response.json();
const blogPost = parsedResponse.rows[0];
console.log(blogPost);

Response:

Copy
{
"id": "gN6Dw9h3FM5VRXJDcHsJz4",
"createdAt": "2022-04-15T17:38:24.101Z",
"updatedAt": "2022-04-15T17:48:24.101Z",
"identifier": "Blog Post 1",
"data": {
"author": "John Doe",
"title": "My First Blog Post",
"slug": "my-first-blog-post",
"body": "<h2>Lorem Ipsum</h2><p>Donec dignissim ornare magna, ac aliquet erat sodales eu.</p>"
}
}

Example: Load a localized version of the post (based on the example above)

Copy
// ...
apiUrl.search = new URLSearchParams({
q: JSON.stringify({ where: { slug: 'my-first-blog-post' }, limit: 1 }),
// Load the `Arabic (Jordan)` localized version of the blog post
locale: 'ar-JO'
}).toString();
// ...

Example: Load a draft version of the post (based on the example above)

Copy
// ...
const useDraftVersion = true;
apiUrl.search = new URLSearchParams({
q: JSON.stringify({ where: { slug: 'my-first-blog-post' }, limit: 1 }),
// Load the Draft version of the blog post
draft: Number(useDraftVersion) // ?draft=1
}).toString();
// ...

API: Create Item

Method: POST

https://studio.plasmic.app/api/v1/cms/databases/CMS_ID/tables/CMS_MODEL_ID/rows

ArgumentDescription
CMS_IDID of the CMS to update.
CMS_MODEL_IDID of the model to create.
HeaderValue
x-plasmic-api-cms-tokensCMS_ID:CMS_SECRET_TOKEN
content-typeapplication/json

Example

e.g. create one or more blog posts

Copy
// You can find your CMS ID and Secret Token from the settings page of your CMS.
const CMS_ID = 'YOUR_CMS_ID';
// WARNING: Anyone with your secret token can edit the content in your CMS.
// Only use your secret token in secure server environments, not in public websites.
const CMS_SECRET_TOKEN = 'YOUR_CMS_SECRET_TOKEN';
// Find your model's unique identifier from its model schema page.
const modelId = 'blogPosts';
// Construct the json for the itens you want to create
const firstItem = {
identifier: 'First item',
data: {
author: 'First User',
// message is localized, the empty string is the default locale
message: {
'': 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
'ar-JO': 'Nam viverra dignissim arcu, eget ultrices elit aliquet.'
},
imageUrl: 'https://picsum.photos/200/200?image=1'
}
};
const secondItem = {
data: {
// Not including a field or a locale will use the default values on that table
message: {
'': 'Phasellus a massa fermentum, consequat orci at.'
},
// Setting imageUrl to null, it will remove the default
imageUrl: null
}
};
// Create entries, you can add `?publish=1` to the URL to automatically publish the created rows
const response = await fetch(`https://studio.plasmic.app/api/v1/cms/databases/${CMS_ID}/tables/${modelId}/rows`, {
method: 'POST',
headers: {
// Your CMS ID and CMS Secret API token
'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_SECRET_TOKEN}`,
'content-type': 'application/json'
},
body: JSON.stringify({ rows: [firstItem, secondItem] })
});

Response:

Copy
{
"rows": [
{
"id": "fQukeSHQdijeTD22pPD3iZ",
"tableId": "37ZHFaa2oL6L3F6uEpSzCP",
"createdAt": "2022-05-18T16:32:13.164Z",
"updatedAt": "2022-05-18T16:32:13.164Z",
"identifier": "First item",
"data": null,
"draftData": {
"author": "First User",
"message": {
"": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"ar-JO": "Nam viverra dignissim arcu, eget ultrices elit aliquet."
},
"imageUrl": "https://picsum.photos/200/200?image=1"
}
},
{
"id": "387J2rZHouBSQhVdHbKDbY",
"tableId": "37ZHFaa2oL6L3F6uEpSzCP",
"createdAt": "2022-05-18T16:32:13.165Z",
"updatedAt": "2022-05-18T16:32:13.165Z",
"identifier": null,
"data": null,
"draftData": {
"author": "Anonymous Author",
"message": {
"": "Phasellus a massa fermentum, consequat orci at.",
"ar-JO": "Default Arabic (Jordan) localized message"
},
"imageUrl": null
}
}
]
}

API: Publish Item

Method: POST

https://studio.plasmic.app/api/v1/cms/rows/ROW_ID/publish

ArgumentDescription
ROW_IDID of the row to publish.
HeaderValue
x-plasmic-api-cms-tokensCMS_ID:CMS_SECRET_TOKEN

Example

Copy
// Find your CMS ID and Secret Token from the settings page.
const CMS_ID = 'YOUR_CMS_ID';
// WARNING: Anyone with your secret token can edit the content in your CMS.
// Only use your secret token in secure server environments, not in public websites.
const CMS_SECRET_TOKEN = 'YOUR_CMS_SECRET_TOKEN';
const rowId = 'ROW_ID';
// Publish entry
const response = await fetch(`https://studio.plasmic.app/api/v1/cms/rows/${rowId}/publish`, {
method: 'POST',
headers: {
// Your CMS ID and CMS Secret API token
'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_SECRET_TOKEN}`
}
});

Response:

Copy
{
"id": "387J2rZHouBSQhVdHbKDbY",
"tableId": "37ZHFaa2oL6L3F6uEpSzCP",
"createdAt": "2022-05-18T16:32:13.165Z",
"updatedAt": "2022-05-18T16:32:13.165Z",
"identifier": null,
"data": {
"author": "Anonymous Author",
"message": {
"": "Phasellus a massa fermentum, consequat orci at.",
"ar-JO": "Default Arabic (Jordan) localized message"
},
"imageUrl": null
},
"draftData": null
}

API: Update Item

Method: PUT

https://studio.plasmic.app/api/v1/cms/rows/ROW_ID

ArgumentDescription
ROW_IDID of the row to update.
HeaderValue
x-plasmic-api-cms-tokensCMS_ID:CMS_SECRET_TOKEN
content-typeapplication/json

Example

Copy
// Find your CMS ID and Secret Token from the settings page.
const CMS_ID = 'YOUR_CMS_ID';
// WARNING: Anyone with your secret token can edit the content in your CMS.
// Only use your secret token in secure server environments, not in public websites.
const CMS_SECRET_TOKEN = 'YOUR_CMS_SECRET_TOKEN';
const rowId = 'ROW_ID';
// Construct the json for item to update
const updateItem = {
identifier: 'Second item',
data: {
// Undefined fields won't be changed, null fields will be cleared
message: {
'ar-JO': null
},
imageUrl: 'https://picsum.photos/200/200?image=2'
}
};
// Update entry, you can add `?publish=1` to the URL to automatically publish the updated row
const response = await fetch(`https://studio.plasmic.app/api/v1/cms/rows/${rowId}`, {
method: 'PUT',
headers: {
// Your CMS ID and CMS Secret API token
'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_SECRET_TOKEN}`,
'content-type': 'application/json'
},
body: JSON.stringify(updateItem)
});

Response:

Copy
{
"id": "387J2rZHouBSQhVdHbKDbY",
"tableId": "37ZHFaa2oL6L3F6uEpSzCP",
"createdAt": "2022-05-18T16:32:13.165Z",
"updatedAt": "2022-05-18T16:51:14.336Z",
"identifier": "Second item",
"data": {
"author": "Anonymous Author",
"message": {
"": "Phasellus a massa fermentum, consequat orci at.",
"ar-JO": "Default Arabic (Jordan) localized message"
},
"imageUrl": null
},
"draftData": {
"author": "Anonymous Author",
"message": { "": "Phasellus a massa fermentum, consequat orci at.", "ar-JO": null },
"imageUrl": "https://picsum.photos/200/200?image=2"
}
}

API: Delete Item

Method: DELETE

https://studio.plasmic.app/api/v1/cms/rows/ROW_ID

ArgumentDescription
ROW_IDID of the row to delete.
HeaderValue
x-plasmic-api-cms-tokensCMS_ID:CMS_SECRET_TOKEN

Example

Copy
// Find your CMS ID and Secret Token from the settings page.
const CMS_ID = 'YOUR_CMS_ID';
// WARNING: Anyone with your secret token can edit the content in your CMS.
// Only use your secret token in secure server environments, not in public websites.
const CMS_SECRET_TOKEN = 'YOUR_CMS_SECRET_TOKEN';
const rowId = 'ROW_ID';
// Delete entry
const response = await fetch(`https://studio.plasmic.app/api/v1/cms/rows/${rowId}`, {
method: 'DELETE',
headers: {
// Your CMS ID and CMS Secret API token
'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_SECRET_TOKEN}`
}
});

Appendix

Find your CMS IDs, Public Token, and Secret Token

  1. Go to the dashboard.
  2. Click on your workspace from the left sidebar.
  3. Click on your CMS.
  4. Click on the “CMS Settings” tab from the left sidebar.
  5. Find the “CMS ID”, “Public Token”, and “Secret Token”.
Screenshot of CMS settings

Find your model ID

  1. Go to the dashboard.
  2. Click on your workspace from the left sidebar.
  3. Click on your CMS.
  4. Click on the “Edit models” tab from the left sidebar.
  5. Click on your model.
  6. Find the “Unique identifier”.
Screenshot of edit models

Find your row ID

Your row IDs will be returned in the response of all API calls. For example, see the response of API: Get Items.

Was this page helpful?

Give feedback on this page