Ssnap DocsCapture parameters
Every capture parameter, with types, ranges, defaults and interactions.
All parameters work identically on GET (query string) and POST (JSON body).
Only url is required.
Target
| Parameter | Type | Default | Notes |
|---|---|---|---|
url | string (uri) | none | Required. Must be a publicly routable http/https address. See URL restrictions. |
Output
| Parameter | Type | Default | Notes |
|---|---|---|---|
format | jpeg | png | webp | pdf | jpeg | pdf skips image post-processing and ignores selector. |
quality | integer 1–100 | 80 | Applies to jpeg and webp. png is lossless and ignores it. |
response | binary | url | binary | url returns a signed link valid 24 hours. |
Viewport and device
| Parameter | Type | Default | Notes |
|---|---|---|---|
device_id | integer | server default preset | A device preset id. See Device emulation. |
width | integer 1–5000 | from preset | Applied only together with height. |
height | integer 1–5000 | from preset | Applied only together with width. |
theme | light | dark | light | Emulates prefers-color-scheme for the page. |
width and height are applied after the device preset, so an explicit viewport
overrides the preset's dimensions. Pass both; a lone width or height is ignored.
The device's user agent still applies.
Capture behaviour
| Parameter | Type | Default | Notes |
|---|---|---|---|
full_page | boolean | false | Captures the whole scroll height instead of the viewport. |
selector | string ≤255 | none | CSS selector to clip to. Takes precedence over full_page; ignored for pdf. |
network_idle | boolean | false | Waits for network activity to settle before capturing. |
delay | integer 0–30000 | 0 | Extra milliseconds to wait after load. |
selector and full_page are mutually exclusive: when both are given on an image
format, the selector wins and the page is clipped to that element.
Image styling
Applied after the render, to image formats only. See Backgrounds, borders and watermarks.
| Parameter | Type | Default | Notes |
|---|---|---|---|
background | hex colour | none | Six hex digits, # optional (#ffffff or ffffff). |
border_width | integer 1–200 | none | Border expands the image rather than cropping it. |
border_color | hex colour | 000000 | Only used when border_width is set. |
watermark_text | string ≤255 | none | Enables the watermark. |
watermark_size | integer 6–200 | 24 | Font size in points. |
watermark_color | hex colour | ffffff | |
watermark_x | integer 0–5000 | 20 | Offset from the left edge, in pixels. |
watermark_y | integer 0–5000 | 20 | Offset from the top edge, in pixels. |
Delivery
| Parameter | Type | Default | Notes |
|---|---|---|---|
cache_ttl | integer 0–2592000 | 0 | Seconds an identical earlier capture may be reused. A cache hit does not consume quota. |
callback_url | string (uri) | none | When set, the capture is queued and the result POSTed here; the request returns 202. Subject to the same public-host checks as url. |
Which parameters affect the cache key
The cache key is a hash of the target url, the device, and these output-affecting parameters:
theme, format, quality, device_id, width, height, full_page,
network_idle, delay, selector, background, border_width, border_color,
watermark_text, watermark_size, watermark_color, watermark_x, watermark_y.
cache_ttl, response and callback_url are delivery options and do not change the
key. See Screenshot caching.
Validation
Parameters are validated before any browser work happens. A violation returns 422
with Laravel's standard validation error body:
{
"message": "The url field is required.",
"errors": {
"url": ["The url field is required."]
}
}