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.
The following table provides a few examples of URLs you can use to make specific types of requests.
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
HTTP Method: POST
Description: Transform JSON template to HTML.
The following table lists the parameters applicable for this request.
Content-Type: application/json
The following JSON displays an example request.
The following HTML displays an example response.
Endpoint: /message/plain-text
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a plain text document.
page
(JSON): The email JSON template to create the plain text for.
The following table lists the parameters for this endpoint.
The following section shows an example request:
The following section shows an example response:
URL: https://api.getbee.io/v1/{collection}/pdf
Method: POST
Description: Transform HTML and PDF settings to a JSON object with a PDF url.
The following table lists the parameters applicable for this request.
Content-Type: application/json
The following code sample shows an examples request with HTML and PDF settings.
The following code sample shows an examples response.
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
HTTP Method: POST
Description: Transform HTML and image settings into an image.
The following table lists the headers applicable for this request.
Content-Type: application/json
The following code sample shows an example response.
The following image is an example response.
application/jpg
The response includes the raw image data.
URL: https://api.getbee.io/v1/{collection}/merge
HTTP Method: POST
Description: Replace a Beefree template in JSON format.
The following table lists the request parameters.
Content-Type: application/json
The following table lists the request parameters for the replace array and whether or not they are optional.
The following code displays an example request of the "replace" array.
application/json
The JSON object containing the following parameters:
The following code displays an example response.
URL: https://api.getbee.io/v1/{collection}/merge-rows
HTTP Method: POST
Description: 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 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 following table lists the request parameters.
Content-Type: application/json
The following code displays an example request.
The following code displays an example response.
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
HTTP Method: POST
Description: Get a list of all the synced rows inside a template with their corresponding rowIdentifier
values.
The following table lists the request parameters.
Content-Type: application/json
The following code displays an example request.
The following code displays an example response.
The following table provides the name, type, and description for the response elements within the returned syncedRows
array.
URL: https://api.getbee.io/v1/{collection}/merge/index
HTTP Method: POST
Description: Reference an array of metadata objects from a Beefree template in JSON format.
The following table lists the request parameters.
Content-Type: application/json
The following JSON shows an example request.
application/json
The JSON object containing the following parameters:
The following JSON shows an example response.
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
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a JSON object with metadata (preheader and subject).
The following table lists the parameters for this endpoint.
*Note: Reference the optional parameters for the options
JSON in the following section.
The following table lists the optional parameters for making this request.
The following section shows an example request:
The following section shows an example response with the preheader and subject metadata in the JSON object:
v1/ai/sms
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a JSON object with the SMS text. Use this endpoint for summaries geared toward SMS.
The following table lists the parameters for this endpoint.
*Note: Reference the optional parameters for the options
JSON in the following section.
The following table lists the optional parameters for making this request.
The following code sample shows an example request.
The following code sample shows an example response.
v1/ai/summary
HTTP Method: POST
Description: The text endpoint accepts a JSON template and returns a JSON object with the summary text. This endpoint is for generating general summaries that can have multi-purpose use.
The following table lists the parameters for this endpoint.
*Note: Reference the optional parameters for the options
JSON in the following section.
The following table lists the optional parameters for making this request.
The following section shows an example request:
The following section shows an example response:
Collection | Available Resources |
---|---|
Type | Action | Example URL |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Required | Description |
---|---|---|---|
Name | Data Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Parameters | Type | Required or Optional | Description |
---|---|---|---|
Parameter | Type | Required or Optional | Description |
---|---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Parameter | Type | Required or Optional | Description |
---|---|---|---|
Name | Type | Required | Description |
---|---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Required | Description |
---|---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Required | Description |
---|---|---|---|
Name | Type | Description |
---|---|---|
/message
html
, pdf
, images
, merge
, index, plain-text
/page
html
, pdf
, images
, merge
, index
/popup
html
/amp
html
/template
brand
/ai
metadata
, sms
, summary
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
page
*
object
A Beefree template in JSON format
beautifulHtmlEnabled
*
boolean
This flag will force the API to return uncompressed HTML
page
JSON
Yes
The template's JSON. This is the template used to create the plain text document.
language
JSON
Optional
For multi-language templates, any valid language code sets the output language.
html
*
String
A full HTML document
page_size
String
Accepted values: letter (default), A4, A3, full
Full: a single page using 900px as page width. The page_orientation is always portrait when using this page size.
page_orientation
String
Accepted values: landscape (default), portrait
file_type
String
Accepted values: PDF
html
*
String
A Beefree HTML messag
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.
source*
Object
A Beefree template in JSON format.
replace*
Array
An array of objects that contain a JSON path and value to replace.
value*
String | Object
The value can be an object, such as a saved row. Or, it can be a string, such a hex color code. The value should be the same type as the value you want to match in your match expression.
path*
String
A JSON Path to the matching nodes in the source JSON.
Value
String | Object
Required
The value can be an object, such as a saved row. Or, it can be a string, such a hex color code. The value should be the same type as the value you want to match in your match expression.
Path
String
Required
A JSON Path to the matching nodes in the source JSON.
json
object
required
The updated Beefree template in JSON format. In the event of an error, the original source is returned.
html
string
required
The HTML message.
warnings
array
optional
An array of objects containing information about issues that occurred during the merge. If no warnings exist, then it is safe to save the updated JSON.
rows
Array
An array of Beefree rows in JSON format. The array accepts the following format: rows: [{row1json}, {row2json}]
template
JSON
A Beefree template in JSON format.
webFonts
This facilitates the addition of missing webfonts for messages associated with synced or saved rows. It allows you to provide a list of webfonts available in your host application to the editor. This information enables the editor to rectify missing webfonts during the merge process, ensuring consistent and accurate rendering of messages across synced or saved rows.
rowIdentifierLabel
String
The label used for identifying the rows added to the metadata key usually is guid.
rowIdentifierLabel
String
The label used for identifying the rows added to the metadata key usually is guid.
template
Array
The JSON of a template.
rowIndex
Number
The index of the row in the array of rows inside the Template.
rowIdentifier
String
The value of the rowIdentifier
(guid in most cases) for that specific row.
source*
object
A Beefree template in JSON format.
rows
array
required
An array of metadata objects containing row details, which can be saved in a database to create a reference (or relational table) to the rows associated with your template.
template
JSON
Yes
The template's JSON. This is the template used to create the AI-generated metadata.
options
JSON
No
Optional settings that instruct the output.*
toneOfVoice
string
Use this parameter to define a tone of voice for the response output. For example, you can include words such "Formal", "Humorous", or "Business" to instruct the AI's response.
instructions
string
Use this parameter to include extra instructions and fine tune the AI's response.
reportUsage
boolean
Use this parameter to return the usage data from OpenAI. Set this boolean to true or false.
language
string
Use this parameter to specify the output language for the response.
template
JSON
Yes
The template's JSON. This is the template used to create the AI-generated SMS text.
options
JSON
No
Optional settings that instruct the output.*
toneOfVoice
string
Use this parameter to define a tone of voice for the response output. For example, you can include words such "Formal", "Humorous", or "Business" to instruct the AI's response.
length
string
Must be one of the following options: "Concise", "Standard", or "Detailed".
instructions
string
Use this parameter to include extra instructions and fine tune the AI's response.
reportUsage
boolean
Use this parameter to return the usage data from OpenAI. Set this boolean to true or false.
language
string
Use this parameter to specify the output language for the response.
template
JSON
Yes
The template's JSON. This is the template used to create the AI-generated summary text.
options
JSON
No
Optional settings that instruct the output.*
toneOfVoice
string
Use this parameter to define a tone of voice for the response output. For example, you can include words such "Formal", "Humorous", or "Business" to instruct the AI's response.
length
string
Must be one of the following options: "Concise", "Standard", or "Detailed".
instructions
string
Use this parameter to return the usage data from OpenAI. Set this boolean to true or false.
reportUsage
boolean
Use this parameter to return the usage data from OpenAI. Set this boolean to true or false.
language
string
Use this parameter to specify the output language for the response.