REST API for retrieving published content from Builder.io models. Supports filtering via MongoDB-style queries, targeting by user attributes, locale, and URL path. Returns paginated JSON results with support for enriched references and nested content symbols.
openapi: 3.0.3
info:
title: Builder.io Content API
version: v3
description: >-
REST API for retrieving published content from Builder.io models. Supports
filtering via MongoDB-style queries, targeting by user attributes, locale,
and URL path. Returns paginated JSON results with support for enriched
references and nested content symbols.
contact:
name: Builder.io Support
url: https://www.builder.io/c/docs/content-api
termsOfService: https://www.builder.io/m/legal/privacy-policy
license:
name: Proprietary
url: https://www.builder.io/m/legal/privacy-policy
servers:
- url: https://cdn.builder.io/api/v3
description: Builder.io CDN API
security:
- apiKeyQuery: []
tags:
- name: Content
description: Retrieve and query published content entries from Builder.io models.
paths:
/content/{model}:
get:
operationId: getContent
summary: Query content entries by model
description: >-
Retrieves published content entries for a given model name. Supports
MongoDB-style query filters, user attribute targeting, locale,
pagination, and field selection. Results are sorted by priority
by default.
tags:
- Content
parameters:
- name: model
in: path
required: true
description: The name of the Builder.io content model to query.
schema:
type: string
example: page
- name: apiKey
in: query
required: true
description: Your public Builder.io API key.
schema:
type: string
example: YOUR_PUBLIC_API_KEY
- name: limit
in: query
required: false
description: Maximum number of results to return. Maximum value is 100.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: offset
in: query
required: false
description: Number of results to skip for pagination.
schema:
type: integer
minimum: 0
default: 0
- name: query
in: query
required: false
description: >-
MongoDB-style JSON query filter applied to content fields.
Example: {"data.slug":{"$eq":"my-page"}}
schema:
type: string
- name: userAttributes
in: query
required: false
description: >-
JSON object of user attributes used for targeting and personalization.
Example: {"urlPath":"/about","country":"US"}
schema:
type: string
- name: url
in: query
required: false
description: >-
The current page URL used for targeting by urlPath. Used as a
shorthand for setting userAttributes.urlPath.
schema:
type: string
format: uri
- name: locale
in: query
required: false
description: The locale code for localized content retrieval (e.g., "en-US").
schema:
type: string
- name: enrich
in: query
required: false
description: >-
When true, enriches references and Symbol blocks with their
full content data instead of returning only IDs.
schema:
type: boolean
default: false
- name: fields
in: query
required: false
description: >-
Comma-separated list of fields to include in the response.
Reduces payload size by returning only specified fields.
schema:
type: string
example: id,name,data
- name: includeRefs
in: query
required: false
description: When true, includes referenced content objects inline.
schema:
type: boolean
default: false
- name: cacheSeconds
in: query
required: false
description: Override the CDN cache duration in seconds.
schema:
type: integer
responses:
'200':
description: A paginated list of content entries matching the query.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentListResponse'
example:
results:
- id: abc123def456
name: Home Page
published: published
modelId: page
priority: 0
firstPublished: 1700000000000
lastUpdated: 1717000000000
data:
title: Welcome to Our Site
description: The home page of our website.
blocks: []
'400':
description: Bad request — invalid query parameters or missing apiKey.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized — invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/content/{model}/{id}:
get:
operationId: getContentById
summary: Get a single content entry by ID
description: >-
Retrieves a single content entry from a Builder.io model by its unique ID.
tags:
- Content
parameters:
- name: model
in: path
required: true
description: The name of the Builder.io content model.
schema:
type: string
example: page
- name: id
in: path
required: true
description: The unique ID of the content entry.
schema:
type: string
example: abc123def456abc123def456abc12345
- name: apiKey
in: query
required: true
description: Your public Builder.io API key.
schema:
type: string
- name: enrich
in: query
required: false
description: When true, enriches referenced content inline.
schema:
type: boolean
default: false
responses:
'200':
description: The content entry matching the given ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentEntry'
'404':
description: Content entry not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
apiKeyQuery:
type: apiKey
in: query
name: apiKey
description: Public API key for your Builder.io space.
schemas:
ContentListResponse:
type: object
description: Paginated list of content entries.
properties:
results:
type: array
items:
$ref: '#/components/schemas/ContentEntry'
required:
- results
ContentEntry:
type: object
description: >-
A single published content entry from a Builder.io model.
properties:
'@version':
type: integer
description: Schema version of the content entry.
example: 2
id:
type: string
description: Unique identifier for the content entry.
example: abc123def456abc123def456abc12345
name:
type: string
description: Human-readable name of the content entry.
example: Home Page
published:
type: string
enum:
- published
- draft
- archived
description: Publication status of the content entry.
example: published
modelId:
type: string
description: The model type identifier for this content.
example: page
priority:
type: number
description: Sort priority used when multiple entries match a query.
example: 0
firstPublished:
type: integer
description: Unix timestamp (milliseconds) when first published.
example: 1700000000000
lastUpdated:
type: integer
description: Unix timestamp (milliseconds) of the last update.
example: 1717000000000
startDate:
type: integer
description: >-
Unix timestamp (milliseconds) after which the entry becomes active.
Used for scheduled publishing.
example: 1717000000000
endDate:
type: integer
description: >-
Unix timestamp (milliseconds) after which the entry is no longer served.
example: 1719600000000
variations:
type: object
description: >-
Map of variation IDs to variation data for A/B testing.
additionalProperties:
$ref: '#/components/schemas/ContentVariation'
testVariationId:
type: string
description: ID of the winning or current test variation.
testVariationName:
type: string
description: Name of the current test variation.
data:
type: object
description: >-
The model-specific field data for this content entry. Structure
varies by model definition.
additionalProperties: true
properties:
blocks:
type: array
description: Array of Builder visual editor block elements.
items:
$ref: '#/components/schemas/BuilderElement'
title:
type: string
description: Page or content title field.
url:
type: string
description: URL path associated with this content entry.
ContentVariation:
type: object
description: A/B test variation data attached to a content entry.
properties:
id:
type: string
description: Unique ID of this variation.
name:
type: string
description: Name of this variation.
testRatio:
type: number
description: Traffic percentage (0–1) allocated to this variation.
minimum: 0
maximum: 1
data:
type: object
description: Override data for this variation.
additionalProperties: true
BuilderElement:
type: object
description: >-
A visual element node in the Builder.io page tree.
properties:
'@type':
type: string
description: Type discriminator for Builder elements.
example: '@builder.io/sdk:Element'
'@version':
type: integer
description: Schema version of this element.
id:
type: string
description: Unique identifier for this element.
tagName:
type: string
description: HTML tag to render for this element.
example: div
layerName:
type: string
description: Display name shown in the Builder editor layer panel.
children:
type: array
description: Nested child elements.
items:
$ref: '#/components/schemas/BuilderElement'
component:
type: object
description: Component binding for this element.
properties:
name:
type: string
description: The registered component name.
example: Hero
options:
type: object
description: Props passed to the component.
additionalProperties: true
responsiveStyles:
type: object
description: CSS styles keyed by breakpoint (large, medium, small, xsmall).
properties:
large:
type: object
additionalProperties:
type: string
medium:
type: object
additionalProperties:
type: string
small:
type: object
additionalProperties:
type: string
xsmall:
type: object
additionalProperties:
type: string
bindings:
type: object
description: Dynamic JS expression bindings for element properties.
additionalProperties:
type: string
properties:
type: object
description: Static HTML attribute key-value pairs.
additionalProperties:
type: string
actions:
type: object
description: Event handler expressions keyed by event name.
additionalProperties:
type: string
repeat:
type: object
description: List repeat configuration for rendering collections.
nullable: true
properties:
collection:
type: string
description: JS expression resolving to the collection to iterate.
itemName:
type: string
description: Variable name for each item in the collection.
ErrorResponse:
type: object
description: Standard error response body.
properties:
error:
type: string
description: Error message describing what went wrong.
example: Unauthorized
statusCode:
type: integer
description: HTTP status code.
example: 401