Website screenshots

Pirehub captures a public webpage and returns a PNG data URI in the standard JSON success envelope. Choose a viewport capture or set fullPage: true to capture the full page.

Authentication

POST /api/v1/screenshot accepts a Pirehub API key with the screenshot:capture scope for server-to-server integrations. Send the key in x-pirehub-api-key or as a bearer token. Keep the key on your server. Pirehub’s website can use the alternative described in First-party browser verification. External integrations should use a scoped API key.

Capture options

Field	Required	Accepted values
`url`	Yes	Public HTTP(S) URL, at most 2048 characters
`width`	Yes	Integer viewport width from 300 to 1920 pixels
`height`	Yes	Integer viewport height from 168 to 4096 pixels
`fullPage`	Yes	`true` for the full page; `false` for the viewport
`device`	No	`desktop` (default) or `mobile`
`theme`	No	`light` (default) or `dark`
`delay`	No	Additional delay: `0` (default), `2000`, or `5000` milliseconds
`refreshCache`	No	`false` (default); `true` to request a fresh capture

URLs containing credentials, private network targets, and ports other than 80 or 443 are rejected. Sites that require login or block automated capture may not produce an image.

Capture request

curl --request POST \
  --url https://www.ntanduy.com/api/v1/screenshot \
  --header 'Content-Type: application/json' \
  --header "x-pirehub-api-key: $PIREHUB_API_KEY" \
  --data '{
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "fullPage": false,
    "device": "desktop",
    "theme": "light",
    "delay": 0,
    "refreshCache": false
  }'

Capture response

{
  "success": true,
  "data": {
    "dataUrl": "data:image/png;base64,...",
    "width": 1280,
    "height": 720,
    "cached": false
  }
}

The image data is abbreviated in this example. data.width and data.height describe the actual output image; full-page capture can produce a height different from the requested viewport. Decode the base64 portion of data.dataUrl to save a PNG, or use the complete data URI as an image source.

Caching

Matching captures are cached for 15 minutes, or 10 minutes for supported tweet URLs. data.cached: true indicates a cached result. Set refreshCache: true to request a fresh capture. Cache hits still count toward the API key’s limits.

Limits and failures

API-key requests use the per-minute and monthly limits configured for that key. Inspect X-ApiKey-RateLimit-* and X-ApiKey-Monthly-*. First-party browser requests without an API key are limited to 5 requests per minute per IP and return X-RateLimit-* headers.

HTTP status	Code	Meaning
`400`	`VALIDATION_ERROR`	Invalid capture options or a disallowed URL
`401`	`UNAUTHORIZED`	Invalid API key
`403`	`FORBIDDEN`	The key is revoked, expired, or lacks `screenshot:capture`
`422`	`VALIDATION_ERROR`	The page blocks capture or the content is too tall
`429`	`RATE_LIMITED`	A request rate limit was reached
`429`	`MONTHLY_QUOTA_EXCEEDED`	The key’s monthly quota is exhausted
`502`, `503`, `504`	See error response	Capture failed, is unavailable, or timed out

Honor Retry-After when present. After monthly quota exhaustion, wait until the reported reset time. See Errors and retries.

Next steps

Screenshot endpoint

Review the complete request and response schemas.

Authentication

Learn about scopes and credential handling.

Errors and retries

Handle failures safely and predictably.

Getting started

Network intelligence

Video tools

Payment utilities

Screenshot tools

Authentication

Capture options

Capture request

Capture response

Caching

Limits and failures

Next steps

Screenshot endpoint

Authentication

Errors and retries

​Authentication

​Capture options

​Capture request

​Capture response

​Caching

​Limits and failures

​Next steps

Screenshot endpoint

Authentication

Errors and retries

Authentication

Capture options

Capture request

Capture response

Caching

Limits and failures

Next steps