Cache Management

RenderScreenshot caches screenshots for fast retrieval. These endpoints let you manage cached content programmatically. Each workspace has its own cache: every endpoint here sees and changes only the renders of the API key's workspace.

Get Cached Screenshot

Retrieve a screenshot by its cache key.

GET https://api.renderscreenshot.com/v1/cache/:key

:key is the exact X-Cache-Key value of a render, for example screenshots/a/<account token>/w/<workspace token>/k/og-home.png. Send it as it is, with its slashes and extension, or URL-encoded (screenshots%2Fa%2F...). The short form without screenshots/ and your own cache.key also work. A key that the API key's workspace does not own returns 404, also when another workspace of your account owns it.

curl

curl https://api.renderscreenshot.com/v1/cache/cache_xyz789 \
  -H "Authorization: Bearer rs_live_xxxxx" \
  --output screenshot.png

Java

import com.renderscreenshot.sdk.Client;
import java.nio.file.Files;
import java.nio.file.Path;

Client client = new Client("rs_live_xxxxx");

byte[] image = client.cache.get("cache_xyz789");
if (image != null) {
    Files.write(Path.of("screenshot.png"), image);
}

Node.js

import { Client } from 'renderscreenshot';
import { writeFile } from 'fs/promises';

const client = new Client('rs_live_xxxxx');

const image = await client.cache.get('cache_xyz789');
if (image) {
  await writeFile('screenshot.png', image);
}

PHP

use RenderScreenshot\Client;

$client = new Client('rs_live_xxxxx');

$image = $client->cache->get('cache_xyz789');
if ($image) {
    file_put_contents('screenshot.png', $image);
}

Python

from renderscreenshot import Client

client = Client('rs_live_xxxxx')

image = client.cache.get('cache_xyz789')
if image:
    with open('screenshot.png', 'wb') as f:
        f.write(image)

Ruby

require 'net/http'

uri = URI('https://api.renderscreenshot.com/v1/cache/cache_xyz789')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'

response = http.request(request)
File.binwrite('screenshot.png', response.body) if response.code == '200'

Response

Returns the cached screenshot binary, or 404 if not found.

HTTP/1.1 200 OK
Content-Type: image/png
X-Cache-Key: screenshots/abc123
X-Cache-Hit: true
X-Cache-Expires: 2024-01-19T00:00:00Z

Delete Cache Entry

Invalidate a single cached screenshot. :key takes the same forms as on GET. After a delete, cache.available does not reuse that render: the next identical request renders fresh and uses one credit.

DELETE https://api.renderscreenshot.com/v1/cache/:key

curl

curl -X DELETE https://api.renderscreenshot.com/v1/cache/cache_xyz789 \
  -H "Authorization: Bearer rs_live_xxxxx"

Java

import com.renderscreenshot.sdk.Client;

Client client = new Client("rs_live_xxxxx");

boolean deleted = client.cache.delete("cache_xyz789");
System.out.println(deleted ? "Deleted" : "Not found");

Node.js

import { Client } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

const deleted = await client.cache.delete('cache_xyz789');
console.log(deleted ? 'Deleted' : 'Not found');

PHP

use RenderScreenshot\Client;

$client = new Client('rs_live_xxxxx');

$deleted = $client->cache->delete('cache_xyz789');
echo $deleted ? 'Deleted' : 'Not found';

Python

from renderscreenshot import Client

client = Client('rs_live_xxxxx')

deleted = client.cache.delete('cache_xyz789')
print('Deleted' if deleted else 'Not found')

Ruby

require 'net/http'

uri = URI('https://api.renderscreenshot.com/v1/cache/cache_xyz789')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'

response = http.request(request)
puts response.code == '200' ? 'Deleted' : 'Not found'

Response

{
  "deleted": true,
  "key": "cache_xyz789"
}

Bulk Purge

Invalidate multiple cache entries at once.

POST https://api.renderscreenshot.com/v1/cache/purge

Request Body

{
  "keys": ["cache_abc", "cache_def"],
  "pattern": "screenshots/2024/01/*",
  "url": "https://example.com/*",
  "before": "2024-01-15T00:00:00Z"
}

You can combine multiple filters. All matching entries of the API key's workspace will be purged; other workspaces are not affected. A parameter of the wrong type (for example "url": ["..."]) returns 400 invalid_parameter with the parameter name in error.param. A purged render is not reused by cache.available: the next identical request renders fresh and uses one credit.

Example: Purge by Keys

curl

curl -X POST https://api.renderscreenshot.com/v1/cache/purge \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["cache_abc123", "cache_def456"]
  }'

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.CacheManager;
import java.util.Arrays;

Client client = new Client("rs_live_xxxxx");

CacheManager.PurgeResponse result = client.cache.purge(
    Arrays.asList("cache_abc123", "cache_def456")
);
System.out.println("Purged " + result.getPurged() + " entries");

Node.js

import { Client } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

const result = await client.cache.purge(['cache_abc123', 'cache_def456']);
console.log(`Purged ${result.purged} entries`);

PHP

use RenderScreenshot\Client;

$client = new Client('rs_live_xxxxx');

$result = $client->cache->purge(['cache_abc123', 'cache_def456']);
echo "Purged {$result['purged']} entries";

Python

from renderscreenshot import Client

client = Client('rs_live_xxxxx')

result = client.cache.purge(['cache_abc123', 'cache_def456'])
print(f"Purged {result['purged']} entries")

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.renderscreenshot.com/v1/cache/purge')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'
request['Content-Type'] = 'application/json'
request.body = { keys: ['cache_abc123', 'cache_def456'] }.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts "Purged #{result['purged']} entries"

Example: Purge by URL Pattern

curl

curl -X POST https://api.renderscreenshot.com/v1/cache/purge \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mysite.com/blog/*"
  }'

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.CacheManager;

Client client = new Client("rs_live_xxxxx");

CacheManager.PurgeResponse result = client.cache.purgeUrl("https://mysite.com/blog/*");
System.out.println("Purged " + result.getPurged() + " entries");

Node.js

import { Client } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

const result = await client.cache.purgeUrl('https://mysite.com/blog/*');
console.log(`Purged ${result.purged} entries`);

PHP

use RenderScreenshot\Client;

$client = new Client('rs_live_xxxxx');

$result = $client->cache->purgeUrl('https://mysite.com/blog/*');
echo "Purged {$result['purged']} entries";

Python

from renderscreenshot import Client

client = Client('rs_live_xxxxx')

result = client.cache.purge_url('https://mysite.com/blog/*')
print(f"Purged {result['purged']} entries")

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.renderscreenshot.com/v1/cache/purge')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'
request['Content-Type'] = 'application/json'
request.body = { url: 'https://mysite.com/blog/*' }.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts "Purged #{result['purged']} entries"

Example: Purge by Date

curl

curl -X POST https://api.renderscreenshot.com/v1/cache/purge \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "before": "2024-01-01T00:00:00Z"
  }'

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.CacheManager;
import java.time.Instant;

Client client = new Client("rs_live_xxxxx");

CacheManager.PurgeResponse result = client.cache.purgeBefore(
    Instant.parse("2024-01-01T00:00:00Z")
);
System.out.println("Purged " + result.getPurged() + " entries");

Node.js

import { Client } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

const result = await client.cache.purgeBefore(new Date('2024-01-01'));
console.log(`Purged ${result.purged} entries`);

PHP

use RenderScreenshot\Client;

$client = new Client('rs_live_xxxxx');

$result = $client->cache->purgeBefore(new DateTime('2024-01-01'));
echo "Purged {$result['purged']} entries";

Python

from datetime import datetime
from renderscreenshot import Client

client = Client('rs_live_xxxxx')

result = client.cache.purge_before(datetime(2024, 1, 1))
print(f"Purged {result['purged']} entries")

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.renderscreenshot.com/v1/cache/purge')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'
request['Content-Type'] = 'application/json'
request.body = { before: '2024-01-01T00:00:00Z' }.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts "Purged #{result['purged']} entries"

Response

{
  "purged": 42,
  "pattern": "https://mysite.com/blog/*"
}

Cache Keys

Cache keys are returned in the X-Cache-Key response header when capturing screenshots:

X-Cache-Key: cache_xyz789
X-Cache-URL: https://cdn.renderscreenshot.com/xyz789.png

You can also set custom cache keys when creating screenshots:

{
  "url": "https://example.com",
  "cache": {
    "key": "my-custom-key"
  }
}

Use Cases

Force Refresh

To update a cached screenshot, set cache.refresh to true:

{
  "url": "https://example.com",
  "cache": {
    "refresh": true
  }
}

Clear on Deploy

Purge all cached screenshots for your domain after deploying updates:

curl -X POST https://api.renderscreenshot.com/v1/cache/purge \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/*"}'

Scheduled Cleanup

Purge old cache entries to ensure fresh content:

curl -X POST https://api.renderscreenshot.com/v1/cache/purge \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"before": "2024-01-01T00:00:00Z"}'