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_KEYYou can learn about the response structure using the Builder API Explorer.
This section covers the available Builder Content API query params.
Use your API key when integrating with Builder.
Set it to true include references and Symbols in the response, ensuring consistency 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.
Use it to specify targeting attributes, such as urlPath, device, and any of the defined custom targeting, to fetch the most relevant entry when the model contains multiple entries.
By default, the response is limited to one entry. Without targeting attributes, it will only include the topmost entry.
For more details on User Attributes, read targeting content.
Only include the specified fields from the response.
Exclude only specific fields from the response and return everything else.
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 . Set value higher for better performance, and lower for content that changes frequently.
Builder uses stale-while-revalidate caching at the CDN level, serving content from the edge cache while updates occur in the background for optimal performance.
The more frequently content is requested, the fresher it becomes. By default, Builder holds content in the stale cache for up to one day, but you can adjust this to a shorter duration if needed.
We recommend keeping this duration high unless you have low-traffic content that must update rapidly.
Use the property to order results by setting the value to 1 for ascending and -1 for descending.
The key specifies the field to sort on. For example, sorting by createdDate with a value of 1 results in ascending order.
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.
Use the fetch option to override the default behavior of the global fetch() function used in the API.
This is helpful for:
- Adding specific headers or handling authentication
- Using libraries like Axios
- Defining custom HTTP request logic, such as integrating custom agents
The fetch property expects a function with the same parameters as the global fetch() function. It takes url.href as the first parameter and optionally a configuration object as the second.
For more information, see fetch() parameters.
Specifies additional RequestInit options to configure the overridden fetch request, including:
headersfor custom request headerscredentialsto control authenticationkeepalivefor background requests and sending analyticsmethodto define the HTTP method
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.
