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 access this data, write queries with dot notation and, optionally, MongoDB style operators.
For more details on querying, see the Querying Cheatsheet.
Note: Content published by Builder is immediately available to the Content API. If your application's visual interface does not reflect the changes you have made, check whether they have been published to the Content API.
Set up
To start using the Content API, make sure to import the Builder SDK into your project.
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
At the command line, install the Qwik SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
Install the Builder Angular SDK:
In your code, be sure to import the SDK:
Install the Builder Angular SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder plugin for Gatsby and the React SDK (the Builder SDK):
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
There's no Builder SDK package dependency when using the HTML API directly. You need an HTTP client to access the API, whether it's built into your framework or installed separately.
Install the Builder Angular SDK:
In your code, be sure to import the SDK:
At the command line, use npm to install the Builder SDK:
In your code, be sure to import the SDK:
Query requirements
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.
You can learn about the response structure using the Builder API Explorer.
No responses returned
If your API responses are coming back empty when querying, try the following:
- Verify API Key format. You must
apiKey, notapikey. - Ensure you've passed necessary targeting conditions. If your content has targeting conditions (like
urlPath,device, or custom user attributes), you must pass the corresponding user attributes in your API request to receive a response. - Check your content's status. Verify that your content is published and currently active if it is scheduled.
Query performance
Not all query parameters perform equally. To get the best response times from the Content API, structure your queries to take advantage of Builder's database indexing.
Optimized targeting attributes
The two most performant targeting attributes are urlPath and locale. These fields are database-indexed, which means Builder can resolve matching content entries significantly faster when either or both are included in userAttributes.
Including urlPath or locale when possible or logically relevant greatly improves performance. The majority of Builder content is targeted against at least one of these two attributes, and this pattern is heavily optimized at the infrastructure level.
Tips for efficient querying
The following tips can be used to improve efficiency when using the Content API.
- Always target by
urlPathorlocalewhen relevant. Queries that include these attributes consistently outperform queries that rely solely on other custom targeting attributes. - Avoid broad, untargeted queries at runtime. Using
noTargeting: trueor omittinguserAttributesentirely fetches all entries without the benefit of indexing. Reserve these patterns for build-time use cases like static generation. - Use
fieldsandomitto reduce payload size. Returning only the fields you need reduces both response time and bandwidth. - Use
cachebust: trueonly at build time. Bypassing the cache produces the freshest data but significantly increases response times. Do not use it for runtime requests. - Lean on stale-while-revalidate caching. Builder serves content from the CDN edge cache while revalidating in the background. Keep
staleCacheSecondshigh for low-traffic content to maximize this benefit.
Solve common query issues
If your API responses are missing entries or returning fewer results than expected, the following patterns are common causes.
- Draft entries do not have targeting. Draft entries in a model that have no targeting rules configured can interfere with query results. Review your model for unfinished draft entries and either configure targeting for them or remove them.
- Your content is expired. A large volume of expired entries can affect query performance and skew results. Use
excludeExpired: trueto filter these out, or addstartDate/endDatefilters in yourqueryparam to scope results to an active date range. - Your cache is stale. If you've recently published changes that aren't appearing, the CDN cache may be serving an older version. Use
cachebust: trueto bypass the cache and confirm the latest data. Only use this for debugging or build-time use, not runtime requests. - Pagination is limiting the response. The default
limitis 30 and the maximum per request is 100. If your model has more entries than that, uselimitandoffsettogether to paginate through all results.
Content API query params
This section covers the available Builder Content API query params.
apiKey
Use your API key when integrating with Builder.
Notice that Gatsby uses publicAPIKey rather than apiKey.
Notice that Gatsby uses publicAPIKey rather than apiKey.
The apiKey query param is required, as in the following example where YOUR_API_KEY is your Public API Key.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
enrich
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.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
enrichOptions
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.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is excluded.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a navigation model. The id, name, and data fields are included in the response. However, from the data field, the data.title is omitted.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.
For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.
fetchTotalCount
Adding this key to your request returns a totalCount key with the total number of results for the model. This number can be used for pagination or other use-cases where the total number of results is useful to know.
query
MongoDB style query of your data.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
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.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
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.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
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.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
The following is the same for Qwik, Vue, Solid, Svelte, React (beta) or React-Native SDK:
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel
This example retrieves an entry where the id matches abc123 and store it in this.content.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
This example retrieves an entry where the id matches abc123 and store it in this.content.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
When using the query field in fetchOneEntry(), you can filter and retrieve entries based on any fields in the JSON structure returned by Builder that match the value provided to the query.
This includes:
- Standard fields such as
id,name,meta,data, andlastUpdated - Any custom fields defined in your model, for example, a
productmodel.
Combine multiple query conditions to filter content more precisely. For example, query fields within the data object.
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.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
For example, the whole URL could be:
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
By default, data for all locales is returned. To limit results to a specific locale, include the locale value as a key before the actual query.
userAttributes
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.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
fields
Only include the specified fields from the response.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
omit
Exclude only specific fields from the response and return everything else.
When omit is used alongside fields, the response will include only the fields specified in fields and then exclude the fields specified in omit from that subset.
Use caution when combining these options to ensure the desired fields are included or excluded correctly in the response.
When you use both fields and omit in builder.get(), it first includes only the specified fields and then excludes those listed in omit in the response.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
omitHiddenLayers
When set to true, exclude hidden layers from the response.
When you use both fields and omit in builder.get(), it first includes only the specified fields and then excludes those listed in omit in the response.
For example, the whole URL could be:
noTargeting
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.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
The noTargeting option does not apply to Gen 2 frameworks.
limit
Maximum number of results to return. The default is 30 and the maximum is 100.
By default, Builder applies targeting rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all content entries, call builder.getAll() and set noTargeting to true in the options parameter.
By default, Builder applies targeting rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all content entries, call builder.getAll() and set noTargeting to true in the options parameter.
By default, Builder applies targeting rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all content entries, call builder.getAll() and set noTargeting to true in the options parameter.
By default, Builder applies targeting rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all content entries, call builder.getAll() and set noTargeting to true in the options parameter.
By default, Builder applies targeting rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all content entries, call builder.getAll() and set noTargeting to true in the options parameter.
For example, the whole URL could be:
To fetch all content beyond the limit of 100, use limit and offset together by paginating results and making multiple API calls as follows:
The following video demonstrates installing the React SDK:
offset
Use to specify an offset for pagination of results. The default is 0.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
To fetch all content beyond the limit of 100, use limit and offset together by paginating results and making multiple API calls as follows:
For more detail, see this forum post and this forum post.
includeRefs
Include content of references in response.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The includeRefs option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
cacheSeconds
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.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
staleCacheSeconds
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.
The minimum value for staleCacheSeconds is 1 hour, or 3600 seconds.
We recommend keeping this duration high unless you have low-traffic content that must update rapidly.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
sort
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.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
excludeExpired
Exclude content entries that have passed their scheduled end date from the response. Use this when querying without targeting attributes to ensure expired entries are not returned.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
excludeScheduled
Exclude content entries whose scheduled start date has not yet been reached. Use this to ensure only currently active entries are returned when querying without targeting attributes.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
includeUnpublished
Include content entries in a response that are still in draft mode and unarchived.
Important: You can restrict this option with a Space setting. See Restrict public API access below for details.
For important information regarding targeting and scheduling and the Content API, see Scheduling Behavior later in this document.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
published.$ne
Use published.$ne as a query filter to exclude entries based on their publish state. This uses the MongoDB-style "not equal", $ne, operator against the published field, which has three possible values: 'published', 'draft', and 'archived'.
The most common use is published.$ne=archived, which returns both published and draft entries while excluding archived ones.
The following video demonstrates installing the React SDK:
Because published.$ne can expose draft content, it is subject to the same access restriction as includeUnpublished. If your space has Restrict Public API Key from Querying Unpublished Content enabled, this filter is blocked for the public API key and requires a Private API Key. See Restrict public API access to unpublished content for details.
Restrict public API access to unpublished content
By default, the Public API Key can query draft and archived content using includeUnpublished: true or published.$ne filters. If you want to prevent public access to unpublished content, you can enable the Restrict Public API Key from Querying Unpublished Content setting.
When enabled:
- The public API key cannot use
includeUnpublished: trueorpublished.$nefilters. - Only a Private API Key can query draft or archived content.
This setting is useful for preventing accidental exposure of draft or unfinished content in production environments.
To enable this setting, go to Settings → Advanced Settings → Advanced in your Space Settings.
noTraverse
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.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
cachebust
true to ensure you get the most up-to-date data, bypassing the existing cache. This may be useful if you need to have The noTraverse option does not apply to Gen 2 frameworks. Use the enrich parameter instead.
For example, the whole URL could be:
The following video demonstrates installing the React SDK:
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.
If intentionally choosing to bypass Builder's cache, it is highly recommended to provide your own cache layer to reduce the impact of potential service disruptions.
Fetch modifications
Request functionality can be modified in the following ways.
fetch
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.
The fetch option does not apply to Gen 1 frameworks.
The fetch option does not apply to Gen 1 frameworks.
The fetch option does not apply to Gen 1 frameworks.
The fetch option does not apply to Gen 1 frameworks.
The fetch option does not apply to Gen 1 frameworks.
In some cases, you might need to override the global fetch() function to customize API calls, such as implementing caching or using custom HTTP agents. The following example demonstrates how to provide a custom fetch() function that integrates custom agents:
To improve efficiency, this next example customizes fetch() to cache API responses, reducing redundant network requests. By leveraging Angular’s HttpClient, fetch() makes sure that responses are stored and reused instead of making duplicate API calls.
This approach is particularly useful in scenarios where the same content needs to be retrieved multiple times, such as during hydration.
To customize how API calls are handled, you can override the global fetch() function by using custom HTTP agents. This means better control over network connections, such as keeping persistent connections alive to improve efficiency. The following example demonstrates how to integrate custom HTTP agents when making requests:
In server-side rendering (SSR) environments, it’s important to optimize API calls by caching responses. This prevents redundant requests, improves performance, and ensures content persists during hydration.
The following approach introduces a customFetch() function inside a service (BuilderService), which integrates Angular’s HttpClient to store and reuse API responses.
First, define the custom fetch() function in a new file calledBuilderService.ts:
In the resolver, inject BuilderService into the resolver and assign customFetch to the fetch option in fetchOneEntry().
Finally, make sure the custom fetch function is properly configured inapp.config.ts:
The fetch option does not apply to Gen 1 frameworks.
The fetch option does not apply to Gen 1 frameworks.
fetchOptions
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
Keep in mind that fetchOptions can be used regardless of whether or not fetch was modified, and is usable in both Gen 1 and Gen 2 SDKs.
Content API v3 is currently the default. Learn more in Content API Versions.
Scheduling behavior
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.
Scheduling and references
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.
What's next
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.
