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