Saving to S3 Compatible Storage

By default, Urlbox's rendering service will save your renders to our own cloud storage.

These renders will expire after 30 days.

When using render links to call the API, you can rely on the urlbox cache for 30 days to serve your renders, after 30 days the cache will expire and the render will be regenerated the next time the render link is requested.

If you would like a more permanent way to store your renders, configuring your project to save to S3, or an S3-compatible service is a great option.

Please see the guides below for more information on how to configure s3 and other services with your Urlbox project:

• Amazon S3
• Amazon S3 (private)
• Google Cloud Storage
• Cloudflare R2
• DigitalOcean Spaces
• Backblaze B2

(More provider guides coming soon - configure the S3 endpoint to the provider's endpoint to use with Urlbox)

Telling Urlbox to use your S3 bucket

Once you have configured a bucket and added the credentials to your project, you need to tell Urlbox to use it. You can do this by passing in the option use_s3 and set it to true.

This will tell Urlbox to save the render to the bucket configured on your project instead of Urlbox's storage.

When using render links, the render from your bucket will be served by Urlbox's cache for 30 days, after which the cache will expire and the render will be regenerated the next time the render link is requested.

When using the API, the renderUrl will be a direct link to the render in your bucket.

Here's an example using an S3 bucket called screenshots-demo and an s3_path of screenshots/urlbox/google. Note that the renderUrl is now pointing directly to the file inside the bucket.

curl -X POST \
	https://api.urlbox.io/v1/render/sync \
	-H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
	-H 'Content-Type: application/json' \
	-d '
{
	"url": "https://www.google.com",
	"s3_path": "screenshots/urlbox/google",
	"use_s3": true
}
'

{
  "renderId": "8a83126e-7eb8-442d-8943-86ac953d3017",
  "status": "succeeded",
  "renderUrl": "https://screenshots-demo.s3.amazonaws.com/screenshots/urlbox/google.png",
  "size": 35428
}

Configuring where Urlbox saves renders in your bucket

You can configure where Urlbox will save the renders in your bucket, by setting the s3_path option.

This will be the path to the file in your bucket, and should include subdirectories and the final name.

For example if you want to save the render as screenshot-1.png inside the screenshots/urlbox folder, you would set the s3_path option to screenshots/urlbox/screenshot-1.

Other storage options

You can override the bucket name to save to on each request, by setting the s3_bucket. You will of course need to ensure that the credentials configured also have the required permissions to save to this bucket.

You can tell urlbox not to add the file format suffix (e.g. .png) to the file in your bucket by setting the no_suffix option to true.

If necessary you can also set the region of your bucket by passing in s3_region option.

It's also possible to override the configured S3 endpoint per request by sending in the s3_endpoint option on a request.

Private bucket mode

When a private bucket is configured for your project, Urlbox will use the bucket for storing renders only. When using render links with a private bucket, Urlbox will no longer try to serve the renders directly, and just return a JSON response.