API reference

Robolly features an on-demand API to render templates designed in our editor. Robolly API is very flexible as it returns the rendered file synchronously (the response is the rendered file, but Robolly can be also send a JSON data response if needed). To get started with Robolly API, you can sign up for a free trial, so you can set up your dynamic template.

https://api.robolly.com/templates/{TEMPLATE_ID}/renderGETRender link
https://api.robolly.com/templates/{TEMPLATE_ID}/render.jpgGETRender link
https://api.robolly.com/templates/{TEMPLATE_ID}/render.pngGETRender link
https://api.robolly.com/templates/{TEMPLATE_ID}/render.pdfGETRender link
https://api.robolly.com/templates/{TEMPLATE_ID}/render.mp4GETRender link
https://api.robolly.com/rd/{URL_BASE_64_DATA}.jpgGETHidden render link
https://api.robolly.com/rd/{URL_BASE_64_DATA}.pngGETHidden render link
https://api.robolly.com/rd/{URL_BASE_64_DATA}.pdfGETHidden render link

Classic API endpoints:

https://api.robolly.com/v1/templatesGETList templates
https://api.robolly.com/v1/templates/{TEMPLATE_ID}/accepted-modificationsGETList template elements
https://api.robolly.com/v1/video/renderPOSTRender a video
https://api.robolly.com/v1/rendersGETList renders


Authentication is required based on the specific template's settings. If "Require render link authentication" is turned off, the render link is secured based on the template ID, if the template ID is shared or publicly accessable, it's not secure any more.

If "Require render link authentication" is turned on, render link requires either signature (lean more about signed render link) or a Robolly API key to be included in the authorization header. For server-side use and automation platforms, we recommend to authenticate by including the API key inside the request headers:

Authorization: Bearer {ROBOLLY_API_KEY}

Render link is the most direct way to render a template. Render link works based on query parameters to pass any dynamic data into a template. Modifications via query parameters will differ from template to template. To pass a dynamic content into a specific element, make sure to you reference the element with its name in the query parameters. Some generic parameters in the query parameters are reserved.

Hidden render link looks like static file URL to hide the dynamic nature of normal render link. Where normal render link has visible modifications, a hidden render link uses base64url encoding to obscure the modifications into a static looking URL. A hidden render link may be a best fit in publickly accessible places (eg., HTML) where it's preferred to hide the dynamic nature of the render link.

# example of a render link

# example of the same render link but hidden
// Step 1: Create query parameters (must include template ID)
const query = new URLSearchParams({
	template: "TEMPATE_ID",
	text: "My dynamic text modification",
	// modifications go here

// Step 2: Encode query in base64Url
const encoded = Buffer.from(query, "utf8").toString("base64url");

// Step 3: Create the hidden render link (.jpg/.pdf/.png)
const url = `https://api.robolly.com/rd/${encoded}.jpg`;


Parameters inside a render link will differ from template to template due to dynamic modifications. However, some generic parameters in the query parameters are reserved:

sigSigning a render link prevents exploiting it by changing the data.
scaleMust be a number with min value 0.1 and max value 3. Scale adjusts the rendered output dimensions based on template's size. For example, if default template size is 1024x1024, with scale=2, the output will be 2048x2048. Doesn't do anything for the MP4 format.
dlIf present, the rendered file will get prompted for download instead of shown (when opening render link in browser manually)
jsonIf present, the response will be JSON (use "1" as the value). This parameter was specifically added for Active Pieces, Pabbly Connect and other platforms that cannot work with responses that include the file directly.
fpsOnly for MP4 format, controls FPS. Must be one of: 24, 30, 50, 60
durationOnly for MP4 format, controls video duration in milliseconds. Maximum value is 10000.

Dynamic modifications

Every element in template designed in Robolly editor is dynamically modifiable. To pass a dynamic content into a specific element, make sure to you reference the element with its name in the query parameters. Here's a breakdown of default behavior for passing in data to different types of elements.

Element typeDescription
textDynamically updates text content. Conditional styling is supported.
imageDynamically updates image path. Must be a path to a publicly accessible image file. Google Drive and Dropbox public links are supported.
rectDynamically updates rectangle or circle background color. Valid formats: red, #FF0000, linear-gradient(45deg, blue, red), rgb(255,255,0). Note that when using HEX format, the hashtag symbol (#) must be encoded (%23).
qrDynamically update QR code content. Must be a valid content for the selected QR type.

Detailed dynamic modifications

More dynamic modifications are also available for each element. The syntax for these detailed modifcations is {element-name}.{modification-type}. An example, to dynamically update text color of an element name title, it will be title.textColor=red.

Modification typeDescription
xX axis (px)
yY axis (px)
widthWidth (px)
heightHeight (px)
angleAngle (deg)
opacityOpacity (0 is 0%, 1 is 100%)
textStroke.colorText stroke color (HEX/RGBA, must have text stroke already)
textStroke.widthText stroke width (px, must have text stroke already)
background.typeBackground type (color/gradient)
background.colorBackground color (HEX/RGBA)
background.stops.$.colorBackground stop color (HEX/RGBA). Replace $ with 0/1/2/3 etc based on which stop you want to target.
fontSizeFont size (px)
lineHeightLine height (number)
borderRadiusBorder radius (px)
borderColorBorder color (HEX/RGBA)
borderWidthBorder width (px)
srcHTTP(S) source for image or video
objectFitObject fit for image or video (cover, contain, fill, fit)
letterSpacingLetter spacing (px)
textColorText color (HEX/RGBA)
textBackgroundColorText background color (HEX/RGBA)
fillColorSVG fill color (HEX/RGBA)
textContentText content
textAlignText alignment (left, center, right)
boxShadow.colorBox shadow color (HEX/RGBA)
boxShadow.blurRadiusBox shadow blur radius (px)
boxShadow.spreadRadiusBox shadow spread radius (px)
boxShadow.offsetXBox shadow offset X (px)
boxShadow.offsetYBox shadow offset Y (px)
filters.$.typeFilter object type (blur, saturate, brightness, contrast). Replace $ with 0/1/2/3 etc based on which filter you want to target.
filters.$.valueFilter object value (number). Replace $ with 0/1/2/3 etc based on which filter you want to target.

Example of dynamic modifications:

Note that element names (text-element-name etc.) are arbitrary and you need to use the corresponding names of elements in your template (you can name elements any way you want in our editor).

    ?text-element-name=lorem ipsum

In publicly accessible environments, a render link may be exploited by changing a query string parameter resulting in using up your monthly rendering quota. To prevent unauthorized changes, you can create an HMAC‑SHA256 signature using your API key and add the signature to a render link as a sig parameter. Then, you can disable unsigned requests in your template’s settings (find it in the template's render tab).

How to create signature:

  1. Create query string with modifications
  2. Create signature by signing the signature format (see below, notice there is intentionally not a question mark sign for query string) with your API key using HMAC‑SHA256
  3. Add signature to the query params of the render link (&sig=xxxxx)
Example signature format = 6416bcbab241242aa0b22ecb:jpg:text=lorem-ipsum

To test your signing function, try signing the above example and comparing with the result below. Test signature is the above example signed with secret robolly instead of an actual API key.

Test signature = 288d26be11b5af71920b4bd8693dc53b1c3364d34ea3cb00ec510d04d003ff37

Multi-page PDFs

Robolly supports rendering dynamic PDFs with multiple pages. Best way to start rendering multipage PDFs is to use the Multi PDF page at your Robolly dashboard to get a pre-generated render link or set up Google Sheets integration.

# Example render link (copied from Dashboard -> Multi PDF):

Rate limiting

On-demand rendering is rate limited and there is a hard limit of 3 renderings per second. We recommend making the API render request sequentially one by to as that's the most straightforward way of avoiding the rate limit.


When there is an error, the response will be json. The response structure will include errorCode and developerMessage.

Error code types:

render-errorGeneric render error
parameters-invalidInvalid request parameters
render-limit-exhaustedRender limit exhausted
authentication-failedMissing or wrong auth signature / auth header
timeoutRendering timout
rate-limitRate limit reached (too many requests per second)
error-unknownUnknown error
resource-not-foundWrong template ID or similar