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:
- Go to Models.
- Select any model.
- Scroll down and click on the button labeled Try the API Explorer.
- 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.
- For this example, expand one of the areas under Content API.
- Click the Try it Out button.
- Under Query, accept the default of no-queries.
- Scroll down and click the Execute button.
- 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:
Supported Query Params
Optionally use to send targeting attributes. For example:
MongoDB style query of your data. For example:
Builder supports the following operators:
Only include these fields. For example:
Omit only these fields. For example:
Max number of results to return. The default is
Include content of references in response.
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.
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.
Property to order results by, use 1 for
Include unpublished content in the response, rather than the default, which only includes published content.
Though the default is
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.