Get started with the Project Model API

Note: The Model API is experimental, and the schema may evolve from time to time. If you plan to introduce a production dependency on this, please get in touch with us.

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-v3/preview/PROJECTID'

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

You’ll get a large response that starts something like this:

Copy
{
  "site": {
    "__iid": 1,
    "__type": "Site",
    "components": [
      {
        "__iid": 25,
        "__type": "Component",
        "uuid": "5-ThUEPfFc",
        "name": "Home",
        "params": [],
        "states": [],
        "tplTree": {
          "__iid": 51705,
          "__type": "TplComponent",
          "name": null,
          "component": { "__iidRef": 51706 },
          "vsettings": [
            {
              "__iid": 51707,
              "__type": "VariantSetting",
              "variants": [{ "__iidRef": 28 }],
              "args": [
                {
                  "__iid": 52922,
                  "__type": "Arg",
                  "param": { "__iidRef": 52921 },
                  "expr": {
                    "__iid": 114515,
                    "...": "..."
                  },
                  "...": "..."
                }
              ],
              "...": "..."
            }
          ],
          "...": "..."
        },
        "...": "..."
      }
    ],
    "...": "..."
  },
  "...": "..."
}

Schema

All models start with a site object at the root.

This in turn contains a number of fields. The most interesting of these are:

  • styleTokens
  • mixins
  • globalVariants
  • userManagedFonts
  • globalContexts: The global configuration options on the project, for the various used packages.
  • activeTheme: The default styles defined in the project.
  • splits: Metadata about all the optimization features defined for the project, such as A/B tests, custom targets, and scheduled content.
  • components: This is where all pages and components are defined. Their subfields include:
    • type: Whether it’s a page or component.
    • metadata: The user-specified metadata for this copmonent.
    • pageMeta: SEO page metadata for this page.
    • variants: The definition/enumeration of all the variants defined for this.
    • tplTree: The actual tree of TplNodes (template nodes) that form a component. TplNodes are typically either TplTags (normal HTML tag elements) or TplComponents (instances of components, whether Plasmic components or code components) or TplSlots.
      • vsettings: Short for “variant settings.” This is where all styles and prop settings are stored. They correspond to some combination of variants.
        • rs: This is where the CSS rulesets are stored.
        • attrs: Props for built-in HTML element tag types.
        • args: Props for each component. This can include slot arguments, so can include for instance children prop values for components.
        • text: For TplTags, what the text content is.
      • tag: Only for normal TplTags.
      • children: Only for normal TplTags.
      • component: Only for TplComponents. Indicates which component this is an instance of.

Every object in the tree should have a field __type indicating its type (such as Component or StyleToken).

Every object also has an “internal ID” in a field __iid.

You’ll occasionally find cross-references in the tree to objects that live elsewhere:

Copy
{
  "__iid": 235897
}

Sometimes, these references are not to other parts of the current project, but to another project. This can happen when you have made use of cross-project imports, for instance. In that case, you’ll see a UUID in the reference as well:

Copy
{
  "__iid": 235897,
  "__uuid": "kjuFFTSZb8fanzCHT2C1jz"
}

There are many more details to the model schema not yet covered in these docs. Please feel free to reach out with more specific questions!

Was this page helpful?

Give feedback on this page