Storage Options

Upload screenshots directly to your configured cloud storage provider (S3, R2, GCS, etc.).

Prerequisites

Configure your storage credentials in the RenderScreenshot Dashboard before using storage options.

Full Configuration

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

Parameters

Enable Storage Upload

{
  "url": "https://example.com",
  "storage": {
    "enabled": true
  }
}

When enabled, the screenshot is uploaded to your configured storage bucket in addition to the standard response.

Path Templates

Customize the storage path using template variables:

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

Available Variables

Path Examples

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

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

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

Access Control

Private (Default)

Files are private and require authentication to access:

{
  "storage": {
    "enabled": true,
    "acl": "private"
  }
}

Public Read

Files are publicly accessible via direct URL:

{
  "storage": {
    "enabled": true,
    "acl": "public-read"
  }
}

Response with Storage

When storage is enabled, the response includes storage information:

Binary Response Headers

X-Storage-URL: https://your-bucket.s3.amazonaws.com/screenshots/2024/01/18/a1b2c3.png
X-Storage-Path: screenshots/2024/01/18/a1b2c3.png

JSON Response

{
  "id": "req_abc123",
  "status": "completed",
  "image": {
    "url": "https://cdn.renderscreenshot.com/xyz789.png",
    "width": 1200,
    "height": 630
  },
  "storage": {
    "url": "https://your-bucket.s3.amazonaws.com/screenshots/2024/01/18/a1b2c3.png",
    "path": "screenshots/2024/01/18/a1b2c3.png",
    "bucket": "your-bucket",
    "provider": "s3"
  }
}

Supported Storage Providers

Configure these in your dashboard:

Common Patterns

Archive All Screenshots

{
  "url": "https://example.com",
  "storage": {
    "enabled": true,
    "path": "archive/{year}/{month}/{domain}/{hash}.{ext}",
    "acl": "private"
  }
}

Public Social Cards

{
  "url": "https://myblog.com/post/123",
  "preset": "og_card",
  "storage": {
    "enabled": true,
    "path": "og-images/{domain}/{hash}.{ext}",
    "acl": "public-read"
  }
}

Batch with Storage

{
  "urls": [
    "https://example1.com",
    "https://example2.com"
  ],
  "options": {
    "preset": "og_card",
    "storage": {
      "enabled": true,
      "path": "batch/{date}/{hash}.{ext}"
    }
  }
}

Examples

Upload to S3

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": true,
      "path": "screenshots/{year}/{month}/{hash}.{ext}",
      "acl": "public-read"
    }
  }'

Response:

{
  "id": "req_abc123",
  "status": "completed",
  "storage": {
    "url": "https://my-bucket.s3.amazonaws.com/screenshots/2024/01/a1b2c3.png",
    "path": "screenshots/2024/01/a1b2c3.png"
  }
}

Storage vs Cache URL

Use cache URL for temporary/dynamic content. Use storage for permanent archives or when you need full control.

See Also

• Caching - Cache URL behavior
• Response Headers - All response headers
• Batch Screenshots - Batch with storage