Get started with the Project Model API

Note: The Model API is available as a custom early access add-on for enterprise customers. We expect active iteration with the customers who use this to refine the feature.

The Model API provides access to a JSON representation of Plasmic projects. This is the tree of elements that make up any Plasmic page or component, and then from there control the rendering yourself.

Learn more about SDUI.

Get started with the Model API

Copy
curl \
  --header 'x-plasmic-api-project-tokens: PROJECTID:APITOKEN' \
  'https://codegen.plasmic.app/api/v1/loader/repr-v2/preview/PROJECTID'

As with the REST API, you can specify preview, published, or loader, and specify specific tags/branches/versions in the project ID.

JSON representation examples

Components, props, and nested components inside a children slot—note that these may be instances of either code components or Plasmic components:

Copy
{
  "type": "component",
  "name": "List",
  "props": {
    "name": "Shopping list",
    "upvotes": 42,
    "children": [
      {
        "type": "component",
        "name": "ListItem",
        "props": {
          "name": "Milk"
        }
      },
      {
        "type": "component",
        "name": "ListItem",
        "props": {
          "name": "Cookies"
        }
      }
    ]
  }
}

Rich text, including both span-level and block-level elements denoted within markers (node markers replace the [child] substring):

Copy
{
  "type": "text",
  "value": "Hello world!\n[child]\nThis is the body text.",
  "markers": [
    {
      "type": "style",
      "position": 0,
      "length": 5,
      "style": {
        "font-weight": "bold"
      }
    },
    {
      "type": "node",
      "position": 13,
      "length": 7,
      "value": {
        "type": "text",
        "value": "This is a heading",
        "tag": "h1"
      }
    }
  ]
}

Arbitrary box containers (aka stacks) are always returned as box type, ignoring their layout styles:

Copy
{
  "type": "box",
  "children": [
    {
      "type": "component",
      "name": "HeroSection"
    },
    {
      "type": "component",
      "name": "PricingSection"
    }
  ]
}

Use cases and limitations

This is intended to serve use cases where Plasmic is being used primarily as a visual CMS, rather than a free-form page builder. This means it assumes you have implemented your own components for taking care of rendering.

It does not support the following:

• Styling and layout.
• Variants.
• Dynamic values.
• Visibility settings.

What is supported:

• Component instances, including both code components and Plasmic components
• Box containers (stacks)
• Rich text

More fields may be introduced into the JSON schema in the future, so please ensure your code tolerates additional keys that are not currently part of the returned object structures.

(Experimental) Full model structure API

If you are needing a more complete but lower-level dump of the project model structure for debugging purposes, you can use the (fast-changing) repr-v3 API. Do not depend on this for any production usage---it is liable to change at any time!

Copy
curl \
  --header 'x-plasmic-api-project-tokens: PROJECTID:APITOKEN' \
  'https://codegen.plasmic.app/api/v1/loader/repr-v3/preview/PROJECTID'

Give feedback on this page