Content Services API Reference
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.
API Key
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}
Rate Limits
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.
API Root
All API access is over HTTPS, and accessed from the following URL:
https://api.getbee.io/v1/{collection}/{resource}
Collections
The following table lists the available collection option and corresponding resources for each collection.
Collection | Available Resources |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Example URLs
The following table provides a few examples of URLs you can use to make specific types of requests.
Type | Action | Example URL |
---|---|---|
Request HTML for email |
| |
Landing Page | Request HTML for a landing page |
|
Popup | Request HTML for a popup |
|
AMP | Request HTML for AMP |
|
Resources
The following section provides detailed information for each of the resources associated with each collection mentioned in the previous section.
HTML
URL: https://api.getbee.io/v1/{collection}/html
HTTP Method: POST
Description: Transform JSON template to HTML.
Request Parameters
The following table lists the parameters applicable for this request.
Name | Type | Description |
---|---|---|
| object | A Beefree template in JSON format |
| boolean | This flag will force the API to return uncompressed HTML |
| JSON | For multi-language templates, any valid language code sets the output language. |
Content-Type: application/json
Example
The following JSON displays an example request.
Response
The following HTML displays an example response.
Plain Text
Endpoint: /message/plain-text
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a plain text document.
Request Parameters
page
(JSON): The email JSON template to create the plain text for.
Request Parameters
The following table lists the parameters for this endpoint.
Name | Type | Required | Description |
---|---|---|---|
| JSON | Yes | The template's JSON. This is the template used to create the plain text document. |
| JSON | Optional | For multi-language templates, any valid language code sets the output language. |
Example Request
The following section shows an example request:
Example Response
The following section shows an example response:
PDF
URL: https://api.getbee.io/v1/{collection}/pdf
Method: POST
Description: Transform HTML and PDF settings to a JSON object with a PDF url.
Request Parameters
The following table lists the parameters applicable for this request.
Name | Data Type | Description |
---|---|---|
| String | A full HTML document |
| 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. |
| String | Accepted values: landscape (default), portrait |
| String | Accepted values: PDF |
Content-Type: application/json
Request
The following code sample shows an examples request with HTML and PDF settings.
Response
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.
Image
URL: https://api.getbee.io/v1/{collection}/image
HTTP Method: POST
Description: Transform HTML and image settings into an image.
Request Parameters
The following table lists the headers applicable for this request.
Name | Type | Description |
---|---|---|
| String | A Beefree HTML message. |
| 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. |
| Integer | The image width in pixels. Required if size is not defined. |
| 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. |
| String | Accepts jpg or png. |
Content-Type: application/json
Example Request
The following code sample shows an example response.
Example Response
The following image is an example response.
application/jpg
The response includes the raw image data.
Merge
URL: https://api.getbee.io/v1/{collection}/merge
HTTP Method: POST
Description: Replace a Beefree template in JSON format.
Request Parameters
The following table lists the request parameters.
Name | Type | Description |
---|---|---|
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. |
Content-Type: application/json
Replace Array
The following table lists the request parameters for the replace array and whether or not they are optional.
Parameters | Type | Required or Optional | Description |
---|---|---|---|
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. |
Example Request
The following code displays an example request of the "replace" array.
Response
application/json
The JSON object containing the following parameters:
Parameter | Type | Required or Optional | Description |
---|---|---|---|
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. |
Example Response
The following code displays an example response.
Merge Rows
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.
Request Parameters
The following table lists the request parameters.
Name | Type | Description |
---|---|---|
| Array | An array of Beefree rows in JSON format. The array accepts the following format: |
| JSON | A Beefree template in JSON format. |
| 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. | |
| String | The label used for identifying the rows added to the metadata key usually is guid. |
Content-Type: application/json
Example Request
The following code displays an example request.
Example Response
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.
Synced Rows
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.
Request Parameters
The following table lists the request parameters.
Name | Type | Description |
---|---|---|
| String | The label used for identifying the rows added to the metadata key usually is guid. |
| Array | The JSON of a template. |
Content-Type: application/json
Example Request
The following code displays an example request.
Example Response
The following code displays an example response.
Response Elements
The following table provides the name, type, and description for the response elements within the returned syncedRows
array.
Name | Type | Description |
---|---|---|
| Number | The index of the row in the array of rows inside the Template. |
| String | The value of the |
Index
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.
Request Parameters
The following table lists the request parameters.
Name | Type | Description |
---|---|---|
source* | object | A Beefree template in JSON format. |
Content-Type: application/json
Example
The following JSON shows an example request.
Response
application/json
The JSON object containing the following parameters:
Parameter | Type | Required or Optional | Description |
---|---|---|---|
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. |
Example
The following JSON shows an example response.
AI Collection
The resources in the AI collection accept your template JSON and use generative AI to return text within a JSON object to you.
Prerequisites
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.
Metadata (Preheader and Subject)
v1/ai/metadata
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a JSON object with metadata (preheader and subject).
Request Parameters
The following table lists the parameters for this endpoint.
Name | Type | Required | Description |
---|---|---|---|
| JSON | Yes | The template's JSON. This is the template used to create the AI-generated metadata. |
| JSON | No | Optional settings that instruct the output.* |
*Note: Reference the optional parameters for the options
JSON in the following section.
Optional parameters
The following table lists the optional parameters for making this request.
Name | Type | Description |
---|---|---|
| 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. |
| string | Use this parameter to include extra instructions and fine tune the AI's response. |
| boolean | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| string | Use this parameter to specify the output language for the response. |
Example Request
The following section shows an example request:
Example Response
The following section shows an example response with the preheader and subject metadata in the JSON object:
SMS
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.
Request Parameters
The following table lists the parameters for this endpoint.
Name | Type | Required | Description |
---|---|---|---|
| JSON | Yes | The template's JSON. This is the template used to create the AI-generated SMS text. |
| JSON | No | Optional settings that instruct the output.* |
*Note: Reference the optional parameters for the options
JSON in the following section.
Options parameters
The following table lists the optional parameters for making this request.
Name | Type | Description |
---|---|---|
| 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. |
| string | Must be one of the following options: "Concise", "Standard", or "Detailed". |
| string | Use this parameter to include extra instructions and fine tune the AI's response. |
| boolean | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| string | Use this parameter to specify the output language for the response. |
Example Request
The following code sample shows an example request.
Example Response
The following code sample shows an example response.
Summary
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.
Request Parameters
The following table lists the parameters for this endpoint.
Name | Type | Required | Description |
---|---|---|---|
| JSON | Yes | The template's JSON. This is the template used to create the AI-generated summary text. |
| JSON | No | Optional settings that instruct the output.* |
*Note: Reference the optional parameters for the options
JSON in the following section.
Options parameters
The following table lists the optional parameters for making this request.
Name | Type | Description |
---|---|---|
| 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. |
| string | Must be one of the following options: "Concise", "Standard", or "Detailed". |
| string | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| boolean | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| string | Use this parameter to specify the output language for the response. |
Example Request
The following section shows an example request:
Example Response
The following section shows an example response:
Last updated