Sync vs Async

The Urlbox API can be called in both synchronous and asynchronous modes.

Depending on your use case and desired workflow, you may want to choose one method of calling the API over another.

With render links the request will always be synchronous.

Synchronous requests

Synchronous means that when calling the API the request will wait for the render to finish generating before returning a response.

The render will be returned in this response either as binary data or as a URL to the rendered image depending on how you're calling the API.

When to use synchronous requests

Synchronous requests are useful when you want to get the results back immediately.

When you want to call the Urlbox API directly from an <img> tag, you can use a render link which will always be synchronous and return the binary data by default.

It is usually easier to use synchronous requests when integrating with no-code solutions such as Zapier.

If your server environment can deal with potentially having many long running connections open at the same time, then synchronous requests might be a good choice.

Asynchronous requests

Asynchronous means that the request will return immediately with a renderId and statusUrl (if the request passes validation).

The renderId can be stored and used to retrieve the render at a later time, either by polling the statusUrl or by passing in a webhook_url to be notified when the render is complete.

When to use asynchronous requests

Asynchronous requests are useful when you want to render a large number of URLs or when the render time is long (such as when rendering a very tall page with full_page set to true).

You can fire off the requests, and either poll the status URL's, or wait for your webhook endpoint to be called.