Render a screenshot

Render a web page (`url`) or a raw HTML string (`html`) to a PNG, JPEG, WebP image, or a PDF. Provide **exactly one** of `url` or `html`. By default the request is **synchronous**: dOCR renders the page and returns the finished screenshot record (with a hosted `url`) in the response. Set `async: true` to return immediately with a `pending` record and receive a [`screenshot.completed`](/docs/guides/webhooks) webhook when the render finishes. Each successful render costs **1 credit**. Cache hits and failed renders cost nothing. See the [Screenshots guide](/docs/guides/screenshots) for a full walkthrough of formats, devices, caching, and signed URLs.

Authorization

AuthorizationBearer <token>

API key as a Bearer token: Authorization: Bearer docr_sk_…

In: header

Request Body

url?string

URL to render. Provide exactly one of url or html.

Formaturi

html?string

Raw HTML to render. Provide exactly one of url or html.

format?string

Output format.

Default"png"

fullPage?boolean

Capture the entire scrollable page rather than just the viewport.

Defaultfalse

viewportWidth?integer

Viewport width in pixels. Ignored when device is set.

Default1280

Range100 <= value <= 3840

viewportHeight?integer

Viewport height in pixels. Ignored when device is set.

Default1024

Range100 <= value <= 4320

device?string

A device preset. When set, it overrides viewportWidth, viewportHeight, and deviceScaleFactor.

deviceScaleFactor?number

Pixel density. 2 produces a retina-resolution image.

Default1

Range1 <= value <= 3

imageQuality?integer

Compression quality for jpeg and webp. Ignored for png.

Default80

Range0 <= value <= 100

omitBackground?boolean

Render a transparent background (PNG/WebP).

Defaultfalse

blockAds?boolean

Block known ad networks before rendering.

Defaultfalse

blockCookieBanners?boolean

Hide common cookie-consent banners.

Defaultfalse

blockChats?boolean

Hide common chat and support widgets.

Defaultfalse

delay?integer

Seconds to wait after the page loads before capturing.

Default0

Range0 <= value <= 30

waitUntil?string

The navigation lifecycle event to wait for before capturing.

Default"load"

Value in"load" | "domcontentloaded" | "networkidle0" | "networkidle2"

waitForSelector?string

Wait until this CSS selector appears before capturing.

timeout?integer

Maximum seconds to wait for navigation before failing.

Default60

Range1 <= value <= 90

darkMode?boolean

Emulate prefers-color-scheme: dark.

cache?boolean

Reuse a previously stored render for an identical set of options. A cache hit returns instantly and costs 0 credits.

Defaultfalse

cacheTtl?integer

How long a cached render stays valid, in seconds (4 hours–30 days).

Range14400 <= value <= 2592000

async?boolean

Render in the background. Returns a 202 with a pending record; completion is delivered to webhookUrl and your account webhooks.

Defaultfalse

webhookUrl?string

URL to receive the completion event when async is true.

Formaturi

store?boolean

Persist the render to storage and return a hosted url. Set to false to stream the raw bytes back in the response without storing.

Defaulttrue

selector?string

CSS selector of a single element to screenshot (instead of the page).

scrollIntoView?string

CSS selector to scroll into view before capturing.

clipX?integer

Left offset of the capture region (with clipY/clipWidth/clipHeight).

clipY?integer

Top offset of the capture region.

clipWidth?integer

Width of the capture region. Must be set together with clipHeight.

clipHeight?integer

Height of the capture region. Must be set together with clipWidth.

viewportMobile?boolean

Emulate a mobile device (respects the meta viewport tag).

Defaultfalse

viewportHasTouch?boolean

Emulate touch support.

Defaultfalse

viewportLandscape?boolean

Emulate landscape orientation.

Defaultfalse

imageWidth?integer

Resize the output image to this width (thumbnail), preserving aspect ratio.

imageHeight?integer

Resize the output image to this height (thumbnail), preserving aspect ratio.

fullPageScroll?boolean

Scroll to the bottom and back before capturing, to trigger lazy-loaded content.

Defaultfalse

fullPageMaxHeight?integer

Cap the height (px) of a full-page capture; handles infinite-scroll pages.

pdfPrintBackground?boolean

Print background graphics in the PDF.

Defaulttrue

pdfLandscape?boolean

Use landscape orientation.

Defaultfalse

pdfPaperFormat?string

Paper size for the PDF.

Value in"a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "a6" | "letter" | "legal" | "tabloid" | "ledger"

pdfFitOnePage?boolean

Size the PDF page to fit the full content on one page.

Defaultfalse

pdfMargin?number

Uniform PDF margin in px (overridden by per-side margins).

pdfMarginTop?number

pdfMarginRight?number

pdfMarginBottom?number

pdfMarginLeft?number

reducedMotion?boolean

Emulate prefers-reduced-motion: reduce.

Defaultfalse

mediaType?string

Emulate the CSS media type.

Value in"screen" | "print"

hideSelectors?array<string>

CSS selectors to hide (display:none) before capturing.

click?string

CSS selector to click before capturing.

hover?string

CSS selector to hover before capturing.

styles?string

Custom CSS injected into the page.

scripts?string

Custom JavaScript evaluated in the page before capturing.

blockTrackers?boolean

Block common analytics/tracker requests.

Defaultfalse

blockResources?array<string>

Block requests of these resource types.

blockRequests?array<string>

Block requests whose URL matches these glob patterns (e.g. *.ads.com/*).

userAgent?string

Override the User-Agent header.

authorization?string

Value for the Authorization request header (for protected pages).

cookies?array<string>

Cookies to set, each name=value; Domain=...; Path=/; Secure.

headers?array<string>

Extra request headers, each Header-Name: value.

timeZone?string

Emulate this IANA time zone (e.g. America/New_York).

bypassCsp?boolean

Bypass the page's Content-Security-Policy (needed for some injected scripts).

Defaultfalse

navigationTimeout?integer

Max seconds to wait for the target site to respond.

Default30

Range1 <= value <= 30

ignoreHostErrors?boolean

Screenshot the page even when the host responds with a 4xx/5xx status.

Defaultfalse

failIfRequestFailed?boolean

Fail the render if any network request fails during load.

Defaultfalse

failIfContentContains?string

Fail the render if the page text contains this string (case-insensitive).

failIfContentMissing?string

Fail the render if the page text does NOT contain this string.

metadataImageSize?boolean

Return the rendered image's width/height/bytes in metadata.

Defaultfalse

metadataPageTitle?boolean

Return the page <title> in metadata.

Defaultfalse

metadataIcon?boolean

Return the page favicon URL in metadata.

Defaultfalse

metadataOpenGraph?boolean

Return Open Graph / Twitter card tags in metadata.

Defaultfalse

metadataContent?boolean

Return the page HTML content in metadata.

Defaultfalse

metadataHttpStatusCode?boolean

Return the host HTTP status code in metadata.

Defaultfalse

metadataHttpHeaders?boolean

Return the host HTTP response headers in metadata.

Defaultfalse

cacheKey?string

Custom cache key (overrides the computed one) when cache is true.

webhookSign?boolean

Sign the one-off webhookUrl delivery with your org signing secret.

Defaulttrue

webhookErrors?boolean

Also deliver screenshot.failed events to webhookUrl.

Defaultfalse

externalIdentifier?string

Correlation id echoed back in webhook events and the X-docr-External-Identifier header.

Response Body

application/json

curl -X POST "https://app.docr.dev/api/v1/screenshots" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "fullPage": true,
    "viewportWidth": 1280
  }'

curl -X POST "https://app.docr.dev/api/v1/screenshots" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com",    "format": "png",    "fullPage": true,    "viewportWidth": 1280  }'

{
  "screenshot": {
    "id": "6a382443304f240b189f228a",
    "orgId": "string",
    "kind": "screenshot",
    "status": "pending",
    "format": "png",
    "url": "https://res.cloudinary.com/docr/image/upload/screenshot-6a382443.png",
    "width": 1280,
    "height": 3840,
    "fullPage": true,
    "cacheHit": true,
    "creditsUsed": 1,
    "externalIdentifier": "string",
    "metadata": {},
    "error": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "screenshot": {
    "id": "6a382443304f240b189f228a",
    "orgId": "string",
    "kind": "screenshot",
    "status": "pending",
    "format": "png",
    "url": "https://res.cloudinary.com/docr/image/upload/screenshot-6a382443.png",
    "width": 1280,
    "height": 3840,
    "fullPage": true,
    "cacheHit": true,
    "creditsUsed": 1,
    "externalIdentifier": "string",
    "metadata": {},
    "error": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "error": "string"
}

{
  "error": "Invalid or revoked API key"
}

{
  "error": "Credit limit reached (100/100). Upgrade your plan."
}

{
  "error": "IP 203.0.113.4 is not whitelisted"
}

{
  "error": "string"
}

Render a screenshot

Authorization

Request Body

Response Body

200

202application/json

400application/json

401application/json

402application/json

403application/json

422application/json

application/json

application/json

application/json

application/json

application/json

application/json