Storage Options

Upload screenshots to your own S3-compatible storage bucket. Screenshots are always stored in RenderScreenshot's CDN first, then copied to your bucket asynchronously via a background job. This page is the parameter reference, part of the API documentation. For a step-by-step setup with a worked example, read upload screenshots to S3.

Step by step: Save screenshots to your own bucket walks through this task with screenshots of every step.

Supported Providers

Works with any S3-compatible storage:

• Amazon S3
• Cloudflare R2
• DigitalOcean Spaces
• Backblaze B2
• MinIO
• Wasabi
• Any other S3-compatible storage

Prerequisites

1. Configure your storage credentials in the Storage Dashboard
2. Test the connection to verify credentials work
3. Ensure your bucket is accessible with the provided credentials

Full Configuration

{
  "url": "https://example.com",
  "storage": {
    "enabled": true,
    "path": "screenshots/{year}/{month}/{day}/{hash}.{ext}",
    "acl": "public-read"
  }
}

Parameters

When the API key's workspace has storage configured and enabled, screenshots are automatically uploaded. Each workspace has its own storage configuration, so two projects can upload to two buckets. Use storage.enabled: false to skip storage for a specific request.

Path Templates

Customize where screenshots are stored using template variables. Set a default template in the storage dashboard, or send storage.path to override it for one request:

{
  "storage": {
    "path": "screenshots/{year}/{month}/{day}/{hash}.{ext}"
  }
}

Available Variables

Path Examples

Organized by date: screenshots/{year}/{month}/{day}/{hash}.{ext} → screenshots/2026/01/27/a1b2c3d4.png

Organized by domain: captures/{domain}/{hash}.{ext} → captures/example.com/a1b2c3d4.png

With UUID for uniqueness: shots/{uuid}-{hash}.{ext} → shots/550e8400-e29b-41d4-a716-446655440000-a1b2c3d4.png

Simple flat structure: {hash}.{ext} → a1b2c3d4.png

Access Control

Private (Default)

Files are private and require authentication to access:

{
  "storage": {
    "acl": "private"
  }
}

Public Read

Files are publicly accessible via direct URL:

{
  "storage": {
    "acl": "public-read"
  }
}

Async Upload Behavior

Storage uploads happen asynchronously after the screenshot response is returned:

1. You receive the screenshot immediately
2. A background job copies the screenshot to your bucket
3. The upload result is stored in the screenshot request record

This means you get fast response times without waiting for the upload to complete.

If the upload fails with a temporary error (throttling such as SlowDown, a 5xx from the provider, or a network error), the job tries again with backoff, up to 5 attempts. A permanent error, such as AccessDenied or NoSuchBucket, is not retried: the job records the error and stops, so fix the bucket or the keys and render again.

Dashboard Configuration

Configure your storage settings at /dashboard/storage:

Endpoint URLs by Provider

Provider Setup Guides

Cloudflare R2

Cloudflare R2 is S3-compatible object storage with zero egress fees.

Step 1: Create an R2 bucket

1. Log in to your Cloudflare Dashboard
2. Navigate to R2 Object Storage in the sidebar
3. Click Create bucket
4. Enter a bucket name (e.g., my-screenshots)
5. Click Create bucket

Step 2: Create API credentials

1. In the R2 section, click Manage R2 API Tokens
2. Click Create API token
3. Give it a name (e.g., RenderScreenshot)
4. Under Permissions, select Object Read & Write
5. Under Specify bucket(s), select your bucket or choose Apply to all buckets
6. Click Create API Token
7. Copy the Access Key ID and Secret Access Key (you won't see the secret again)

Step 3: Find your Account ID

Your Account ID is in the R2 overview page URL or in the sidebar. It's a 32-character hexadecimal string.

Step 4: Configure in RenderScreenshot

Optional: Set up a public bucket with custom domain

If you want screenshots to be publicly accessible:

1. In your bucket settings, go to Settings → Public access
2. Click Allow Access to enable public access
3. Optionally, connect a custom domain under Custom Domains
4. Add the public URL base to your RenderScreenshot storage settings

Amazon S3

Step 1: Create an S3 bucket

1. Log in to the AWS Console
2. Click Create bucket
3. Enter a bucket name and select a region
4. Configure public access settings based on your needs
5. Click Create bucket

Step 2: Create IAM credentials

1. Go to IAM → Users → Create user
2. Create a user with programmatic access
3. Attach the following inline policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:PutObjectAcl"],
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::your-bucket-name"
    }
  ]
}

The connection test calls HeadBucket, which needs s3:ListBucket on the bucket itself (note: no /*). Without the second statement, uploads would be allowed but the test fails with Forbidden, and storage stays off.

1. Save the Access Key ID and Secret Access Key

Step 3: Configure in RenderScreenshot

DigitalOcean Spaces

Step 1: Create a Space

1. Log in to DigitalOcean
2. Go to Spaces Object Storage
3. Click Create a Space
4. Select a datacenter region and name your Space

Step 2: Create API credentials

1. Go to API → Spaces Keys
2. Click Generate New Key
3. Copy the Key and Secret

Step 3: Configure in RenderScreenshot

Backblaze B2

Step 1: Create a B2 bucket

1. Log in to Backblaze
2. Click Create a Bucket
3. Enter a bucket name and set file visibility

Step 2: Create application key

1. Go to App Keys → Add a New Application Key
2. Give it a name and select your bucket
3. Copy the keyID and applicationKey

Step 3: Configure in RenderScreenshot

Wasabi

Step 1: Create a bucket

1. Log in to Wasabi Console
2. Click Create Bucket
3. Enter a name and select a region

Step 2: Create access keys

1. Go to Access Keys → Create New Access Key
2. Copy the Access Key and Secret Key

Step 3: Configure in RenderScreenshot

MinIO (Self-Hosted)

For self-hosted MinIO instances:

Examples

Basic Storage Upload

curl

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "preset": "og_card"
  }'

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.TakeOptions;

Client client = new Client("rs_live_xxxxx");

// When storage is configured for your account, uploads happen automatically
byte[] image = client.take(
    TakeOptions.url("https://example.com").preset("og_card")
);

Node.js

import { Client, TakeOptions } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

// When storage is configured for your account, uploads happen automatically
const image = await client.take(
  TakeOptions.url('https://example.com').preset('og_card')
);

PHP

use RenderScreenshot\Client;
use RenderScreenshot\TakeOptions;

$client = new Client('rs_live_xxxxx');

// When storage is configured for your account, uploads happen automatically
$image = $client->take(
    TakeOptions::url('https://example.com')->preset('og_card')
);

Python

from renderscreenshot import Client, TakeOptions

client = Client('rs_live_xxxxx')

# When storage is configured for your account, uploads happen automatically
image = client.take(
    TakeOptions.url('https://example.com').preset('og_card')
)

Ruby

require 'renderscreenshot'

client = RenderScreenshot.client('rs_live_xxxxx')

# When storage is configured for your account, uploads happen automatically
image = client.take(
  RenderScreenshot::TakeOptions
    .url('https://example.com')
    .preset('og_card')
)

Go

client, _ := rs.New("rs_live_xxxxx")

// When storage is configured for your account, uploads happen automatically
image, _ := client.Take(context.Background(),
    rs.URL("https://example.com").Preset("og_card"),
)

When storage is configured for your account, uploads happen automatically.

Custom Path Template

A per-request storage.path (the SDK storagePath / storage_path methods) overrides the path template saved in your storage dashboard for that request, and acl overrides the default ACL. The path follows the same rules as the dashboard template: only the variables above, and both {hash} and {ext}. Any other path returns HTTP 400 invalid_parameter with param: "storage.path", before the render starts.

curl

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "storage": {
      "path": "og-images/{domain}/{hash}.{ext}",
      "acl": "public-read"
    }
  }'

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.TakeOptions;

Client client = new Client("rs_live_xxxxx");

byte[] image = client.take(
    TakeOptions.url("https://example.com")
        .storageEnabled()
        .storagePath("og-images/{domain}/{hash}.{ext}")
        .storageAcl("public-read")
);

Node.js

import { Client, TakeOptions } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

const image = await client.take(
  TakeOptions.url('https://example.com')
    .storageEnabled()
    .storagePath('og-images/{domain}/{hash}.{ext}')
    .storageAcl('public-read')
);

PHP

use RenderScreenshot\Client;
use RenderScreenshot\TakeOptions;

$client = new Client('rs_live_xxxxx');

$image = $client->take(
    TakeOptions::url('https://example.com')
        ->storageEnabled()
        ->storagePath('og-images/{domain}/{hash}.{ext}')
        ->storageAcl('public-read')
);

Python

from renderscreenshot import Client, TakeOptions

client = Client('rs_live_xxxxx')

image = client.take(
    TakeOptions.url('https://example.com')
    .storage_enabled()
    .storage_path('og-images/{domain}/{hash}.{ext}')
    .storage_acl('public-read')
)

Ruby

require 'renderscreenshot'

client = RenderScreenshot.client('rs_live_xxxxx')

image = client.take(
  RenderScreenshot::TakeOptions
    .url('https://example.com')
    .storage_enabled
    .storage_path('og-images/{domain}/{hash}.{ext}')
    .storage_acl('public-read')
)

Go

client, _ := rs.New("rs_live_xxxxx")

image, _ := client.Take(context.Background(),
    rs.URL("https://example.com").
        StorageEnabled().
        StoragePath("og-images/{domain}/{hash}.{ext}").
        StorageACL(rs.ACLPublicRead),
)

Skip Storage for One Request

curl

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "storage": {
      "enabled": false
    }
  }'

Node.js

import { Client, TakeOptions } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

// Explicitly disable storage for this request
const image = await client.take(
  TakeOptions.url('https://example.com').storageEnabled(false)
);

PHP

use RenderScreenshot\Client;
use RenderScreenshot\TakeOptions;

$client = new Client('rs_live_xxxxx');

// Explicitly disable storage for this request
$image = $client->take(
    TakeOptions::url('https://example.com')->storageEnabled(false)
);

Python

from renderscreenshot import Client, TakeOptions

client = Client('rs_live_xxxxx')

# Explicitly disable storage for this request
image = client.take(
    TakeOptions.url('https://example.com').storage_enabled(False)
)

Ruby

require 'renderscreenshot'

client = RenderScreenshot.client('rs_live_xxxxx')

# Explicitly disable storage for this request
image = client.take(
  RenderScreenshot::TakeOptions
    .url('https://example.com')
    .storage_enabled(false)
)

Go

client, _ := rs.New("rs_live_xxxxx")

// Explicitly disable storage for this request
image, _ := client.Take(context.Background(),
    rs.URL("https://example.com").StorageEnabled(false),
)

Storage vs Cache URL

Use cache URL for temporary/dynamic content where you don't need permanent storage. Use custom storage when you need permanent archives or want screenshots in your own infrastructure.

Troubleshooting

How storage failures show up

Storage problems never appear in the API response, because the response is sent before the upload starts. They show up in two places:

• The connection test on the storage dashboard. It runs when you save the settings and when you click Test. While the test fails, storage is off for the account and no uploads are attempted.
• Your bucket. If the test passed but a file is missing, the upload itself failed. Use the script below to check.

Uploads also run only for fresh renders on a paid plan, and not for requests with storage.enabled: false.

Symptom to fix

The messages in this table are the exact text the dashboard shows. We produced them by sending the dashboard's own S3 calls, with the same AWS SDK for Ruby version, to a local S3 stub that returned each status.

Storage settings are on paid plans only. If your plan changes to Free, uploads stop, and a request that still sends a storage block (other than "enabled": false) fails with HTTP 403 feature_not_available.

Check that uploads arrive

This script takes one screenshot, works out the object key, and polls your bucket with HeadObject until the copy appears. Run it after you change any storage setting. It reads its own bucket credentials from the standard AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables, so give it a key that can read the bucket.

// verify-upload.mjs (Node 22+, npm i @aws-sdk/client-s3)
// Takes one screenshot, then checks that its copy arrived in your bucket.
import { S3Client, HeadObjectCommand } from '@aws-sdk/client-s3';

const API = process.env.RS_BASE_URL ?? 'https://api.renderscreenshot.com';
const BUCKET = process.env.S3_BUCKET;
const PREFIX = process.env.STORAGE_PREFIX ?? ''; // the part of your path template before {hash}
const s3 = new S3Client({
  region: process.env.S3_REGION ?? 'auto',
  endpoint: process.env.S3_ENDPOINT, // leave unset for Amazon S3
  forcePathStyle: Boolean(process.env.S3_ENDPOINT),
});
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const res = await fetch(`${API}/v1/screenshot`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.RS_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' }),
});
if (!res.ok) throw new Error(`Render failed with HTTP ${res.status}: ${await res.text()}`);
if (res.headers.get('x-cache-hit') === 'true') throw new Error('Cache hit: cache hits are not uploaded again');

// {hash}.{ext} is the file name at the end of X-Cache-Key.
const key = PREFIX + res.headers.get('x-cache-key').split('/').pop();

for (let attempt = 1; attempt <= 10; attempt++) {
  try {
    const head = await s3.send(new HeadObjectCommand({ Bucket: BUCKET, Key: key }));
    console.log(`Uploaded: s3://${BUCKET}/${key} (${head.ContentLength} bytes, attempt ${attempt})`);
    process.exit(0);
  } catch (err) {
    // 404 means "not there yet". Anything else (403, wrong endpoint) is a real problem.
    if (err.$metadata?.httpStatusCode !== 404) throw err;
  }
  await sleep(3000);
}
console.error(`Not in the bucket after 30 seconds: ${key}`);
process.exitCode = 1;

The key logic works for templates of the form prefix/{hash}.{ext}, such as the default {hash}.{ext}. Templates with date, {domain}, {timestamp} or {uuid} parts need the same values the upload used, so list the bucket for those instead.

Tested on 2026-10-15 with Node 22.18 and @aws-sdk/client-s3 3.1152.0 against a local API stub that sends X-Cache-Key and an S3 stub. The script found an object that appeared on the third check, exited 1 for an object that never appeared, and stopped at once on a 403. The dashboard messages in the table came from the same run of aws-sdk-s3 1.233.1, the version the API uses.

See Also

• Caching - Cache URL behavior and how it differs from custom storage
• POST /v1/screenshot - Screenshot endpoint with storage parameters
• Batch Screenshots - Batch processing with storage support
• Output Options - Image format and quality settings
• Response Headers - All response headers