Website Screenshot API

OverviewLink to Overview

Piloterr’s Screenshot API renders a webpage like a real browser and returns a screenshot (PNG/JPEG/WebP) or a PDF. It’s designed for workflows where you need a reliable visual output for previews, reporting, QA, monitoring, and archiving without building your own headless browser infrastructure.

Typical use casesLink to Typical use cases

• Website previews & thumbnails: generate consistent previews for links in dashboards, directories, or SEO tools.
• QA & visual regression: capture pages across releases (desktop/mobile) to detect UI changes.
• Reporting & client deliverables: export full-page screenshots or PDFs for audits and documentation.
• Monitoring & compliance: store visual proof of page state at a given time (pricing pages, legal pages, ads).
• Product / page capture: take clean product screenshots while removing cookie banners/ads/popups.
• Component capture: screenshot a specific element (card, widget, chart) rather than the full page.

QuickstartLink to Quickstart

Send a request with url and your access_key. The response body is the generated file (binary).

Example request:

`curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com" --output capture.png`

Common variants:

Full page

`curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com&full_page=true" --output full.png`

Mobile preview

`curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com&device=iphone_14_pro" --output mobile.png`

PDF export

`curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com&format=pdf&full_page=true" --output page.pdf`

ParametersLink to Parameters

RequiredLink to Required

• url (string): Webpage URL to render and capture.

• x-api-key (string): API key (can be provided as query param, header x-api-key, or request body).

OutputLink to Output

• format (optional): Output file type (png default; also supports webp, jpeg/jpg, pdf).
• viewport_width / viewport_height (optional): Control the desktop viewport size.
• scale_factor (optional): Increase pixel density for sharper output.
• image_quality (optional): Compression quality for webp / jpeg.

Mobile / responsive testingLink to Mobile / responsive testing

• device (optional): Emulate a predefined mobile/tablet device profile.

Full-page captureLink to Full-page capture

• full_page (optional): Capture the entire page height.
• full_page_scroll / full_page_scroll_duration (optional): Scroll to trigger lazy-loaded content during full-page capture.

Timing (JS-heavy pages)Link to Timing (JS-heavy pages)

• wait_for_selector (optional): Wait until a CSS selector exists before capturing (best for SPAs).
• wait_until (optional): Choose the page readiness event.
• delay (optional): Fixed wait time before capture.

Cleanup (remove overlays)Link to Cleanup (remove overlays)

• remove_cookie_banners (optional): Attempt to remove cookie banners.
• remove_ads (optional): Attempt to remove ads.
• remove_selectors (optional): Remove specific elements via CSS selectors.
• selector (optional): Capture only one specific element.

Performance / routingLink to Performance / routing

• block_urls (optional): Block matching URL patterns (trackers, analytics).
• block_resources (optional): Block resource types (images, fonts, etc.).
• proxy (optional): Route through a proxy (geo / restricted / anti-bot cases).

CachingLink to Caching

• cache (optional): Cache results for repeated requests.
• cache_ttl (optional): Cache TTL in seconds.

Storage (optional)Link to Storage (optional)

• S3 upload: s3_url + bucket/credentials fields to upload directly to S3 or S3-compatible storage.

Notes / limitsLink to Notes / limits

• Page variability: dynamic pages can change between captures; store timestamps with your outputs.
• SPAs need deterministic waits: prefer wait_for_selector for consistent results on JS-heavy sites.
• Full-page + infinite scroll: pages with endless content can produce unpredictable full-page renders.
• Cleanup isn’t universal: cookie banners/ads vary by site; remove_selectors is the most reliable fallback.
• Performance tradeoffs: higher scale_factor and full-page captures increase output size and render time.
• Binary response handling: treat responses as binary (Blob/ArrayBuffer) in your playground/client.