Skip to content
ScreenshotDude

Core concepts

S3 / R2 upload

Upload screenshots directly to AWS S3, Cloudflare R2 or any S3-compatible storage.

Instead of receiving the image in the response, you can have /v1/capture upload it to your own bucket.

Parameters

Parameter Description
s3_access_key_id Access key ID with PutObject permission on the bucket.
s3_secret_key Secret access key.
s3_bucket Bucket name.
s3_region Region, e.g. eu-west-1. Use auto for Cloudflare R2.
s3_object_key Object key (path) to write, e.g. screens/home.png. Auto-generated when empty.
storage_endpoint S3-compatible endpoint, e.g. https://<account>.r2.cloudflarestorage.com. Leave empty for AWS S3.
s3_url true to return JSON with the file location instead of the binary image.

Credentials are used only for the upload and are never stored or shown in logs.

AWS S3

curl -G "http://localhost:4000/v1/capture" \
  --data-urlencode "url=https://example.com" \
  -d s3_bucket=my-bucket -d s3_region=eu-west-1 \
  -d s3_object_key=screens/example.png -d s3_url=true \
  --data-urlencode "s3_access_key_id=$AWS_ACCESS_KEY_ID" \
  --data-urlencode "s3_secret_key=$AWS_SECRET_ACCESS_KEY" \
  -H "x-api-key: $SNAPLENS_API_KEY"
curl -G "http://localhost:4000/v1/capture" \
  --data-urlencode "url=https://example.com" \
  -d s3_bucket=screenshots -d s3_region=auto \
  --data-urlencode "storage_endpoint=https://<account-id>.r2.cloudflarestorage.com" \
  --data-urlencode "s3_access_key_id=$R2_ACCESS_KEY_ID" \
  --data-urlencode "s3_secret_key=$R2_SECRET_ACCESS_KEY" \
  -d s3_url=true \
  -H "x-api-key: $SNAPLENS_API_KEY"

Other S3-compatible providers (MinIO, Backblaze B2, Wasabi, DigitalOcean Spaces) work the same way with their storage_endpoint.

Response

With s3_url=true:

{
  "success": true,
  "data": {
    "url": "https://my-bucket.s3.eu-west-1.amazonaws.com/screens/example.png",
    "key": "screens/example.png",
    "bucket": "my-bucket"
  }
}

Without s3_url, the file is uploaded and returned as the binary response.

Permissions

Create a dedicated access key restricted to s3:PutObject on the target bucket (or prefix). The returned url is the object's canonical location; whether it's publicly readable depends on your bucket policy.

Errors

If the upload fails (wrong credentials, missing bucket, denied permission), the request returns 400 with a message from the storage provider and is not billed.