Made in Builder

Made in Builder

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

Product

Features

Integrations

Talk to an Expert

Pricing

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

Builder HTML API

Usage

With the HTML API you can have Builder prerender your components server-side. This makes it a breeze to integrate Builder into pretty much any set up you might have. The best way to get familiar with the API is to explore it using your personalized api explorer, which you can find by clicking the blue button below.

Try Out the Interactive API Explorer

Sample Request and Response

Query params

NameRequiredDescription

apiKey

Yes

Your API key

url

Yes

The current URL of the visitor on your site, e.g. ?url=https://your-site.com/about?foo=bar

includeUnpublished

No

Set to true to include unpublished content in your API response (e.g. for testing)

query.*

No

Mongodb style query of your data. E.g.:

fields

No

Only include these fields. E.g.

omit

No

Omit only these fields, E.g.:

userAttributes.*

No

Optionally use this to send targeting attributes, e.g.:

cacheSeconds

No

Seconds to cache content (sets the max-age of the cache-control header response header). Make higher for better performance, and lower for content that will change more frequently

format

No

Set this to amp to render amp content (the content must be made via an "amp" model type) or email to render email model content (the content must be made via an "email" model)

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 HTMML it returns should look like this:

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

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. That way you can use one 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 of how to do that:

Once you have the route set up on your website to return the above HTML, the next thing to do is to set the model preview url in Builder. Navigate to builder.io/models, and select the model you want to integrate previewing with. Once in that model's settings, you will need to change the preview url to https://www.yoursite.com/builder-preview (making sure to replace that with your actual website). Next, click the Save button.

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

The last step is to go to the builder.io/account/space page, click on Advanced Settings, and then click on 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.

You should now be able to create content in the editor and preview it on your site. If you need to enable more models to be previewed on your site, repeat the above steps.


Need Expert help?

Submit a project to our partners, BuildQuick, and be matched with a Builder expert.

Submit a project

Was this article helpful?