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 access this data, write queries with dot notation and, optionally, MongoDB style operators.
For more details on querying, see the Querying Cheatsheet.
To start using the Content API, make sure to import the Builder SDK into your project.
To use the Builder Content API to retrieve data from your models, be sure to always provide the following request parameters in your queries:
- Required:
my-model-name(replace with your model's name) - Required:
apiKeyquery param (replace with your Public API Key)
As an example, you'd replace my-model-name with the name of your model, such as page, and YOUR_API_KEY with your own Public API Key.
https://cdn.builder.io/api/v3/content/my-model-name?apiKey=YOUR_API_KEYThis section covers the available Builder Content API query params.
Use your API key when integrating with Builder.
Set to true to fetch references and Symbols in the response. This provides a consistent experience between the Visual Editor and the live site.
For more information on enrich, read Fetching References and Symbols with enrich.
MongoDB style query of your data.
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.
Optionally use to send targeting attributes.
Only include these fields.
Omit only these fields.
Max number of results to return. The default is 30 and the maximum is 100.
Use to specify an offset for pagination of results. The default is 0.
To fetch all content beyond the limit of 100, use limit and offset together by paginating results and making multiple API calls as follows:
const limit = 100;
let offset = 0;
const pages = await getResults({limit, offset});
while(pages.length === (limit + offset)) {
offset += pages.length;
pages.push( ... (await getResults({ limit, offset})));
}
return pages;For more detail, see this forum post and this forum post.
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.
In this way, 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 ascending and -1 for descending.
The key is what you're sorting on, so the following example sorts by createdDate. and because the value is 1, the sort is ascending.
Include content entries in a response that are still in draft mode and unarchived.
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.
Set this to true to ensure you get the most up-to-date data. This may be particularly relevant for frequently changing content or situations where updated information is preferred.
This will bypass the default cache settings. Note that as a result response times will be significantly slower when using this option.
Only set cachebust to true in the SDKs or APIs for build-time requests, such as when statically generating Pages, as response times will be slow when bypassing all caching. We do not recommend it for runtime requests — such as when serving Pages.
Content API v3 is currently the default. Learn more in Content API Versions.
To experiment with the Content API, you can 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.
