Content Services API Reference
Last updated
Last updated
© Bee Content Design, Inc. San Francisco, CA | Part of Growens
The Content Services API Reference provides a comprehensive guide to utilizing the Content Services API, which leverages the REST architecture and HTTP protocol for making API calls. This reference document outlines the available collections, including /message, /page, /popup, /amp, /template, and /ai, detailing the resources for each collection. For every resource, this document includes its description, parameters, and example responses and requests.
To use the Content Services API you will first need to obtain a your API Key from the Beefree SDK Console.
To obtain an API Key, take the following steps:
Log into the Beefree SDK Console
Locate the application that you wish to work with, and click on Details
Locate the Content Services API section and click Create New API Key
Acknowledge the message that reminds you that if you exceed the number of API calls included in your plan, you may be charged for overages and click Create Key
Your API key will appear under the Content services API section of your application details.
The Content Services API uses API Keys to authenticate requests for resources. You can manage your API Keys within the Beefree SDK Console. All requests must be made over HTTPS and contain the following HTTP Header:
Authorization: Bearer {token}
API requests rate limits exist independently of API key’s monthly usage allowance.
By default, the API has the following rate limits:
Per minute: 500 requests
Per second: 100 requests
X-Rate-Limit: An integer representing the total number of requests available per cycle. Exceeding the limit per cycle results in a 429 error. (e.g. 500)
X-Rate-Limit-Remaining: An integer representing the number of remaining requests before the next cycle begins, and the count resets. (e.g. 100)
X-Rate-Limit-Reset: A Unix timestamp representing the time the next cycle will begin, and the count will reset.
Retry-After: A Unix timestamp representing the time the application may resume submitting requests.
All API access is over HTTPS, and accessed from the following URL:
https://api.getbee.io/v1/{collection}/{resource}
The following table lists the available collection option and corresponding resources for each collection.
/message
html, pdf, images, merge, index, plain-text
/page
html, pdf, images, merge, index
/popup
html
/amp
html
/template
brand
/ai
metadata, sms, summary
/conversion
email-to-page, page-to-email
The following table provides a few examples of URLs you can use to make specific types of requests.
Request HTML for email
https://api.getbee.io/v1/message/html
Landing Page
Request HTML for a landing page
https://api.getbee.io/v1/page/html
Popup
Request HTML for a popup
https://api.getbee.io/v1/popup/html
AMP
Request HTML for AMP
https://api.getbee.io/v1/amp/html
The following section provides detailed information for each of the resources associated with each collection mentioned in the previous section.
URL: https://api.getbee.io/v1/{collection}/html
Include the optional newbutton query string parameter and set its value to true to generate HTML button results optimized for Outlook. Reference HTML Outlook Button Rendering for additional details.
Endpoint: /message/plain-text
URL: https://api.getbee.io/v1/{collection}/pdf
Note: The response is a JSON string that will contain the URL of the temporary location of the PDF document. The file is available for 24 hours.
URL: https://api.getbee.io/v1/{collection}/image
Prior to using the image endpoint, ensure you reference the following information.
The HTML is rendered in a fixed window size of 1920x1080 to generate a screenshot, with default viewport widths of 320 pixels for mobile and 1024 pixels for desktop, which may cause cropped previews if the content exceeds these dimensions. A clipping size of 1920x1080 is applied, but it can be customized, and the scale factor adjusts to align the viewport and clipping dimensions. For improved results, using auto height with the size parameter is recommended.
html*
String
A Beefree HTML message.
size
String
Use “size” instead of “width” and “height” when you only know the width and want the height automatically calculated. Required if width and height are not defined.
width
Integer
The image width in pixels. Required if size is not defined.
height
Integer
The image height in pixels. Default applies a proportional value based on the given width, keeping the image aspect ratio. When the value is not proportional to the given width, either will occur: If it’s higher, the proportional value applies, or, if it’s lower, the image is cropped. Required if size is not defined.
file_type*
String
Accepts jpg or png.
URL: https://api.getbee.io/v1/{collection}/merge
URL: https://api.getbee.io/v1/{collection}/merge-rows
When utilizing this feature, it's important to consider adding a handle to the metadata. This handle serves a crucial role in functions such as onDeleteRow and onEditRow. In our provided example, we use a handle named guid. However, users have the flexibility to choose their own handle name according to their preferences and requirements. When selecting a handle name, we recommend you choose something descriptive and meaningful for ease of identification and management within your workflow.
URL: https://api.getbee.io/v1/{collection}/synced-rows
URL: https://api.getbee.io/v1/{collection}/merge/index
The resources in the AI collection accept your template JSON and use generative AI to return text within a JSON object to you.
Prior to getting started with the resources in this collection, ensure you have the following:
Superpowers subscription or higher
OpenAI AddOn installed and configured in your Beefree Developer Console
Content Services API key
Note: OpenAI billing costs apply in addition to the Content Services API billing.
v1/ai/metadata
v1/ai/sms
v1/ai/summary
The Conversion Collection provides you with endpoints that enable you to convert templates from one format to another. With the Email to Page endpoint, you can easily convert your email JSON templates into page JSON. The Page to Email endpoint lets you turn your page JSON templates into email-ready JSON, with the option to disable the HTML sanitizer if needed.
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.
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:
Handle Multi-Column Layouts The email builder supports up to 12 columns, which is compatible with the page builder's column configurations.
Transform HTML and image settings into an image.
The collection ID or name
JSON payload with HTML message and image settings
Accepts jpg or png
The image height in pixels
A BeeFree HTML message
Image size if width and height are not defined
The image width in pixels
The image response as a binary data in PNG format
Transform a JSON template into an HTML response.
The collection ID or name
JSON payload with the template
Flag to return beautified HTML
For multi-language templates, sets the output language using a valid language code
A BeeFree template in JSON format
The HTML response
The Merge Rows endpoint enables you to integrate custom fonts and resized images into your designs. It saves custom fonts within the template's JSON, ensuring the correct font is displayed. It also handles image resizing, particularly when the image's initial template width is narrower than the saved row's destination template. To use this endpoint, send your template and rows in JSON format. You will receive a response with an updated template. The rows requiring an update are identified by their rowIdentifier values.
The collection ID or name
JSON payload with the template and rows
Label for identifying rows, usually GUID
An array of Beefree rows in JSON format
A Beefree template in JSON format
List of available webfonts to rectify missing ones
Updated template with merged rows
Parameters required to generate plain text from a template.
A successful response with the plain text document.
Replace or update content in the template using a specific path and value.
Successful operation
The transformed HTML output.
The resulting updated JSON structure.
This endpoint accepts HTML and settings to generate a PDF document and provides a URL for the PDF.
Parameters required to generate a PDF from HTML.
The file type for the output.
A full HTML document to be transformed into a PDF.
The orientation of the PDF page.
The size of the PDF page.
A successful response with the PDF document URL.
The HTTP status code of the response.
Retrieve a list of synced rows from a template.
The collection name.
Parameters for the synced rows request.
The label used for identifying the rows added to the metadata key, usually GUID.
The JSON structure of the template.
A successful response with a list of synced rows.
Converts an email JSON template to a page JSON template, ensuring compatibility by converting or removing unsupported blocks.
JSON payload with the email template to be converted
A BeeFree template in JSON format
Successful conversion to page JSON template
The endpoint accepts a JSON template and returns a JSON object with metadata.
JSON template and options to generate metadata
Optional settings that provide additional instructions to the AI for metadata generation.
A JSON object representing the template structure.
A JSON object with metadata (preheader and subject).
Preheader text for the email.
"Ready to Bee a part of our user research project? Schedule your interview now!"Subject line for the email.
"BEE Pro: Let's Bee-gin! Join our user research project 🐝"Information about the token usage in the AI request.
This endpoint accepts a JSON template and options to generate a custom SMS.
Successful response with SMS.
"Ciao! Ti interessa partecipare a un progetto di ricerca utente con noi? Sarà una videochiamata di 30-45 minuti."This endpoint accepts a JSON template and options to generate a concise summary.
Successful response with summary.
"Vuoi partecipare a un progetto di ricerca utente con BEE Pro? Rispondi a Dalila per prenotare un colloquio video."Reference an array of metadata objects from a Beefree template in JSON format.
The collection ID or name
JSON payload containing the Beefree template
A Beefree template in JSON format
An array of metadata objects containing row details
Converts a page JSON template to an email JSON template, ensuring compatibility by converting or removing unsupported blocks. By default, the conversion sanitizes HTML modules, which can be disabled by setting a specific parameter.
JSON payload with the page template to be converted
Option to disable HTML sanitizer
trueA BeeFree template in JSON format
Successful conversion to email JSON template