Made in Builder

Made in Builder

Webinar ๐Ÿ‘‰ Visually Build at Scale with Builder.io & Netlify on 12/1

ร—

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 Content API

With the Content API, you can make requests to retrieve data about any of your models within Builder. The Content API supports advanced query filtering with URL parameters to help you get exactly the data you need.

Use cases for querying data could include searches, populating content for a collection, or getting all links that meet certain criteria.

To experiment with the Content API, use the Builder API Explorer, which offers a way for you to compose queries in your own Builder Space. This way, you can confirm that your queries are correct before editing your code base.

The video below shows querying the Content API and displaying the response JSON. Written instructions are below the video.

The process in the video above is as follows:

  1. Go to Models.
  2. Select any model.
  3. Scroll down and click on the button labeled Try the API Explorer.
  4. When you're logged into your Builder account, the API Explorer is pre-populated with your Public API Key. In this way, the available options reflect what you have available in that particular space.
  5. For this example, expand one of the areas under Content API.
  6. Click the Try it Out button.
  7. Under Query, accept the default of no-queries.
  8. Scroll down and click the Execute button.
  9. After clicking the Execute button, scroll down a little for the responses. The API Explorer provides three options for accessing the data:
  • Curl command: run this at the command line
  • Request URL: paste into the address bar of your browser
  • Server response: your data, output in the API Explorer or quick reference

You can use any of these options to reveal the shape of the JSON, which informs how you write your queries. For example, consider JSON with the following shape:

To access this data, write queries with dot notation and, optionally, MongoDB style operators such as:

Text that reads, "Try the API Explorer". Under the text is a curved arrow pointing to a tile to the right

Builder API Explorer

Supported Query Params

NameRequiredDescription

apiKey

Yes

userAttributes

No

Optionally use to send targeting attributes. For example:

query

No

MongoDB style query of your data. For example:

Builder supports the following operators: $eq $gt$in $lt $lte $ne $nin$and $not $or $nor$exists $type $elemMatch$gte $regex $options. For more information, including examples, see the Builder Querying Cheatsheet.

fields

No

Only include these fields. For example:

omit

No

Omit only these fields. For example:

limit

No

Max number of results to return. The default is 30 and the maximum is 100.

offset

No

Use to specify an offset for pagination of results. The default is 0.

For more detail, see this forum post and this forum post.

includeRefs

No

Include content of references in response.

cacheSeconds

No

Seconds to cache content. This sets the maximum age of the cache-control header response header. Set value higher for better performance, and lower for content that changes frequently.

staleCacheSeconds

No

Builder.io uses stale-while-revalidate caching at the CDN level. This means Builder always serves from edge cache and updates caches in the background for maximum possible performance. This also means that the more frequently content is requested, the fresher it is. The longest Builder holds something in stale cache is one day by default, but you can set this to be shorter if needed. We suggest keeping this high unless you have content that must change rapidly and gets very little traffic.

sort

No

Property to order results by, use 1 for ascending and -1 for descending

includeUnpublished

No

Include unpublished content in the response, rather than the default, which only includes published content.

noTraverse

No

Though the default is true, you can pass false to include Symbol JSON in the response. This is helpful if you want to render your page all at once such as in server-side rendering.

Next steps

For more details on querying, see the Querying Cheatsheet.


Need Expert help?

Reach out to us, and we will match you with a Builder expert.

Connect with us

Was this article helpful?