Content Services API Reference

API key
Authorization
Rate Limits
HTTP Headers
API Root
HTML
PDF
Image
Merge
Index

API key

To use the Content Services API you will need to obtain an API key. To do so:

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 on 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 on Create Key
You’re done!

Authorization

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

HTTP Headers

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/{version}/{collection}/{resource}

Versions

Version	Released on
V1	4/25/2019
Beta	4/06/2019

Collections

Collection	Available Resources
/message	html, pdf, images, merge,index
/page	html, pdf, images, merge,index
/popup	html
/amp	html

Example URLs

Request HTML for email:

https://api.getbee.io/v1/message/html

Request HTML for a landing page:

https://api.getbee.io/v1/page/html

Request HTML for a popup:

https://api.getbee.io/v1/popup/html

Request HTML for AMP:

https://api.getbee.io/v1/amp/html

Structure

api.getbee.io				the api
	/v1			the version of the api
		/message /page /popup /amp		the collection of services
			/html	the resource from the collection of services

Resources

HTML

POST /html

Content-Type: application/json

Request

Parameters

page	object	required	A Beefree template in JSON format
beautifyHtmlEnabled	boolean	required	This flag will force the API to return uncompressed HTML

Example




{
  beautifyHtmlEnabled: false,
  page: {
     body: { ... },
     template: { ... },
     rows: { ... },
     title: '',
     description: ''
 }
}

Response

application/html

The HTML message

Status Codes

200	OK
400	Bad Request
401	Unauthorized
429	Too many requests
500	Server error

PDF

POST /pdf

Content-Type: application/json

Request

Parameters

html	string	required	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":"a","file_type":"pdf","page_size":"full","page_orientation":"portrait"}

Response

application/json

A JSON string that will contain the URL of the temporary location of the PDF document.

The file is available for 24 hours.




{"statusCode":200,"body":{"url":"https:\/\/pro-bee-beepro-pdf.s3.amazonaws.com\/public\/pdf\/87ElCDpHHk.pdf","filename":"87ElCDpHHk.pdf","page_size":"full","page_orientation":"portrait","content_type":"application\/pdf"}}

Status Codes

200	OK
400	Bad Request
401	Unauthorized
429	Too many requests
500	Server error

Request

Parameters

html	string	required	A Beefree HTML message
beautifyHtmlEnabled	boolean	required	This flag will force the API to return uncompressed HTML. Both page and popup endpoints do not compress HTML so will ignore this flag.

Image

POST /image

Content-Type: application/json

Request

Parameters

html	string	required	A Beefree HTML message
size	string	required if no width and height	Use “size” instead of “width” and “height” when you only know the width and want the height automatically calculated.
width	integer	required if no size	The image width in pixels
height	integer	required if no size	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: If it’s higher: the proportional value applies If it’s lower: the image is cropped
file_type	string	required	Accepted values: jpg png

Example




{
    "html": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\" /></head><body><div style='width:900px; margin: 30px;'>Hello World!</div></body></html>",
    "width": 215,
    "height": 125,
    "file_type": "jpg"
}

Response

application/jpg

The raw image data

Check out our sample code for a JavaScript method to convert an image to data URI here.

Status Codes

200	OK
400	Bad Request
401	Unauthorized
429	Too many requests
500	Server error

Merge

POST /merge

Content-Type: application/json

Request

Parameters

source

object

required

A Beefree template in JSON format.

replace

array

required

An array of objects that contain a JSON path and value to replace, as follows:

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




{
  "replace": [
    {
      "path": "$..style[?(@ == '#FFFFFF')]",
      "value": "#89cff0"
    },
    {
      "path": "$..rows[?(@.metadata.id=='')]",
      "value": { ... row json }
    }
  ],
  "source": { "page": { ... }  }
}

Response

application/json

The JSON object containing the following parameters:

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




{
    "html": "...",
    "json": {
        "page": { ...// BEE Template }
    },
    "warnings": [
        {
            "msg": "Your path $..style[?(@ == '#FFFFFF')] did not return any matching nodes",
            "param": "path",
            "location": "replace"
        },
        {
            "msg": "Your path $..style[?(@ == '#89cff0')] did not return any matching nodes",
            "param": "path",
            "location": "replace"
        }
    ]
}

Status Codes

200	OK
400	Bad Request
401	Unauthorized
422	Entity cannot be processed
429	Too many requests
500	Server error

Index

Request

Parameters

POST /merge/index

Content-Type: application/json

source	object	required	A Beefree template in JSON format.

Example




{
    "source": { "page": { ... }  }
}

Response

application/json

The JSON object containing the following parameters:

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




[
  {
    "name": "my saved row A"
    "guid": "some unique value"
  },
  {
    "name": "my saved row B"
    "guid": "some unique value"
  }
]

Status Codes

200	OK
400	Bad Request
401	Unauthorized
422	Entity cannot be processed
429	Too many requests
500	Server error