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;

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.

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.

Customization

The REST API let’s 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;

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 in the docs.

Give feedback on this page