Skip to content

Website Screenshots

The Screenshot endpoint allows you to generate and retrieve cached screenshots of publicly accessible webpages. This is useful for previews, thumbnails, link cards, archived captures, and automated webpage imaging.

Endpoint: HEAD GET https://api.teamtbm.org/v1/screenshot

Authentication: API Key (Authorization: ApiKey <api_key>)

Required Scopes

Scope Required When
screenshots:read Required to receive any screenshot response
screenshots:create Required to generate a new standard screenshot when no cached image is available
screenshots:create-thumb Required to generate a new thumbnail screenshot when no cached image is available
screenshots:* Grants access to all screenshot scopes

Note

Creating a standard screenshot requires both screenshots:read and screenshots:create.

Note

Creating a thumbnail screenshot requires both screenshots:read and screenshots:create-thumb.

Rate Limits

Limit Value
Requests 120 per minute
Scope Per API key

Exceeding the rate limit will return a 429 Too Many Requests response.

Query Parameters

Parameter Type Required Description
url string ✅ Yes A valid public http or https URL to capture. Also accepted as u.
preset string No Output preset. Use thumb for thumbnail mode. Also accepted as mode.
width integer No Viewport width in pixels. Also accepted as w.
height integer No Viewport height in pixels. Also accepted as h.
fullpage boolean No Capture the full page height in standard mode. Also accepted as fullPage and full.
ttl integer No Cache freshness period in seconds.
maxAge integer No HTTP cache max-age in seconds.
swr integer No Stale-while-revalidate period in seconds.
timeout integer No Request timeout in milliseconds. Also accepted as timeoutMs.
waitUntil string No Navigation completion mode: load, domcontentloaded, networkidle, or commit.
locale string No Locale used for the browser session. Defaults to en-GB.
dark boolean No Use dark colour scheme when set to true. Also accepted as darkMode.
scale string No Screenshot scale mode. Use css for CSS pixel scaling.
blockAds boolean No Blocks known ad and tracking requests during capture.
cache string No Set to bypass to skip cached results and request a fresh render.
refresh string No Set to 1 to skip cached results and request a fresh render.

Note

Both u and url are accepted as the query parameter name. If both are provided, url takes precedence.

Note

Both mode and preset are accepted as the query parameter name. If both are provided, preset takes precedence.

Note

When preset=thumb is used, thumbnail defaults apply, including a smaller default size and thumbnail-specific cache settings.

Response Format

The API returns a PNG image response body.

Response Headers:

Header Description
Content-Type Always image/png
Content-Length Size of the image response in bytes
ETag Cache validator for conditional requests
Last-Modified Timestamp of the current screenshot
Cache-Control Response caching policy
Expires Expiry timestamp for the current response
X-Cache Cache result such as HIT, MISS, STALE, COLLAPSED, HIT-AFTER-LOCK, or ERROR-STALE
X-Cache-Key Cache identifier for the current screenshot
X-Rendered-At Screenshot render timestamp in ISO format
X-Render-Ms Render time in milliseconds when available
Accept-Ranges Always none

Returned when the url (or u) parameter is missing, invalid, or points to a disallowed target.

{
    "success": false,
    "code": 400,
    "message": "Bad Request",
    "error": "A valid public URL is required."
}

Returned when the Authorization header is missing or is not using the required ApiKey format.

{
    "success": false,
    "code": 401,
    "message": "Unauthorized",
    "error": "Missing or invalid Authorization header"
}

Returned when the API key is invalid or does not have the required scopes for the requested action.

{
    "success": false,
    "code": 403,
    "message": "Forbidden",
    "error": "Missing screenshots:read scope"
}

{
    "success": false,
    "code": 500,
    "message": "Internal Server Error",
    "error": "Failed to render screenshot: Unknown error"
}

Returned when the screenshot is currently being generated and no completed result is available yet.

{
    "success": false,
    "code": 503,
    "message": "Service Unavailable",
    "error": "Screenshot is currently being generated, please retry shortly"
}

Additional Error Fields

Some error responses may include extra fields beyond the standard message and error properties, depending on the specific nature of the failure.

HTTP Status Codes

Code Meaning
200 Success — screenshot returned
400 Bad Request — missing or invalid url parameter
401 Unauthorized — missing or invalid Authorization header
403 Forbidden — invalid API key or missing required scope
500 Internal Server Error
503 Service Unavailable — screenshot is still being generated

Example Requests

curl -X GET "https://api.teamtbm.org/v1/screenshot?url=https%3A%2F%2Fexample.com" \
     -H "Authorization: ApiKey <api_key>" \
     -H "Accept: image/png"

const response = await fetch("https://api.teamtbm.org/v1/screenshot?url=https%3A%2F%2Fexample.com", {
    headers: {
        "Authorization": "ApiKey <api_key>",
        "Accept": "image/png"
    }
});

const imageBuffer = await response.arrayBuffer();

import requests

response = requests.get(
    "https://api.teamtbm.org/v1/screenshot",
    params={"url": "https://example.com"},
    headers={
        "Authorization": "ApiKey <api_key>",
        "Accept": "image/png"
    }
)

image_bytes = response.content

<?php
$ch = curl_init("https://api.teamtbm.org/v1/screenshot?url=https%3A%2F%2Fexample.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: ApiKey <api_key>",
    "Accept: image/png"
]);

$response = curl_exec($ch);
curl_close($ch);
?>