Essentials options

Reference for the essentials options of the shotkit screenshot API, with an example request for each.

The source to render (exactly one of url, html or markdown), the output format, and what to capture.

`url`

URL of the site to screenshot. Must be http:// or https://. Redirects are followed.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com"}' \
  --fail-with-body -o shot.jpg

`html`

HTML to render instead of a URL. Rendered as a page with no origin. Relative URLs don't resolve, so use absolute URLs for images, stylesheets and fonts. Cookies need an explicit Domain.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<div style=\"display:grid;place-items:center;width:1200px;height:630px;background:#0f172a;color:#fff;font:600 72px system-ui\">Hello, world</div>","viewport_width":1200,"viewport_height":630,"format":"png"}' \
  --fail-with-body -o shot.png

`markdown`

Markdown to render instead of a URL. Converted to HTML and rendered with a clean, readable stylesheet. Useful for social cards, changelogs and reports.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Release notes\n\n- Faster renders\n- Video output\n- Cookie banner blocking","format":"png"}' \
  --fail-with-body -o shot.png

Response format. jpeg is an alias for jpg. gif, mp4 and webm are recorded over time (see Animation); webp is a still image unless an animation option is set. html and markdown return the rendered page's content as text instead of an image.

Type: enum · Default: jpg

Values: jpg, jpeg, png, webp, avif, gif, tiff, pdf, html, markdown, mp4, webm

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","format":"webp"}' \
  --fail-with-body -o shot.webp

`response_type`

Return the file, JSON metadata, or nothing. by_format returns the file itself. json uploads the file and returns its URL with any metadata. empty returns 200 with no body, which is useful with async or to warm the cache.

Type: enum · Default: by_format

Values: by_format, json, empty

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","response_type":"json"}' \
  --fail-with-body -o shot.json

`selector`

CSS selector of the element to capture. Captures only the first matching element. With html/markdown output, returns that element's markup. If nothing matches, the full viewport is captured unless error_on_selector_not_found=true.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","selector":"main"}' \
  --fail-with-body -o shot.jpg

`selector_scroll_into_view`

Scroll to the element to trigger lazy content.

Type: boolean · Default: true

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","selector":"footer","selector_scroll_into_view":false}' \
  --fail-with-body -o shot.jpg

`capture_beyond_viewport`

Capture parts outside the viewport (full page / selector).

Type: boolean

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","selector":"#pricing","capture_beyond_viewport":true}' \
  --fail-with-body -o shot.jpg

`scroll_into_view`

Scroll this selector to the top before capture.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","scroll_into_view":"#pricing"}' \
  --fail-with-body -o shot.jpg

`scroll_into_view_adjust_top`

Pixel offset after scroll_into_view.

Type: number · Default: 0

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","scroll_into_view":"#pricing","scroll_into_view_adjust_top":-80}' \
  --fail-with-body -o shot.jpg

`attachment_name`

Download filename (extension added). Sets Content-Disposition: attachment, so browsers download the file instead of displaying it.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","attachment_name":"homepage"}' \
  --fail-with-body -o shot.jpg

`external_identifier`

Your ID, echoed in webhook headers. Sent back as the X-External-Identifier header on webhook deliveries, so you can match results to your records.

Type: string

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","async":true,"webhook_url":"https://your.app/hooks/shot","external_identifier":"order-1234"}' \
  --fail-with-body -o shot.jpg

`include_shadow_dom`

Include shadow roots in html/markdown output.

Type: boolean · Default: false

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","format":"html","include_shadow_dom":true}' \
  --fail-with-body -o shot.html