Instant Snap API

Defaults and limits

A capture request can leave almost every field out. This endpoint says exactly what it gets when it does — and what bounds a value you do send has to fall within.

The endpoint

GEThttps://api.websitescreenshotworld.com/instant-snap/v1/defaults

No key needed

curl https://api.websitescreenshotworld.com/instant-snap/v1/defaults

This is the one Instant Snap API endpoint that takes no X-Api-Key header. It contains nothing about your account, so it is public and cacheable — the response carries Cache-Control: public, max-age=86400.

Why it exists

The values below are projected from the same server-side resolver that fills your requests in — not written out a second time. That is the point of the endpoint: the default in the documentation, the default in the schema and the default in the behaviour have exactly one definition and cannot drift apart.

Read it, do not hard-code it

If your integration cares about a default, fetch it once at startup rather than copying the number into your code. A default that changes bumps spec_version, which your code can notice; a number copied into a constant three years ago cannot.

The response

200 OK

{
  "spec_version": "v1",
  "response_type": "json",
  "media_category": "image",
  "format": {
    "image": "png",
    "video": "mp4",
    "pdf": "image_pdf",
    "content": "markdown"
  },
  "device_category": "desktop",
  "viewport": {
    "width": 1920,
    "height": 1080,
    "device_scale_factor": 1
  },
  "zoom": 100,
  "scroll_mode": "viewport",
  "auto_height": false,
  "auto_height_max_height": 100000,
  "auto_height_max_height_webp": 16383,
  "block_ads": true,
  "block_pop_ups": true,
  "press_escape": false,
  "page_timeout_ms": 30000,
  "scrolling_delay_ms": 500,
  "geolocation": false,
  "wait_for_cloud_sync": false,
  "timestamp_watermark": {
    "enabled": false,
    "location": "top",
    "font_color": "#000000",
    "background_color": "#FFFFFF"
  },
  "page_source": {
    "enabled": false,
    "format": "html",
    "formats": ["html", "json", "text"]
  },
  "formats": {
    "image": ["png", "jpeg", "webp", "tiff"],
    "video": ["mp4", "webm", "mov", "gif"],
    "pdf": ["image_pdf", "document_pdf"],
    "content": ["markdown", "text"]
  },
  "limits": {
    "page_timeout_ms_min": 1000,
    "page_timeout_ms_max": 60000,
    "scrolling_delay_ms_max": 10000,
    "content_max_bytes": 2097152
  },
  "left_to_the_browser": [
    "user_agent",
    "locale",
    "time_zone",
    "headers",
    "cookies",
    "geolocation"
  ]
}

What each key means

Field	Type	Default	Description
`format`	object	—	An omitted format resolves from the media category rather than to one fixed value, so this is a map rather than a single token. content is the page's readable text rather than a picture of it, charged like an image.
`scroll_mode`	string	—	viewport for an image or a PDF. A video resolves to scroll instead, because it needs movement to be worth recording.
`auto_height_max_height`	integer (px)	—	The ceiling applied when auto_height is on. Auto height without a bound would let a pathological page grow without limit.
`geolocation`	boolean	—	False — meaning the browser’s own behaviour is left untouched, not that a position of 0,0 is reported.
`wait_for_cloud_sync`	boolean	—	The default of s3_delivery.wait_for_sync. A synchronous call does not block on a customer bucket unless it asks to.
`timestamp_watermark`	object	—	enabled is false, because a capture carries no strip unless the request sends the block. The other three say what a block naming nothing resolves to.

limits

These are the bounds a value you send is refused outside of. They are published so you can validate before you call, rather than learning them from a refusal.

Field	Type	Default	Description
`page_timeout_ms_min`	integer	—	The smallest page timeout that will be accepted.
`page_timeout_ms_max`	integer	—	The largest. A page still unsettled at this point answers capture_timeout.
`scrolling_delay_ms_max`	integer	—	The longest pause allowed between scroll steps.
`content_max_bytes`	integer	—	The most text a page-content capture (markdown or text) returns, in bytes of UTF-8. A longer page fails with payload_too_large and is not charged; the text is never cut.

Out of range is refused, not clamped

An omitted value is filled from the defaults and never refused. A value outside these bounds is a validation_failed naming the field — the API does not round it down for you, because a request that quietly did something other than what it said would be worse than one that failed.

left_to_the_browser

user_agentlocaletime_zoneheaderscookiesgeolocation

These six are omitted by default and stay unset. The browser’s own user agent, locale, time zone, headers, cookies and location behaviour are left exactly as they are — which is not the same as sending empty ones, and is why this list is published rather than left to be inferred.

spec_version

Every capture records the version of the default set that filled it in, and returns it in its own spec_version field. That is what keeps an old capture meaningful after a default changes: you can tell which set of assumptions produced it.

A changed default is a deliberate, visible edit and bumps the version.
A capture made under v1 keeps reporting v1 forever.
If you parse responses strictly, assert on this field — a bump is your signal to re-read this page.

Did this page answer your question?

Tell us what is missing