# Convert {% hint style="info" %} Convert endpoints are part of the [Content Services API](https://docs.beefree.io/beefree-sdk/~/changes/480/apis/content-services-api). The Content Services API is available on [Beefree SDK plans that are Essentials or above](https://developers.beefree.io/pricing-plans). {% endhint %} ## Overview The Conversion Collection provides you with endpoints that enable you to convert templates from one format to another. With the [Email to Page](#email-to-page-conversion-important-behaviors) endpoint, you can easily convert your email JSON templates into page JSON. The [Page to Email](#page-to-email-conversion-important-behaviors) endpoint lets you turn your page JSON templates into email-ready JSON, with the option to disable the HTML sanitizer if needed. The Simple to Full JSON endpoint enables you to convert [Simple Schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) templates into full Beefree JSON templates that can be loaded in the builder. {% hint style="info" %} **Important:** For all endpoints in this category, the value for `collection` is `conversion`. When making API calls, replace the `collection` placeholder within the URL with `conversion` to execute the call. {% endhint %} ### Available Collection Value for Convert Endpoints The following table lists the collection values available in this category of endpoints, and their corresponding collection options. {% hint style="info" %} Note: The only collection value available for this category of endpoints is **conversion**. Therefore, all **{collection}** placeholders in the URL in this category should be replaced with **conversion**. {% endhint %} Prior to referencing the table, the following example shows how you can replace the **{collection}** placeholder with **conversion**. #### How to Replace the {collection} Placeholder The following example URL has a **{collection}** placeholder. This placeholder needs to be filled in with a **Collection Option** prior to making an API call. `https://api.getbee.io/v1/{collection}/simple-to-full-json` As an example, if you'd like to convert Simple Schema JSON to Full JSON using this endpoint, replace **{collection}** with conversion. The final URL to make the API call will be: `https://api.getbee.io/v1/conversion/simple-to-full-json` The following table provides a comprehensive reference of all available options based on what you'd like to convert. | Resource | Collection Options | | ---------------------- | ------------------------------------------ | | `/page-to-email` | | | `/email-to-page` | | | `/simple-to-full-json` | | | `/full-to-simple-json` | | ## Email to Page Conversion: Important Behaviors The Email to Page endpoint converts a JSON template created for email into a JSON template optimized for web pages. During this conversion, the following adjustments are applied: * **Remove AMP Carousel**\ Any AMP carousels included in the email template are removed, as these are not supported in the page format. * **Expand Content Area Width**\ The content width is expanded to 900px to fit the web page format, removing the width constraints typically applied to emails. * **Target Attributes**\ Target attributes will not be processed. Remove all link target attributes or set them to "Open a new page." Links will not be modified during the conversion. * **Remove Subject and Preheader**\ Email-specific metadata, such as the subject line and preheader text, is removed since these elements are not relevant in the page format. * **Retain Comments and Secondary Language**\ Comments and secondary language data in the email template are preserved in the conversion process. {% openapi src="" path="/v1/{collection}/email-to-page" method="post" %} [email-to-page-conversion.yaml](https://806400411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8c7XIQHfAtM23Dp3ozIC%2Fuploads%2FgOQRbAtHHm9dCLS7LaGx%2Femail-to-page-conversion.yaml?alt=media\&token=9f26e036-7937-45fd-a9da-474616a0e767) {% endopenapi %} ## Page to Email Conversion: Important Behaviors The Page to Email endpoint transforms a JSON template designed for a web page into a JSON template optimized for email. During this conversion process, the following adjustments are made: * **Remove Video Row Backgrounds**\ Video backgrounds applied to page rows are removed because email formats do not support video backgrounds. * **Replace Embedded Videos with Thumbnails**\ Embedded videos are replaced with thumbnail images. This ensures recipients can preview the content visually without the compatibility issues of embedded videos.\ **Note:** Hosted videos will not be converted. * **Remove Form Blocks**\ Any form blocks present in the page template are removed. * **Adjust Design Content Area Width**\ If the page width exceeds the maximum width supported by the email builder (900px), it is resized to fit within email constraints. * **Update Link Target Attributes**\ Target attributes will not be processed. Remove all link target attributes. Links will not be modified during the conversion. * **Sanitize Code**\ The endpoint sanitizes the code to ensure compatibility with email standards. When the sanitizer is disabled, the payload looks like this: ```json { "disableHtmlSanitizer": true, "template": { "page": ... } } ``` * **Handle Multi-Column Layouts**\ The email builder supports up to 12 columns, which is compatible with the page builder's column configurations. {% openapi src="" path="/v1/{collection}/page-to-email" method="post" %} [page-to-emai-conversion.yaml](https://806400411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8c7XIQHfAtM23Dp3ozIC%2Fuploads%2FHVtSywLb2VI9s2fpiYrm%2Fpage-to-emai-conversion.yaml?alt=media\&token=315f959d-a584-468a-a88e-6cf43f083a13) {% endopenapi %} ## Simple to Full JSON This section discusses what the `/simple-to-full-json` endpoint is and how you can use it for AI-driven designs. Beefree SDK template JSON is long and includes many properties. For this reason, it does not provide the best structure for training AI models in workflows that include AI-driven design creation. Beefree SDK's [Simple schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) is a lightweight alternative that is optimized for training AI models. [Simple schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema), which is several lines shorter than Beefree SDK's template JSON, is a great solution for AI-generated schemas. This endpoint accepts [Simple schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) as the body of the `POST` request, and returns the full Beefree SDK template JSON, which can then be loaded in the Beefree SDK editor for an end user to view and edit accordingly. There are many creative ways to use and implement this endpoint, because it provides a pathway to programmatically creating full Beefree SDK-compatible templates completely outside of the Beefree SDK builder. #### Request Parameters The API call accepts a `template` object, which is required to successfully perform the `/simple-to-full-json` API call. The following table describes this required object. | Name | Type | Required | Description | | ---------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `template` | JSON | Yes | A Beefree SDK template in simple JSON format ([see the schema in GitHub](https://github.com/mailupinc/simple-schema-beefree-sdk/blob/main/simple_template.schema.json)). | The following code snippet shows the template object as the body of the `POST` request. ```json { “template”:{...} } ``` {% hint style="info" %} **Note:** The [simple template JSON schema](https://github.com/mailupinc/simple-schema-beefree-sdk/blob/main/simple_template.schema.json) describes the request parameters, and the template object structure. {% endhint %} #### Object Parameters Nested within the Template Object The following table lists and describes both **required** and **optional** object parameters nested within the mandatory `template` object. This `template` object is the body of the `POST` request for the API call. | Name | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | String | ✅ Yes | Specifies the template type. Possible values include: `email`, `page`, `popup`. | | `rows` | Array | ✅ Yes | Array containing at least one row. Reference the [simple row schema](https://github.com/mailupinc/simple-schema-beefree-sdk/blob/main/simple_row.schema.json). | | `settings` | Object | ❌ No | Configuration settings. Reference the [Settings Object Parameters](#settings-object-parameters-request-greater-than-template-greater-than-settings) section for more information. | | `metadata` | Object | ❌ No | Metadata information. Reference the [Metadata Object Parameters section](#metadata-object-parameters-request-greater-than-template-greater-than-metadata) for more information. | #### **Settings Object Parameters** The following code snippet shows the optional `settings` object nested within the `template` object in the body of the `POST` request. ```json { “template”:{ "settings":{...}, ... } } ``` The following table lists and describes **optional** object parameters nested within the `settings` object. The settings object is nested within the mandatory `template` object. | Name | Type | Required | Description | | ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------- | | `linkColor` | String | ❌ No | The default color of the links within the template. | | `backgroundColor` | String | ❌ No | The background color of the template. | | `contentAreaBackgroundColor` | String | ❌ No | The background color of the content area. | | `width` | integer | ❌ No | **Important:** The width of the template must be between **320** and **1440** pixels. | #### **Metadata Object Parameters** The following code snippet shows the optional `metadata` object nested within the `template` object in the body of the `POST` request. ```json { “template”:{ "metadata":{...}, ... } } ``` The following table lists and describes **optional** object parameters nested within the `metadata` object. The `metadata` object is nested within the mandatory `template` object. | Name | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------- | | `lang` | string | ❌ No | The language code of the template (for example, `"en"`, `"fr"`). | | `title` | string | ❌ No | The title of the template. | | `description` | string | ❌ No | A short description of the template. | | `subject` | string | ❌ No | The subject line of the email (if applicable). | | `preheader` | string | ❌ No | The preheader text for the email (if applicable). | ## Simple to Full JSON > Transforms a simple JSON schema into a full JSON schema that can be easily loaded as a template within the Beefree SDK builder. ```json {"openapi":"3.0.0","info":{"title":"Simple to Full JSON","version":"1.0.0"},"servers":[{"url":"https://api.getbee.io","description":"Base URL for the API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Enter Dev Console API Key as Bearer token"}}},"paths":{"/v1/{collection}/simple-to-full-json":{"post":{"summary":"Simple to Full JSON","description":"Transforms a simple JSON schema into a full JSON schema that can be easily loaded as a template within the Beefree SDK builder. ","parameters":[{"name":"collection","in":"path","required":true,"description":"The collection ID or name","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Request body for the endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","description":"An object field for template","properties":{"type":{"type":"string","description":"A string field for type"},"rows":{"type":"array","description":"An array of objects for rows","items":{"type":"object","properties":{"name":{"type":"string","description":"A string field for name"},"columns":{"type":"array","description":"An array of objects for columns","items":{"type":"object","properties":{"weight":{"type":"integer","description":"An integer field for weight"},"modules":{"type":"array","description":"An array of strings for modules","items":{"type":"string"}}}}}}}},"settings":{"type":"object","description":"An object field for settings","properties":{"linkColor":{"type":"string","description":"A string field for linkColor"},"background-color":{"type":"string","description":"A string field for background-color"},"contentAreaBackgroundColor":{"type":"string","description":"A string field for contentAreaBackgroundColor"},"width":{"type":"integer","description":"An integer field for width"}}},"metadata":{"type":"object","description":"An object field for metadata","properties":{"lang":{"type":"string","description":"A string field for lang"},"title":{"type":"string","description":"A string field for title"},"description":{"type":"string","description":"A string field for description"},"subject":{"type":"string","description":"A string field for subject"},"preheader":{"type":"string","description":"A string field for preheader"}}}}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Full to Simple JSON {% hint style="warning" %} This endpoint is in beta. The Simple Schema currently doesn't support all modules and properties present in the full JSON Schema, so please note that some design details may not carry over when using this API. We'd love to hear about your experience working with this endpoint. Please share your feedback . We can't wait to hear from you! {% endhint %} The Full to Simple endpoint provides a service that converts Beefree SDK's rich design documents (Full JSON) into simplified representations ([Simple Schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema)). This enables a new layer of AI integration and workflows, making Beefree SDK's content understandable to large language models (LLMs) and other generative tools. If you’re building with LLMs or generative design systems, this endpoint is your bridge between rich visual design and structured AI-compatible data. When paired with the [Simple to Full conversion](#simple-to-full-json) endpoint, you'll unlock a complete AI-human collaborative design loop. ### Use Cases The Full to Simple endpoint is particularly useful in the following scenarios: * **AI Iteration Workflows**: Use the [Simple Schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) output to feed an AI agent that proposes changes or creates design variations. After AI-generated suggestions are returned in Simple Schema format from the AI agent, use the existing [Simple to Full endpoint](#simple-to-full-json) to convert back to full JSON and load the new version of the design in the Beefree SDK builder. From there, the end user can review the updated design, apply edits within the no-code builder, and [export](https://docs.beefree.io/beefree-sdk/~/changes/480/apis/content-services-api/export) the design once they reach a final version. * **Selective Design Adjustments by AI**: AI tools can target individual components in a simplified layout—for example, change a CTA, adjust text, or move sections—without dealing with full schema complexity. * **Training AI Models**: Convert your library of full Beefree templates into simplified JSON to use as training input for generative design agents, enforcing brand consistency or layout structure in AI-created outputs. ### Round-Trip Workflow When couple with the [Simple to Full endpoint](#simple-to-full-json), this endpoint lets you: 1. Export a full design created by a human in [Simple Schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) format. 2. Modify or generate variants using generative AI. 3. Convert the simplified output back to [full schema](#full-to-simple-json). 4. Reopen the design in the Beefree SDK builder for the end user to apply light edits, customize, and [export](https://docs.beefree.io/beefree-sdk/~/changes/480/apis/content-services-api/export).
### Request Parameters The following request parameter is required to perform the Full to Simple API call. | Name | Type | Required | Description | | ------ | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `page` | JSON | Yes | The full template structure in Beefree JSON format. This is the same structure returned by the builder or captured from its callbacks. | ## Full JSON to Simple > This endpoint converts a Beefree template's full JSON into a Simple Schema template. ```json {"openapi":"3.0.0","info":{"title":"Full JSON to Simple","version":"1.0.0"},"servers":[{"url":"https://api.getbee.io","description":"Base URL for the API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Enter Dev Console API Key as Bearer token"}}},"paths":{"/v1/{collection}/full-to-simple-json":{"post":{"summary":"Full JSON to Simple","description":"This endpoint converts a Beefree template's full JSON into a Simple Schema template.","parameters":[{"name":"collection","in":"path","required":true,"description":"The collection name. Replace the placeholder with \"conversion\".","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Request body for the endpoint","content":{"application/json":{"schema":{"type":"object","required":["page"],"properties":{"page":{"type":"object","description":"An object field for page","required":["template"],"properties":{"body":{"type":"object","description":"An object field for body","properties":{"container":{"type":"object","description":"An object field for container","properties":{"style":{"type":"object","description":"An object field for style","properties":{"background-color":{"type":"string","description":"A string field for background-color"}}}}},"content":{"type":"object","description":"An object field for content","properties":{"computedStyle":{"type":"object","description":"An object field for computedStyle","properties":{"linkColor":{"type":"string","description":"A string field for linkColor"},"messageBackgroundColor":{"type":"string","description":"A string field for messageBackgroundColor"},"messageWidth":{"type":"string","description":"A string field for messageWidth"}}},"style":{"type":"object","description":"An object field for style","properties":{"color":{"type":"string","description":"A string field for color"},"font-family":{"type":"string","description":"A string field for font-family"}}}}},"webFonts":{"type":"array","description":"An array of strings for webFonts","items":{"type":"string"}}}},"description":{"type":"string","description":"A string field for description"},"rows":{"type":"array","description":"An array of objects for rows","items":{"type":"object","properties":{"columns":{"type":"array","description":"An array of objects for columns","items":{"type":"object","properties":{"grid-columns":{"type":"integer","description":"An integer field for grid-columns"},"modules":{"type":"array","description":"An array of objects for modules","items":{"type":"object","properties":{"descriptor":{"type":"object","description":"An object field for descriptor","properties":{"computedStyle":{"type":"object","description":"An object field for computedStyle","properties":{"class":{"type":"string","description":"A string field for class"},"width":{"type":"string","description":"A string field for width"}}},"image":{"type":"object","description":"An object field for image","properties":{"alt":{"type":"string","description":"A string field for alt"},"href":{"type":"string","description":"A string field for href"},"prefix":{"type":"string","description":"A string field for prefix"},"src":{"type":"string","description":"A string field for src"},"target":{"type":"string","description":"A string field for target"}}},"style":{"type":"object","description":"An object field for style","properties":{"border-radius":{"type":"string","description":"A string field for border-radius"},"padding-bottom":{"type":"string","description":"A string field for padding-bottom"},"padding-left":{"type":"string","description":"A string field for padding-left"},"padding-right":{"type":"string","description":"A string field for padding-right"},"padding-top":{"type":"string","description":"A string field for padding-top"},"width":{"type":"string","description":"A string field for width"}}}}},"locked":{"type":"integer","description":"An integer field for locked"},"type":{"type":"string","description":"A string field for type"},"uuid":{"type":"string","description":"A string field for uuid"}}}},"style":{"type":"object","description":"An object field for style","properties":{"background-color":{"type":"string","description":"A string field for background-color"},"border-bottom":{"type":"string","description":"A string field for border-bottom"},"border-left":{"type":"string","description":"A string field for border-left"},"border-right":{"type":"string","description":"A string field for border-right"},"border-top":{"type":"string","description":"A string field for border-top"},"padding-bottom":{"type":"string","description":"A string field for padding-bottom"},"padding-left":{"type":"string","description":"A string field for padding-left"},"padding-right":{"type":"string","description":"A string field for padding-right"},"padding-top":{"type":"string","description":"A string field for padding-top"}}},"uuid":{"type":"string","description":"A string field for uuid"}}}},"container":{"type":"object","description":"An object field for container","properties":{"style":{"type":"object","description":"An object field for style","properties":{"background-color":{"type":"string","description":"A string field for background-color"},"background-image":{"type":"string","description":"A string field for background-image"},"background-position":{"type":"string","description":"A string field for background-position"},"background-repeat":{"type":"string","description":"A string field for background-repeat"}}}}},"content":{"type":"object","description":"An object field for content","properties":{"computedStyle":{"type":"object","description":"An object field for computedStyle","properties":{"hideContentOnDesktop":{"type":"integer","description":"An integer field for hideContentOnDesktop"},"hideContentOnMobile":{"type":"integer","description":"An integer field for hideContentOnMobile"},"rowColStackOnMobile":{"type":"integer","description":"An integer field for rowColStackOnMobile"},"rowReverseColStackOnMobile":{"type":"integer","description":"An integer field for rowReverseColStackOnMobile"},"verticalAlign":{"type":"string","description":"A string field for verticalAlign"}}},"style":{"type":"object","description":"An object field for style","properties":{"background-color":{"type":"string","description":"A string field for background-color"},"background-image":{"type":"string","description":"A string field for background-image"},"background-position":{"type":"string","description":"A string field for background-position"},"background-repeat":{"type":"string","description":"A string field for background-repeat"},"color":{"type":"string","description":"A string field for color"},"width":{"type":"string","description":"A string field for width"}}}}},"empty":{"type":"integer","description":"An integer field for empty"},"locked":{"type":"integer","description":"An integer field for locked"},"synced":{"type":"integer","description":"An integer field for synced"},"type":{"type":"string","description":"A string field for type"},"uuid":{"type":"string","description":"A string field for uuid"}}}},"template":{"type":"object","description":"An object field for template","properties":{"version":{"type":"string","description":"A string field for version"}}},"title":{"type":"string","description":"A string field for title"}}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}}}}}} ``` ### Full to Simple Limitations Consider the following behaviors and feature limitations when using the Full to Simple endpoint. Your conversion is limited to the existing [Simple Schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) only. * Any blocks not available in the Simple Schema will not be supported during conversion. * Refer to the [Simple Schema definitions](https://github.com/BeefreeSDK/beefree-sdk-simple-schema) to check which modules are supported. If you pass an unsupported module to the API: * It will be ignored silently — no error will be thrown. Only the properties defined in the [Simple Schema](https://docs.beefree.io/beefree-sdk/~/changes/480/data-structures/simple-schema) are supported. * If you pass an unsupported property within a supported module, that property will be ignored, and the related information will be lost. * Reference the [Simple Schema definitions](https://github.com/BeefreeSDK/beefree-sdk-simple-schema) for the list of supported properties. The following style-related properties are not supported in the Full to Simple JSON conversion: * `border-top`, `border-bottom`, `border-right`, `border-left` * `border-radius` When converting from Full to Simple, all border-related styles will be lost.