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.
When enriching data from the Content API, you may wish to exclude some fields or include only specific fields. When enrich is set to true, use the enrichOptions key to define precisely what information to receive.
enrichOptions accepts an object with two possible values:
- model: This key expects an object where each key is the name of a Model and each value is an object. Each object should include either the
fieldskey, representing which fields to include, theomitkey, representing which fields to exclude, or both keys. - enrichLevel: This key accepts a value greater than 0 and determines the depth level for enriching. For example, an
enrichLevelof 1 would return one additional nested model within the original response. The max level is 4.
MongoDB style query of your data.
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.
If you pass in a date value to the date param, you can override Builder's default behavior, which uses the server's current time.
For more details on user attributes, read targeting content. For important information regarding targeting and scheduling and the Content API, see Scheduling behavior later in this document.
Only include the specified fields from the response.
Exclude only specific fields from the response and return everything else.
Builder applies targeting and personalization rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all the content entries regardless of targeting rules, set noTargeting to true in the options parameter.
For important information regarding targeting and scheduling and the Content API, see Scheduling behavior later in this document.
Maximum 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.
For important information regarding targeting and scheduling and the Content API, see Scheduling behavior later in this document.
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.
Builder content scheduling using startDate and endDate is only checked if all of the following conditions are met:
userAttributesare included in the requestnoTargetingis not passed or is set tofalse
If these conditions are met, then Builder includes a content entry if the current time falls between the entry's startDate and endDate.
By default, Builder uses the server's current time. You can override this by passing a date value in userAttributes.date.
If a reference's schedule is invalid, it is skipped and not included in the response.
If you're debugging missing content in API responses, make sure userAttributes are included and that you are not disabling targeting or scheduling unintentionally.
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.
