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://data.plasmic.app/api/v1/cms/databases/CMS_ID/tables/CMS_MODEL_ID/query

Argument	Description
`CMS_ID`	ID of the CMS to read data from.
`CMS_MODEL_ID`	ID of the model to read data from.

Querystring Params	Required?	Description
`q`	No	URL encoded string of a JSON object for specifying the query parameters (e.g. `{"where":{"slug":"first-post"},"limit":1}`). Default filters include all records.
`q.limit`	100	Fetch only up to this many records.
`q.offset`	0	Skip this many records first.
`draft`	No	Pass `draft=1` to load draft/unpublished items. Requires secret token.
`locale`	No	Locale tag for loading localized/translated fields (e.g. `locale=ar-JO`). Locale tags are configured in your CMS’s settings.

Header	Value
`x-plasmic-api-cms-tokens`	`CMS_ID:CMS_PUBLIC_TOKEN`

Example: Load all items of a model

e.g. load all the testimonials

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 = 'testimonials';

// Load all model entries
const response = await fetch(`https://data.plasmic.app/api/v1/cms/databases/${CMS_ID}/tables/${modelId}/query`, {
  headers: {
    // Your CMS ID and CMS Public API token
    'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_PUBLIC_TOKEN}`
  }
});

const parsedResponse = await response.json();
console.log(parsedResponse);

const testimonials = parsedResponse.rows;
// ...

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 or its system ID (_id)

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://data.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'
      // Or to query by the system ID:
      // _id: 'gN6Dw9h3FM5VRXJDcHsJz4'
      // This only queries by system ID if there is no user-defined "_id" field.
    },
    // Load one item only
    limit: 1,
    // Skip this many rows first
    offset: 0
  })
}).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 localized items

e.g. load a single blog post using its slug in Arabic (based on above example)

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 draft versions of items

e.g. load the draft version of a single blog post using its slug (based on above example)

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

Method: GET

https://data.plasmic.app/api/v1/cms/databases/CMS_ID/tables/CMS_MODEL_ID/count

This takes the same arguments as the /query endpoint above, but returns just the count instead of returning row data.

Example: Count all items of a model

e.g. count all the testimonials

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 = 'testimonials';

// Load all model entries
const response = await fetch(`https://data.plasmic.app/api/v1/cms/databases/${CMS_ID}/tables/${modelId}/count`, {
  headers: {
    // Your CMS ID and CMS Public API token
    'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_PUBLIC_TOKEN}`
  }
});

const parsedResponse = await response.json();
console.log(parsedResponse);

const testimonials = parsedResponse.rows;
// ...

Response:

Copy

{
  "count": 3
}

API: Create Item

Method: POST

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

Argument	Description
`CMS_ID`	ID of the CMS to update.
`CMS_MODEL_ID`	ID of the model to create.

Header	Value
`x-plasmic-api-cms-tokens`	`CMS_ID:CMS_SECRET_TOKEN`
`content-type`	`application/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://data.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://data.plasmic.app/api/v1/cms/rows/ROW_ID/publish

Argument	Description
`ROW_ID`	ID of the row to publish.

Header	Value
`x-plasmic-api-cms-tokens`	`CMS_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://data.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://data.plasmic.app/api/v1/cms/rows/ROW_ID

Argument	Description
`ROW_ID`	ID of the row to update.

Header	Value
`x-plasmic-api-cms-tokens`	`CMS_ID:CMS_SECRET_TOKEN`
`content-type`	`application/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://data.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://data.plasmic.app/api/v1/cms/rows/ROW_ID

Argument	Description
`ROW_ID`	ID of the row to delete.

Header	Value
`x-plasmic-api-cms-tokens`	`CMS_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://data.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

Go to the dashboard.
Click on your workspace from the left sidebar.
Click on your CMS.
Click on the “CMS Settings” tab from the left sidebar.
Find the “CMS ID”, “Public Token”, and “Secret Token”.

Find your model ID

Go to the dashboard.
Click on your workspace from the left sidebar.
Click on your CMS.
Click on the “Edit models” tab from the left sidebar.
Click on your model.
Find the “Unique identifier”.

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