Content Services API Reference

  1. API key
  2. Authorization
  3. Rate Limits
  4. HTTP Headers
  5. API Root
  6. HTML
  7. PDF
  8. Image
  9. Merge
  10. Index

API key

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

  1. Log into the BEE Plugin Developer Portal
  2. Locate the application that you wish to work with, and click on Details
  3. Locate the Content Services API section and click on Create New API Key
  4. Acknowledge the message that reminds you that if you exceeds the number of API calls included in your plan, you may be charged for overages and click on Create Key
  5. You’re done!

Authorization

Bee API uses API Keys to authenticate requests for resources.  You can manage your API Keys within the Developer Portal.  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 Bee 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

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

Structure

api.getbee.io the api
/v1 the version of the api
  • /message
  • /page
  • 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 Bee Plugin template in JSON format

    Example

    
    
    
    {
      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 Bee Plugin HTML message
    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

    Image

    POST /image

    Content-Type: application/json

    Request

    Parameters

    html string required A Bee Plugin HTML message
    width integer required The image width in pixels
    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:

    • If it’s higher: the proportional value applies
    • If it’s lower: the image is cropped
    file_type string required Accepted values:

    • jpg
    • png (coming soon)

    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

    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 Bee Plugin template in JSON format.
    replace array required An array of objects that contain a JSON path and value to replace, as follows:

    value string 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 BEE Plugin 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 /index

    Content-Type: application/json

    source object required A Bee Plugin 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

    
    
    
    {
        "rows": [
            {
              "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