Screenshots

Take a screenshot (alias of /api/v1/screenshot)

Render a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Exactly one of url, html or markdown is required. A successful render uses one screenshot of the monthly quota; cache hits and failed renders are free.

get/api/v1/take

Request

  • Base URL: https://curlshot.com
  • URL: https://curlshot.com/api/v1/take
  • Auth: one of:
    • API key in query parameter access_key
    • API key in header X-Access-Key
    • HTTP bearer

Query parameters

urlstring

Address of the page to capture.

htmlstring

HTML to render instead of a URL.

markdownstring

Markdown to render as a styled page instead of a URL.

format'png' | 'jpeg' | 'webp' | 'pdf' | 'mp4' | 'webm' | 'gif'

File format of the result. mp4, webm and gif record a video of the page.

image_qualityinteger

Compression quality for jpeg and webp. From 1 to 100.

image_widthinteger

Resize the final image to this width. In CSS pixels.

image_heightinteger

Resize the final image to this height. In CSS pixels.

omit_backgroundboolean

Keep the page background transparent (png and webp).

response_type'by_format' | 'json'

Return the file itself, or JSON with a link to it.

viewport_widthinteger

Width of the browser window. In CSS pixels.

viewport_heightinteger

Height of the browser window. A video uses 720 unless you set it. In CSS pixels.

device_scale_factornumber

Pixel density; 2 gives a retina image.

viewport_device'iphone_se' | 'iphone_12' | 'iphone_13' | 'iphone_13_mini' | 'iphone_14' | 'iphone_14_plus' | 'iphone_14_pro' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_16' | 'iphone_16_plus' | 'iphone_16_pro' | 'iphone_16_pro_max' | 'pixel_5' | 'pixel_7' | 'pixel_8' | 'pixel_8_pro' | 'pixel_9' | 'pixel_9_pro' | 'galaxy_s23' | 'galaxy_s24' | 'galaxy_s24_ultra' | 'galaxy_a54' | 'ipad' | 'ipad_mini' | 'ipad_air' | 'ipad_pro_11' | 'ipad_pro_13' | 'galaxy_tab_s9' | 'pixel_tablet' | 'macbook_air_13' | 'macbook_pro_14' | 'macbook_pro_16' | 'laptop_hd' | 'laptop_hidpi' | 'desktop_hd' | 'desktop_full_hd' | 'desktop_qhd' | 'desktop_4k' | 'imac_24'

Emulate a phone, tablet or laptop preset.

viewport_mobileboolean

Render the mobile layout (honours the viewport meta tag).

viewport_landscapeboolean

Rotate the viewport to landscape.

full_pageboolean

Capture the whole page, not just the first screen.

full_page_scrollboolean

Scroll through the page first so lazy-loaded images appear.

full_page_max_heightinteger

Cut a full-page capture off at this height. In CSS pixels.

selectorstring

Capture only the first element matching this CSS selector.

clip_xinteger

Left edge of the area to capture. In CSS pixels.

clip_yinteger

Top edge of the area to capture. In CSS pixels.

clip_widthinteger

Width of the area to capture. In CSS pixels.

clip_heightinteger

Height of the area to capture. In CSS pixels.

wait_until'load' | 'domcontentloaded' | 'networkidle' | 'commit'

Page event that marks the page as loaded.

delaynumber

Extra time to wait after the page has loaded. In seconds.

timeoutnumber

Give up if the page is not ready after this long. In seconds.

wait_for_selectorstring

Wait until this element is visible before capturing.

dark_modeboolean

Ask the page for its dark theme.

reduced_motionboolean

Ask the page to turn animations off.

media_type'screen' | 'print'

CSS media type to render with.

hide_selectorsstring[]

Hide every element matching these CSS selectors.

stylesstring

CSS to add to the page.

scriptsstring

JavaScript to run on the page before the capture.

clickstring

Click the first element matching this selector before the capture.

user_agentstring

User-Agent header the browser sends.

headersstring[]

Extra HTTP headers, as "Name: value". In a query string, repeat the parameter once per item.

cookiesstring[]

Cookies to set, as "name=value; Domain=example.com". In a query string, repeat the parameter once per item.

authorizationstring

Authorization header sent to the target site only.

time_zonestring

IANA time zone the page sees.

block_adsboolean

Block requests to ad networks.

block_trackersboolean

Block analytics and tracking scripts.

block_cookie_bannersboolean

Hide cookie consent banners.

block_chatsboolean

Block live-chat widgets.

block_resourcesstring[]

Block whole kinds of resources.

block_requestsstring[]

Block requests whose URL matches these patterns (* is a wildcard).

pdf_paper_format'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6' | 'letter' | 'legal' | 'tabloid' | 'ledger'

Paper size of the PDF.

pdf_landscapeboolean

Use landscape pages.

pdf_print_backgroundboolean

Print background colors and images.

pdf_marginstring

Margin on all four sides.

pdf_margin_topstring

Top margin; overrides pdf_margin.

pdf_margin_rightstring

Right margin; overrides pdf_margin.

pdf_margin_bottomstring

Bottom margin; overrides pdf_margin.

pdf_margin_leftstring

Left margin; overrides pdf_margin.

pdf_fit_one_pageboolean

Put the whole page on a single tall PDF page.

video_durationnumber

Length of the video. Left out, it follows the height of the page. In seconds.

video_max_durationnumber

Longest the video may get when its length follows the page. A taller page then scrolls faster. In seconds.

video_fpsinteger

Frames per second. A gif takes at most 15.

video_scrollboolean

Scroll from the top of the page to the bottom while recording.

video_scroll_backboolean

Scroll back to the top at the end, so the video loops cleanly.

video_scroll_easing'ease_in_out' | 'linear'

How the scroll moves: a soft start and stop, or one even speed.

cacheboolean

Serve a stored copy when the same request was made before.

cache_ttlinteger

How long a cached copy stays valid. In seconds.

cache_keystring

Change this value to force a fresh render.

asyncboolean

Return at once and render in the background.

webhook_urlstring

Address that receives the result when the render is done.

webhook_signboolean

Sign the webhook body so you can verify it came from us.

signaturestring

HMAC-SHA256 signature of the query string, for signed links.

expiresinteger

Unix time in seconds after which the request is refused. Put it in a signed link to give the link a lifetime.

Response

The rendered file. With response_type=json the body is JSON describing the stored file instead.

idstring required

Reference id of the render.

urlstring uri nullable required

Link to the stored file. It carries its own expiring token and needs no access key.

format'png' | 'jpeg' | 'webp' | 'pdf' | 'mp4' | 'webm' | 'gif' required
bytesinteger required
widthinteger nullable
heightinteger nullable
render_msinteger nullable
cachedboolean

True when a stored copy was served.

expires_atstring date-time nullable

When the stored file is removed and its link stops working.

Changes

No recorded changes to this operation across all 1 revision of this API.