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.

Render link endpoints:

Classic API endpoints:

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

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

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

How to create hidden render link (node.js example)

// 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:

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.

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.

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=rgb(255,255,0)
    &qr-element-name=https://robolly.com
    &text-element-name.textColor=red
    &text-element-name.opacity=0.5

Signed render link

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

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):
https://api.robolly.com/v1/pdf/render/?multipdfId=1&t[0][id]=2&t[0][uptitle]={{REPLACE_ME}}&t[0][names]={{REPLACE_ME}}&t[0][date]={{REPLACE_ME}}&t[0][time]={{REPLACE_ME}}&t[0][place]={{REPLACE_ME}}&t[0][address]={{REPLACE_ME}}&t[1][id]=6549f01ab90ef2c52cf99571&t[1][uptitle]={{REPLACE_ME}}&t[1][names]={{REPLACE_ME}}&t[1][date]={{REPLACE_ME}}&t[1][time]={{REPLACE_ME}}&t[1][place]={{REPLACE_ME}}&t[1][address]={{REPLACE_ME}}

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.

List renders

GET https://api.robolly.com/v1/renders

Returns a list of your renders. The renders are returned sorted by creation date, with the most recent render appearing first.

Parameters

id string
A specific ID of the render.

paginationCursorNext string
A cursor for use in pagination. paginationCursorNext is an object ID that defines your place in the list. For instance, if you make a list request and receive 30 objects, ending with obj_foo, your subsequent call can include paginationCursorNext=obj_foo in order to fetch the next page of the list.

filterTemplateIds string or array
Specific ID or IDs of templates.

filterMovieIds string or array
Specific ID or IDs of movies.

cacheHash string
A specific cache hash of the render.

Returns

A object with a data property that contains an array of up to 30 renders. Each entry in the array is a separate contact object. If no more renders are available, the resulting array will be empty.

{
    hasMore: true,
    paginationCursorNext: "307f1f70bcf86cd799439011",
    data: [
        // Render data objects...
    ]
}

Errors

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

Error code types: