Plasmic CMS - API Reference

API Overview

The Plasmic CMS API is a REST 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 REST API can only be requested if you have authorization to access the requested CMS. In the request for the endpoint you should include x-plasmic-api-cms-tokens in the headers. The field has to be set in the following way.

Copy
{
"x-plasmic-api-cms-tokens": "CMS_ID:CMS_PUBLIC_TOKEN"
}

Where CMS_ID is the id of the CMS that you are accessing the data from, and CMS_PUBLIC_TOKEN is a token that will indicate if you are authorized to perform the request.

Finding your CMS ID and Token:

  1. Go to the dashboard.
  2. Click on your workspace from the left sidebar.
  3. Click on your CMS.
  4. Click on the Settings icon from the left sidebar.

API Endpoints

Get Items

https://studio.plasmic.app/api/v1/cms/databases/CMS_ID/tables/CMS_MODEL_ID/query?q=%7B%7D

ArgumentDescription
CMS_IDThis is the id of the CMS to read data from
CMS_MODEL_IDThis is the id of the model, you can get the model identifier from the model schema page.
Querystring ParamsRequired?Description
qYesa url encoded string of a JSON object for specifying the query parameters. e.g. {"where":{"slug":"first-post"}, limit: 1}
draftNoPass draft=1 to load items stored as drafts (not-yet-published).
localeNoThis is locale name for loading localized/translated fields. (e.g. locale=ar-JO)

Examples

The following are code snippets that show how the CMS api can be used.

Loading all items in a model

e.g. load all the testimonials.

Example 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"
}
}
]
}

Loading a specific item

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

Javascript Example

Copy
// You can find your CMS ID and Token by visiting the settings page of your CMS.
// Go to Plasmic's Dashboard -> Workspace -> CMS -> Settings
const CMS_ID = 'YOUR_CMS_ID';
const CMS_PUBLIC_TOKEN = 'YOUR_CMS_ID';
// You can get the model identifier from the 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);

Example 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>"
}
}

Loading 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();
// ...

Loading 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();
// ...

Creating an item

Work in progress…

Updating an item

Work in progress…

Deleting an item

Work in progress…

Give feedback on this page