Builder HTML API

By leveraging the HTML API, Builder streamlines the integration with any setup by enabling server-side pre-rendering

To experiment with the HTML API, check out the Builder API Explorer, which works with your own Builder content. The following video shows an example of using the API Explorer:

Sample request and response

The following is an example of a request and response:

https://cdn.builder.io/api/v1/html/YOUR_MODEL_NAME?apiKey=YOUR_API_KEY&url=PAGE_URL

# Example response
# {
#   "id": "c923kd89",
#   "name": "About page",
#   "data: {
#     "html": "<div data-builder-component="banner-ad"><div class="builder-blocks"><h1>Hello!</h1></div></builder-div>"
#   }
# }

Query params

Name	Required	Description
`apiKey`	Yes	Your Public API key
`url`	Yes	The current URL of the visitor on your site. `?url=https://your-site.com/about?foo=bar`
`includeUnpublished`	No	Set to `true` to include unpublished content in your API response; for example, testing.
`query.*`	No	Mongodb-style query of your data. `&query.data.id=abc123 &query.data.myCustomField=someValue &query.data.someNumber.$ne=20`
`fields`	No	Only include these fields. `&fields=id,name,data.customField`
`omit`	No	Omit only these fields. `&omit=data.bigField,data.blocks`
`userAttributes.*`	No	Optionally use this to send targeting attributes. `&userAttributes.device=desktop &userAttributes.locale=en_us`
`cacheSeconds`	No	Seconds to cache content (sets the max-age of the cache-control header response header). Set the value higher for better performance and lower for content that changes more frequently. `&cacheSeconds=120`
`format`	No	Set to `amp` to render amp content (the content must be made with an amp model type) or `email` to render email model content (the content must be made with an email model). `&format=amp`

Previewing content on your site

In order to take advantage of all Builder has to offer, you need to be able to preview the content you build on your actual site. This ensures that any side effects of site-wide styles that affect Builder created content—for example, heading CSS rules—are clearly shown.

To integrate previewing, create a single route on your website that serves the Builder preview HTML and JavaScript. To do so, create a new page/endpoint/route on your site called /builder-preview. You can call it whatever you like, but this example refers to /builder-preview as the route, so just swap out /builder-preview in any example code or settings changes for the path you choose.

The framework you are using dictates how to create the new route, but the HTML it returns should be similar to the following example:

<builder-component model="PAGE_MODEL_NAME" api-key="YOUR_API_KEY"></builder-component>
<script async src="https://cdn.builder.io/js/webcomponents"></script>

Tip: Make sure to replace the PAGE_MODEL_NAME and API_KEY with the actual values from your Builder space.

For more information, read Using Builder API Keys and Page Models.

The PAGE_MODEL_NAME should be the Builder model name of the model you are trying to preview. Most of the time it is page. An alternative and useful approach is to not hardcode the model name, but instead to have it be determined by query parameter in the page URL.

In this way, you can use a single endpoint to preview content from different models, such as /builder-preview?model=page or /builder-preview?model=homepage-section. Here is a pseudocode example:

import layout from '../yourLayoutComponent';
import { builderPublicKey } from '../constants/builder';

const model = requestQueryParams.get('model');

return (
  <layout title="Builder.io Preview page">
    <builder-component name="{model}" api-key={builderPublicKey}>
    </builder-component>
    <script src="https://cdn.builder.io/js/webcomponents" async></script>
  </layout>
);

For more information, read Dynamic Preview URLs.

Setting the Preview URL

Next, set the model Preview URL in Builder:

Go to Models.
Select the model you want to integrate previewing with. Change the preview URL to https://www.yoursite.com/builder-preview (make sure to replace that with your actual website).
Click the Save button.

For more context, read Editing and Previewing Your Site.

Tip: If you decided to have the model name determined dynamically, then change the Preview URL to have a model query param and have that value be the name of the model; for example, https://www.yoursite.com/builder-preview?model=page

Toggle off reloading the Preview URL

Go to Account Settings.
Go to Advanced Settings > Advanced.
Toggle off the setting called Reload preview on URL path change. This setting is on by default, so you need to click it to make it turn grey instead of blue, which coincides with the toggle to the left.

You should now be able to create content in the editor and preview it on your site. Repeat this process as needed with other models you'd like to preview on your site.

Looking to hire a third party to help with your project?

Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.

Connect with us

Was this article helpful?