BUILDER

Resources

Ɨ

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

ā˜°

Home

Forum

Blog

Github

Login

Signup

This page was made in Builder!

Builder Content API

Usage

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 via url parameters to allow you to get exactly the data you need. The best way to get familiar with the API is to explore it using your personalized api explorer, which you can find by clicking the blue button below.

Try Out the Interactive API Explorer

Sample Request and Response

curl https://builder.io/api/v2/content/YOUR_MODEL_NAME?apiKey=YOUR_API_KEY

# Example response
# {
#   "results": [
#     {
#       "id": "c923kd89",
#       "name": "My first homepage",
#       "data: {
#         "customField": "customValue"
#          ...
#       }
#    ]
# }

Supported Query Params

NameRequiredDescription

apiKey

Yes

Your API key

userAttributes.*

No

Optionally use this to send targeting attributes, e.g.:

&userAttributes.device=desktop
&userAttributes.urlPath=/about
&userAttributes.userLoggedIn=true

query.*

No

Mongodb style query of your data. E.g.:

&query.data.id=abc123
&query.data.myCustomField=someValue
&query.data.someNumber.$ne=20

fields

No

Only include these fields. E.g.

&fields=id,name,data.customField

omit

No

Omit only these fields, E.g.:

&omit=data.bigField,data.blocks

limit

No

Max number of results to return. Default is 1

&limit=10

offset

No

Results offset (for pagination). Default is 0

&offset=10

includeRefs

No

Include content of references in response

&includeRefs=true

cacheSeconds

No

Seconds to cache content (sets the max-age of the cache-control header response header). Make higher for better performance, and lower for content that will change more frequently

&cacheSeconds=1230

staleCacheSeconds

No

Builder.io uses state-while-revalidate caching at the CDN level. This means we always serve from edge cache and update caches in the background for maximum possible performance. This also means that the more frequently content is requested, the more fresh it will be. The longest we will ever hold something in stale cache is 1 day by default, and you can set this to be shorter yourself as well. We suggest keeping this high unless you have content that must change rapidly and gets very little traffic

&staleCacheSeconds=86400

sort

No

Property to order results by, use 1 for ascending and -1 for descending

&sort.createdDate=-1
&sort.data.myCustomField=1

includeUnpublished

No

Include unpublished (draft) content in the response, rather than the default only include published content

&includeUnpublished=true

Up next

GraphQL API

Questions or comments?

Give us a chat, we respond quickly and are here to help!

Chat Us Now
Was this article helpful?