API

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.

Available endpoints:

EndpointMethodType
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/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
https://api.robolly.com/v1/templatesGETReturns a list of templates

Authentication

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
https://api.robolly.com/templates/6416bcbab241242aa0b22ecb/render.jpg?image=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1528543606781-2f6e6857f318%3Fixid%3DMnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8%26ixlib%3Drb-1.2.1%26auto%3Dformat%26w%3D1500%26q%3D80&profile-photo=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1599834562135-b6fc90e642ca%3Fixid%3DMnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8%26ixlib%3Drb-1.2.1%26auto%3Dformat%26w%3D600%26q%3D80&name=Martie+Pitts&handle=mpitts&tweet=So+much+needs+to+change+with+track+and+field+over+here.+So+much%21+The+way+we+tell+our+narratives%2C+the+tone%2C+the+atmosphere%2C+fan+engagement%2C+event+structure+and+cohesion...+So%2C+so+much.+Athletes+need+to+feel+comfortable+enough+to+be+themselves.

# example of the same render link but hidden
https://api.robolly.com/rd/aW1hZ2U9aHR0cHMlM0ElMkYlMkZpbWFnZXMudW5zcGxhc2guY29tJTJGcGhvdG8tMTUyODU0MzYwNjc4MS0yZjZlNjg1N2YzMTglM0ZpeGlkJTNETW53eE1qQTNmREI4TUh4d2FHOTBieTF3WVdkbGZIeDhmR1Z1ZkRCOGZIeDglMjZpeGxpYiUzRHJiLTEuMi4xJTI2YXV0byUzRGZvcm1hdCUyNnclM0QxNTAwJTI2cSUzRDgwJnByb2ZpbGUtcGhvdG89aHR0cHMlM0ElMkYlMkZpbWFnZXMudW5zcGxhc2guY29tJTJGcGhvdG8tMTU5OTgzNDU2MjEzNS1iNmZjOTBlNjQyY2ElM0ZpeGlkJTNETW53eE1qQTNmREI4TUh4d2FHOTBieTF3WVdkbGZIeDhmR1Z1ZkRCOGZIeDglMjZpeGxpYiUzRHJiLTEuMi4xJTI2YXV0byUzRGZvcm1hdCUyNnclM0Q2MDAlMjZxJTNEODAmbmFtZT1NYXJ0aWUrUGl0dHMmaGFuZGxlPW1waXR0cyZ0d2VldD1TbyttdWNoK25lZWRzK3RvK2NoYW5nZSt3aXRoK3RyYWNrK2FuZCtmaWVsZCtvdmVyK2hlcmUuK1NvK211Y2glMjErVGhlK3dheSt3ZSt0ZWxsK291cituYXJyYXRpdmVzJTJDK3RoZSt0b25lJTJDK3RoZSthdG1vc3BoZXJlJTJDK2ZhbitlbmdhZ2VtZW50JTJDK2V2ZW50K3N0cnVjdHVyZSthbmQrY29oZXNpb24uLi4rU28lMkMrc28rbXVjaC4rQXRobGV0ZXMrbmVlZCt0bytmZWVsK2NvbWZvcnRhYmxlK2Vub3VnaCt0bytiZSt0aGVtc2VsdmVzLiZ0ZW1wbGF0ZT02NDE2YmNiYWIyNDEyNDJhYTBiMjJlY2I.jpg
// 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

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:

ParameterDescription
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.
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. This parameter was specifically added for Pabbly Connect which cannot work with responses that includes the file directly.

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)
qrDynamically update QR code content. Must be a valid content for the selected QR type.

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).

https://api.robolly.com/templates/{TEMPLATE_ID}/render.jpg
    ?text-element-name=lorem ipsum
    &image-element-name=https://unsplash.com/photos/3T-De1z7Jj8
    &rect-element-name=#FFFF00
    &qr-element-name=https://robolly.com

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)
Signature format = TEMPLATE_ID:OUTPUT_TYPE:QUERY_STRING
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

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.

Errors

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

Error code types:

CodeDescription
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