API Endpoints for Row Management

Overview of API Endpoints for Rows

Beefree SDK provides robust APIs for managing rows. These API endpoints enable operations such as saving, retrieving, syncing, merging, and organizing rows, making them essential for maintaining design consistency and managing shared rows.

Row-Related API endpoints

1. Merge Rows API endpoints

   • Purpose: Updates linked rows across multiple designs by replacing outdated content with new versions. Ideal for batch-updating designs or maintaining consistent synced rows.

2. Synced Rows API endpoint

   • Purpose: Retrieves all rows marked as "synced," ensuring centralized tracking of synced rows across templates.

3. Index Rows API endpoint

   • Purpose: Generates metadata for template rows, enabling better organization and search capabilities. Create structured catalogs of rows with attributes like categories, names, or tags.

Row Endpoints and Descriptions

Merge Rows

Endpoint: POST https://api.beefree.io/v1/{collection}/merge-rows

Merge Rows

post

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.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection ID or name

Body

application/json

rowIdentifierLabelstringOptional

Label for identifying rows, usually GUID

templateobjectRequired

A Beefree template in JSON format

Responses

200

Updated template with merged rows

application/json

post

/v1/{collection}/merge-rows

HTTPcURLJavaScriptPython

POST /v1/{collection}/merge-rows HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1749

{
  "rowIdentifierLabel": "guid",
  "rows": [
    {
      "columns": [
        {
          "grid-columns": 12,
          "modules": [
            {
              "descriptor": {
                "computedStyle": {
                  "hideContentOnAmp": false,
                  "hideContentOnDesktop": false,
                  "hideContentOnHtml": false,
                  "hideContentOnMobile": false
                },
                "paragraph": {
                  "computedStyle": {
                    "linkColor": "#7747FF",
                    "paragraphSpacing": "16px"
                  },
                  "html": "<p>Updated paragraph block.</p>",
                  "style": {
                    "color": "#101112",
                    "direction": "ltr",
                    "font-family": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
                    "font-size": "16px",
                    "font-weight": "400",
                    "letter-spacing": "0px",
                    "line-height": "120%",
                    "text-align": "left"
                  }
                },
                "style": {
                  "padding-bottom": "10px",
                  "padding-left": "10px",
                  "padding-right": "10px",
                  "padding-top": "10px"
                }
              },
              "locked": false,
              "type": "mailup-bee-newsletter-modules-paragraph",
              "uuid": "29cd2a3d-fd76-4537-a91b-b8cb9872d8a3"
            }
          ],
          "style": {
            "background-color": "transparent",
            "border-bottom": "0px solid transparent",
            "border-left": "0px solid transparent",
            "border-right": "0px solid transparent",
            "border-top": "0px solid transparent",
            "padding-bottom": "5px",
            "padding-left": "0px",
            "padding-right": "0px",
            "padding-top": "5px"
          },
          "uuid": "56119ad2-574d-4122-8dd1-c1152b5f4879"
        }
      ]
    }
  ],
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#ffffff"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#7747FF",
            "messageBackgroundColor": "transparent",
            "messageWidth": "600px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, Helvetica, sans-serif"
          }
        },
        "webFonts": [
          {
            "fontFamily": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
            "name": "Alegreya",
            "url": "https://fonts.googleapis.com/css2?family=Alegreya:wght@100;200;300;400;500;600;700;800;900"
          },
          {
            "fontFamily": "'Arvo', 'Courier New', Courier, monospace",
            "name": "Arvo",
            "url": "https://fonts.googleapis.com/css2?family=Arvo:wght@100;200;300;400;500;600;700;800;900"
          }
        ]
      }
    },
    "title": ""
  }
}

200

Updated template with merged rows

{
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#ffffff"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#7747FF",
            "messageBackgroundColor": "transparent",
            "messageWidth": "600px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, Helvetica, sans-serif"
          }
        },
        "webFonts": [
          {
            "fontFamily": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
            "name": "Alegreya",
            "url": "https://fonts.googleapis.com/css2?family=Alegreya:wght@100;200;300;400;500;600;700;800;900"
          },
          {
            "fontFamily": "'Arvo', 'Courier New', Courier, monospace",
            "name": "Arvo",
            "url": "https://fonts.googleapis.com/css2?family=Arvo:wght@100;200;300;400;500;600;700;800;900"
          }
        ]
      },
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 12,
              "modules": [
                {
                  "descriptor": {
                    "paragraph": {
                      "html": "<p>Updated paragraph block.</p>",
                      "style": {
                        "color": "#101112",
                        "font-family": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
                        "font-size": "16px"
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      ],
      "warnings": [
        {
          "msg": "No merges were completed for row with identifier 0922fb70-f97e-4ae8-bcfe-0be9fd09a0d5"
        }
      ]
    }
  }
}

Index Rows

Endpoint: POST https://api.beefree.io/v1/{collection}/merge/index

Index Rows

post

Reference an array of metadata objects from a Beefree template in JSON format.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection ID or name

Body

application/json

sourceobjectRequired

A Beefree template in JSON format

Responses

200

An array of metadata objects containing row details

application/json

post

/v1/{collection}/merge/index

HTTPcURLJavaScriptPython

POST /v1/{collection}/merge/index HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1987

{
  "source": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#FFFFFF"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#FF819C",
            "messageBackgroundColor": "transparent",
            "messageWidth": "675px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, 'Helvetica Neue', Helvetica, sans-serif"
          }
        },
        "type": "mailup-bee-page-properties",
        "webFonts": [
          {
            "fontFamily": "'Montserrat', 'Trebuchet MS', 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', Tahoma, sans-serif",
            "name": "Montserrat",
            "url": "https://fonts.googleapis.com/css?family=Montserrat"
          }
        ]
      },
      "description": "BF-ecommerce-template",
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 6,
              "modules": [
                {
                  "descriptor": {
                    "computedStyle": {
                      "class": "center fixedwidth",
                      "width": 338
                    },
                    "image": {
                      "alt": "Image",
                      "href": "https://beefree.io",
                      "src": "https://d1oco4z2z1fhwp.cloudfront.net/templates/default/113/logo_1.png"
                    },
                    "style": {
                      "padding-bottom": "0px",
                      "padding-left": "15px",
                      "padding-right": "15px",
                      "padding-top": "5px",
                      "width": "100%"
                    }
                  },
                  "locked": false,
                  "type": "mailup-bee-newsletter-modules-image"
                },
                {
                  "descriptor": {
                    "computedStyle": {
                      "align": "center",
                      "hideContentOnMobile": true
                    },
                    "divider": {
                      "style": {
                        "border-top": "0px solid transparent",
                        "height": "20px",
                        "width": "100%"
                      }
                    },
                    "style": {
                      "padding-bottom": "10px",
                      "padding-left": "10px",
                      "padding-right": "10px",
                      "padding-top": "10px"
                    }
                  },
                  "locked": false,
                  "type": "mailup-bee-newsletter-modules-divider"
                }
              ],
              "style": {
                "background-color": "transparent",
                "padding-bottom": "0px",
                "padding-left": "0px",
                "padding-right": "0px",
                "padding-top": "30px"
              }
            }
          ],
          "container": {
            "style": {
              "background-color": "#FF819C",
              "background-image": "none",
              "background-position": "top left",
              "background-repeat": "no-repeat"
            }
          },
          "content": {
            "computedStyle": {
              "hideContentOnDesktop": false,
              "hideContentOnMobile": false,
              "rowColStackOnMobile": true
            },
            "style": {
              "background-color": "transparent",
              "color": "#333",
              "width": "675px"
            }
          },
          "locked": false,
          "metadata": {
            "guid": "test3",
            "name": "demo3"
          },
          "type": "two-columns-empty"
        }
      ],
      "template": {
        "name": "template-base",
        "type": "basic",
        "version": "2.0.0"
      },
      "title": "BF-ecommerce-template"
    }
  }
}

200

An array of metadata objects containing row details

[
  {
    "guid": "test3",
    "name": "demo3"
  }
]

Retrieve Synced Rows

Endpoint: POST https://api.beefree.io/v1/{collection}/synced-rows

Get Synced Rows

post

Retrieve a list of synced rows from a template.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection name.

Body

application/json

rowIdentifierLabelstringRequired

The label used for identifying the rows added to the metadata key, usually GUID.

Responses

200

A successful response with a list of synced rows.

application/json

400

Invalid input or request parameters.

post

/v1/{collection}/synced-rows

HTTPcURLJavaScriptPython

POST /v1/{collection}/synced-rows HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 812

{
  "rowIdentifierLabel": "guid",
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#ffffff"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#7747FF",
            "messageBackgroundColor": "transparent",
            "messageWidth": "600px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, Helvetica, sans-serif"
          }
        }
      },
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 12,
              "modules": [
                {
                  "descriptor": {
                    "paragraph": {
                      "html": "<p>I'm a new paragraph block.</p>",
                      "style": {
                        "color": "#101112",
                        "font-family": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
                        "font-size": "16px"
                      }
                    }
                  }
                }
              ],
              "metadata": {
                "guid": "0922fb70-f97e-4ae8-bcfe-0be9fd09a0d5"
              },
              "synced": true
            }
          ]
        }
      ]
    },
    "webFonts": [
      {
        "fontFamily": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
        "name": "Alegreya",
        "url": "https://fonts.googleapis.com/css2?family=Alegreya:wght@100;200;300;400;500;600;700;800;900"
      }
    ]
  }
}

{
  "syncedRows": [
    {
      "rowIdentifier": "0922fb70-f97e-4ae8-bcfe-0be9fd09a0d5",
      "rowIndex": 0
    }
  ]
}

Workflow Example

1. Retrieve Synced Rows: Use the Synced Rows endpoint to identify synced rows across designs.

2. Modify a Synced Row: Update the row and submit changes using the Merge Rows endpoint.

3. Verify Updates: Confirm that updates are reflected in all linked templates based on the Merge Rows response.