Get started with the REST API

You must first create a project in Plasmic.

To view this quickstart with all the IDs and token placeholders replaced with real values, open your project in Plasmic Studio and press the “Code” button in the top toolbar.

Get started with the REST API

Render a page or component from Plasmic anywhere you can make a REST API call. This returns plain HTML that you can render anywhere, optionally including Javascript-hydrated interactivity.

For instance, using plain Javascript:

Copy

const response = await fetch(
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?hydrate=1&embedHydrate=1',
  {
    headers: {
      // Your project ID and public API token
      'x-plasmic-api-project-tokens': 'PROJECTID:APITOKEN'
      // You can find your PROJECT token by visiting
      // https://studio.plasmic.app/projects/[PROJECTID]/docs/loader#showToken=true
    }
  }
);
const result = await response.json();
document.body.innerHTML = result.html;

// If you want hydration to happen, load and call the hydrater
if (window.__plasmicHydrater) {
  window.__plasmicHydrater.hydrateAll();
} else {
  var script = document.createElement('script');
  script.src = 'https://codegen.plasmic.app/static/js/loader-hydrate.js';
  document.body.appendChild(script);
}

Or using curl:

Copy

curl \
  --header 'x-plasmic-api-project-tokens: PROJECTID:APITOKEN' \
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?hydrate=1&embedHydrate=1' > out.json

# If you have `jq` installed, extract the raw HTML:
jq .html -r < out.json > out.html

The above use the /preview/ route, which fetches the latest revisions, whether or not they were published! Replace with /published/ to ensure you render only published changes, or /versioned/ to render specific versions (specifying the version numbers with the project names in the URL, i.e. /versioned/PROJECTID@VERSION/COMPONENT).

If you want to publish only static content and don’t want to hydrate any Javascript (don’t need any interactivity), remove the query parameters hydrate and embedHydrate.

Server-side data fetching

By default, when you have components that fetch content to be displayed (such as a CMS), the fetches are not executed and thus not included in the resulting HTML by default—the fetches execute client-side.

However, you can specify that this content should be prefetched in the server and provided in the HTML response, by setting the prepass query parameter to 1.

It is important to note that the HTML response from the server is cached. Therefore, any change in the content that was fetched will not be visible until the cache expires. You can bypass this by publishing a new version or using maxAge as a query parameter.

Copy

const response = await fetch(
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?hydrate=1&embedHydrate=1&prepass=1&maxAge=600',
  {
    headers: {
      // Your project ID and public API token
      'x-plasmic-api-project-tokens': 'PROJECTID:APITOKEN'
      // You can find your PROJECT token by visiting
      // https://studio.plasmic.app/projects/[PROJECTID]/docs/loader#showToken=true
    }
  }
);

Customization

The REST API lets you customize both component props and global variants that should be passed down for the requested component.

Copy

const query = new URLSearchParams([
  ['hydrate', '1'],
  ['embedHydrate', '1'],
  [
    'componentProps',
    JSON.stringify({
      // Your component props
    })
  ],
  [
    'globalVariants',
    JSON.stringify([
      // Your global variants
      {
        name: 'Theme',
        value: 'Dark'
      }
    ])
  ]
]);

const response = await fetch(
  `https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?${query}`,
  {
    headers: {
      // Your project ID and public API token
      'x-plasmic-api-project-tokens': 'PROJECTID:APITOKEN'
      // You can find your PROJECT token by visiting
      // https://studio.plasmic.app/projects/[PROJECTID]/docs/loader#showToken=true
    }
  }
);
const result = await response.json();
document.body.innerHTML = result.html;

// If you want hydration to happen, load and call the hydrater
if (window.__plasmicHydrater) {
  window.__plasmicHydrater.hydrateAll();
} else {
  var script = document.createElement('script');
  script.src = 'https://codegen.plasmic.app/static/js/loader-hydrate.js';
  document.body.appendChild(script);
}

Or using curl

Copy

curl \
  --header 'x-plasmic-api-project-tokens: PROJECTID:TOKEN' \
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/Box' -G -d 'hydrate=1&embedHydrate=1&componentProps={"PROP":"VALUE"}&globalVariants=[{"name": "NAME", "value": "VALUE"}]' > out.json

jq .html -r < out.json > out.html

The componentProps field expects an object, you can override the props of the component and specify which component variants should be active. The globalVariants field expects an array with objects, each object describing a global variant, with name and value.

There’s much more to explore!

Perform server-side rendering.
Render different variants.
Override the content or props.
Add dynamic behavior.

Continue learning the API in the docs.

Was this page helpful?

Give feedback on this page