{"openapi":"3.1.0","info":{"title":"CurlShot API","version":"1.0.0","description":"Paste a website address and get a screenshot of the whole page as an image or PDF. Free to try, nothing to install. For developers, one simple screenshot API.\n\nAuthenticate with an access key: the `access_key` query parameter, the `X-Access-Key` header, or `Authorization: Bearer`. A key can require signed requests: add `signature` (hex HMAC-SHA256 of the sorted query string, keyed with the secret key) and optionally `expires`. Errors are JSON with `error_code`, `error_message` and `documentation_url`. Human-readable docs: https://curlshot.com/docs. Docs as one markdown file: https://curlshot.com/llms-full.txt.","termsOfService":"https://curlshot.com/terms","contact":{"name":"CurlShot support","url":"https://curlshot.com/contact"}},"externalDocs":{"description":"Documentation","url":"https://curlshot.com/docs"},"servers":[{"url":"https://curlshot.com"}],"tags":[{"name":"Screenshots","description":"Render pages into images and PDFs."},{"name":"Jobs","description":"Background renders started with `async=true` or the bulk endpoint."},{"name":"Account","description":"Quota and limits of the calling account."}],"security":[{"AccessKeyQuery":[]},{"AccessKeyHeader":[]},{"BearerAuth":[]}],"webhooks":{"screenshotFinished":{"post":{"operationId":"onScreenshotFinished","summary":"Sent to `webhook_url` when a background job ends","description":"The body is the job exactly as `GET /api/v1/jobs/{id}` returns it, plus `event`. Signed with two headers: `x-timestamp` (Unix seconds when this attempt was signed) and `x-signature`, the hex HMAC-SHA256 of `<x-timestamp>.<raw body>` keyed with your secret key. Refuse a delivery whose timestamp is more than 5 minutes from your clock, so a captured delivery cannot be replayed. Other headers: `x-webhook-event`, `x-job-id`, `x-webhook-attempt`. Answer with any 2xx status; other answers are retried with a growing delay.","tags":["Jobs"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received."}}}}},"paths":{"/api/v1/screenshot":{"get":{"operationId":"takeScreenshot","summary":"Take a screenshot","description":"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.","tags":["Screenshots"],"parameters":[{"name":"url","in":"query","required":false,"description":"Address of the page to capture.","schema":{"type":"string"},"example":"https://example.com"},{"name":"html","in":"query","required":false,"description":"HTML to render instead of a URL.","schema":{"type":"string"},"example":"<h1>Hello</h1>"},{"name":"markdown","in":"query","required":false,"description":"Markdown to render as a styled page instead of a URL.","schema":{"type":"string"},"example":"# Hello"},{"name":"format","in":"query","required":false,"description":"File format of the result. mp4, webm and gif record a video of the page.","schema":{"type":"string","enum":["png","jpeg","webp","pdf","mp4","webm","gif"],"default":"png"},"example":"png"},{"name":"image_quality","in":"query","required":false,"description":"Compression quality for jpeg and webp. From 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":80},"example":80},{"name":"image_width","in":"query","required":false,"description":"Resize the final image to this width. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":8000},"example":640},{"name":"image_height","in":"query","required":false,"description":"Resize the final image to this height. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":8000},"example":400},{"name":"omit_background","in":"query","required":false,"description":"Keep the page background transparent (png and webp).","schema":{"type":"boolean","default":false},"example":true},{"name":"response_type","in":"query","required":false,"description":"Return the file itself, or JSON with a link to it.","schema":{"type":"string","enum":["by_format","json"],"default":"by_format"},"example":"json"},{"name":"viewport_width","in":"query","required":false,"description":"Width of the browser window. In CSS pixels.","schema":{"type":"integer","minimum":100,"maximum":3840,"default":1280},"example":1280},{"name":"viewport_height","in":"query","required":false,"description":"Height of the browser window. A video uses 720 unless you set it. In CSS pixels.","schema":{"type":"integer","minimum":100,"maximum":4320,"default":1024},"example":1024},{"name":"device_scale_factor","in":"query","required":false,"description":"Pixel density; 2 gives a retina image.","schema":{"type":"number","minimum":1,"maximum":3,"default":1},"example":2},{"name":"viewport_device","in":"query","required":false,"description":"Emulate a phone, tablet or laptop preset.","schema":{"type":"string","enum":["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"]},"example":"iphone_15_pro"},{"name":"viewport_mobile","in":"query","required":false,"description":"Render the mobile layout (honours the viewport meta tag).","schema":{"type":"boolean","default":false},"example":true},{"name":"viewport_landscape","in":"query","required":false,"description":"Rotate the viewport to landscape.","schema":{"type":"boolean","default":false},"example":true},{"name":"full_page","in":"query","required":false,"description":"Capture the whole page, not just the first screen.","schema":{"type":"boolean","default":false},"example":true},{"name":"full_page_scroll","in":"query","required":false,"description":"Scroll through the page first so lazy-loaded images appear.","schema":{"type":"boolean","default":true},"example":false},{"name":"full_page_max_height","in":"query","required":false,"description":"Cut a full-page capture off at this height. In CSS pixels.","schema":{"type":"integer","minimum":100,"maximum":30000,"default":20000},"example":10000},{"name":"selector","in":"query","required":false,"description":"Capture only the first element matching this CSS selector.","schema":{"type":"string"},"example":"#pricing"},{"name":"clip_x","in":"query","required":false,"description":"Left edge of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":0},"example":0},{"name":"clip_y","in":"query","required":false,"description":"Top edge of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":0},"example":0},{"name":"clip_width","in":"query","required":false,"description":"Width of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":8000},"example":600},{"name":"clip_height","in":"query","required":false,"description":"Height of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":30000},"example":400},{"name":"wait_until","in":"query","required":false,"description":"Page event that marks the page as loaded.","schema":{"type":"string","enum":["load","domcontentloaded","networkidle","commit"],"default":"load"},"example":"networkidle"},{"name":"delay","in":"query","required":false,"description":"Extra time to wait after the page has loaded. In seconds.","schema":{"type":"number","minimum":0,"maximum":30,"default":0},"example":2},{"name":"timeout","in":"query","required":false,"description":"Give up if the page is not ready after this long. In seconds.","schema":{"type":"number","minimum":1,"maximum":90,"default":30},"example":60},{"name":"wait_for_selector","in":"query","required":false,"description":"Wait until this element is visible before capturing.","schema":{"type":"string"},"example":".chart-ready"},{"name":"dark_mode","in":"query","required":false,"description":"Ask the page for its dark theme.","schema":{"type":"boolean","default":false},"example":true},{"name":"reduced_motion","in":"query","required":false,"description":"Ask the page to turn animations off.","schema":{"type":"boolean","default":false},"example":true},{"name":"media_type","in":"query","required":false,"description":"CSS media type to render with.","schema":{"type":"string","enum":["screen","print"],"default":"screen"},"example":"print"},{"name":"hide_selectors","in":"query","required":false,"description":"Hide every element matching these CSS selectors.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"example":[".cookie-bar","#chat"]},{"name":"styles","in":"query","required":false,"description":"CSS to add to the page.","schema":{"type":"string"},"example":"body{background:#fff}"},{"name":"scripts","in":"query","required":false,"description":"JavaScript to run on the page before the capture.","schema":{"type":"string"},"example":"document.title='Hi'"},{"name":"click","in":"query","required":false,"description":"Click the first element matching this selector before the capture.","schema":{"type":"string"},"example":"#accept"},{"name":"user_agent","in":"query","required":false,"description":"User-Agent header the browser sends.","schema":{"type":"string"},"example":"MyBot/1.0"},{"name":"headers","in":"query","required":false,"description":"Extra HTTP headers, as \"Name: value\". In a query string, repeat the parameter once per item.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"example":["X-Preview: 1"]},{"name":"cookies","in":"query","required":false,"description":"Cookies to set, as \"name=value; Domain=example.com\". In a query string, repeat the parameter once per item.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"example":["session=abc123"]},{"name":"authorization","in":"query","required":false,"description":"Authorization header sent to the target site only.","schema":{"type":"string"},"example":"Basic dXNlcjpwYXNz"},{"name":"time_zone","in":"query","required":false,"description":"IANA time zone the page sees.","schema":{"type":"string"},"example":"Europe/Berlin"},{"name":"block_ads","in":"query","required":false,"description":"Block requests to ad networks.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_trackers","in":"query","required":false,"description":"Block analytics and tracking scripts.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_cookie_banners","in":"query","required":false,"description":"Hide cookie consent banners.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_chats","in":"query","required":false,"description":"Block live-chat widgets.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_resources","in":"query","required":false,"description":"Block whole kinds of resources.","schema":{"type":"array","items":{"type":"string","enum":["document","stylesheet","image","media","font","script","xhr","fetch","websocket","texttrack","eventsource","manifest","other"]}},"style":"form","explode":false,"example":["font","media"]},{"name":"block_requests","in":"query","required":false,"description":"Block requests whose URL matches these patterns (* is a wildcard).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"example":["*.example.com/ads/*"]},{"name":"pdf_paper_format","in":"query","required":false,"description":"Paper size of the PDF.","schema":{"type":"string","enum":["a0","a1","a2","a3","a4","a5","a6","letter","legal","tabloid","ledger"],"default":"a4"},"example":"letter"},{"name":"pdf_landscape","in":"query","required":false,"description":"Use landscape pages.","schema":{"type":"boolean","default":false},"example":true},{"name":"pdf_print_background","in":"query","required":false,"description":"Print background colors and images.","schema":{"type":"boolean","default":true},"example":false},{"name":"pdf_margin","in":"query","required":false,"description":"Margin on all four sides.","schema":{"type":"string"},"example":"10mm"},{"name":"pdf_margin_top","in":"query","required":false,"description":"Top margin; overrides pdf_margin.","schema":{"type":"string"},"example":"20mm"},{"name":"pdf_margin_right","in":"query","required":false,"description":"Right margin; overrides pdf_margin.","schema":{"type":"string"},"example":"10mm"},{"name":"pdf_margin_bottom","in":"query","required":false,"description":"Bottom margin; overrides pdf_margin.","schema":{"type":"string"},"example":"20mm"},{"name":"pdf_margin_left","in":"query","required":false,"description":"Left margin; overrides pdf_margin.","schema":{"type":"string"},"example":"10mm"},{"name":"pdf_fit_one_page","in":"query","required":false,"description":"Put the whole page on a single tall PDF page.","schema":{"type":"boolean","default":false},"example":true},{"name":"video_duration","in":"query","required":false,"description":"Length of the video. Left out, it follows the height of the page. In seconds.","schema":{"type":"number","minimum":1,"maximum":30},"example":8},{"name":"video_max_duration","in":"query","required":false,"description":"Longest the video may get when its length follows the page. A taller page then scrolls faster. In seconds.","schema":{"type":"number","minimum":1,"maximum":30,"default":30},"example":15},{"name":"video_fps","in":"query","required":false,"description":"Frames per second. A gif takes at most 15.","schema":{"type":"integer","minimum":5,"maximum":30,"default":24},"example":30},{"name":"video_scroll","in":"query","required":false,"description":"Scroll from the top of the page to the bottom while recording.","schema":{"type":"boolean","default":true},"example":false},{"name":"video_scroll_back","in":"query","required":false,"description":"Scroll back to the top at the end, so the video loops cleanly.","schema":{"type":"boolean","default":false},"example":true},{"name":"video_scroll_easing","in":"query","required":false,"description":"How the scroll moves: a soft start and stop, or one even speed.","schema":{"type":"string","enum":["ease_in_out","linear"],"default":"ease_in_out"},"example":"linear"},{"name":"cache","in":"query","required":false,"description":"Serve a stored copy when the same request was made before.","schema":{"type":"boolean","default":false},"example":true},{"name":"cache_ttl","in":"query","required":false,"description":"How long a cached copy stays valid. In seconds.","schema":{"type":"integer","minimum":60,"maximum":2592000,"default":14400},"example":86400},{"name":"cache_key","in":"query","required":false,"description":"Change this value to force a fresh render.","schema":{"type":"string"},"example":"v2"},{"name":"async","in":"query","required":false,"description":"Return at once and render in the background.","schema":{"type":"boolean","default":false},"example":true},{"name":"webhook_url","in":"query","required":false,"description":"Address that receives the result when the render is done.","schema":{"type":"string"},"example":"https://example.com/hook"},{"name":"webhook_sign","in":"query","required":false,"description":"Sign the webhook body so you can verify it came from us.","schema":{"type":"boolean","default":true},"example":false},{"name":"signature","in":"query","required":false,"description":"HMAC-SHA256 signature of the query string, for signed links.","schema":{"type":"string"},"example":"9f86d081..."},{"name":"expires","in":"query","required":false,"description":"Unix time in seconds after which the request is refused. Put it in a signed link to give the link a lifetime.","schema":{"type":"integer"},"example":1767225600}],"responses":{"200":{"description":"The rendered file. With `response_type=json` the body is JSON describing the stored file instead.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotResult"}}}},"202":{"description":"Returned when `async=true`: the render was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"`invalid_url`: The URL is not valid. Use a full http:// or https:// address. `invalid_options`: One or more options are not valid. `invalid_request`: The request could not be read. Send a JSON object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"invalid_url","error_message":"The URL is not valid. Use a full http:// or https:// address.","documentation_url":"https://curlshot.com/docs/errors#invalid_url"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"402":{"description":"`quota_exceeded`: The screenshot quota for this billing period is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"quota_exceeded","error_message":"The screenshot quota for this billing period is used up.","documentation_url":"https://curlshot.com/docs/errors#quota_exceeded"}}}},"403":{"description":"`host_not_allowed`: This host cannot be rendered. Private, local and internal network addresses are blocked. `signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `email_not_verified`: The email address of this account is not verified yet. Open the verification link we emailed you, then retry. `feature_not_available`: Your plan does not include this feature. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"host_not_allowed","error_message":"This host cannot be rendered. Private, local and internal network addresses are blocked.","documentation_url":"https://curlshot.com/docs/errors#host_not_allowed"}}}},"413":{"description":"`content_too_large`: The request or the rendered output is larger than the allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"content_too_large","error_message":"The request or the rendered output is larger than the allowed size.","documentation_url":"https://curlshot.com/docs/errors#content_too_large"}}}},"422":{"description":"`selector_not_found`: No element on the page matches the selector.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"selector_not_found","error_message":"No element on the page matches the selector.","documentation_url":"https://curlshot.com/docs/errors#selector_not_found"}}}},"429":{"description":"`concurrency_limit`: Too many renders are running at once for this account. Retry in a moment. `rate_limited`: Too many requests. Slow down and retry after the indicated delay. `queue_limit`: Too many async jobs of this account are waiting to render. Wait for some to finish, then retry. `failure_limit`: Too many renders of this account failed in the last minute. Fix the failing requests, then retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"concurrency_limit","error_message":"Too many renders are running at once for this account. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#concurrency_limit"}}}},"500":{"description":"`internal_error`: Something went wrong while rendering. The render was not billed; please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"internal_error","error_message":"Something went wrong while rendering. The render was not billed; please retry.","documentation_url":"https://curlshot.com/docs/errors#internal_error"}}}},"502":{"description":"`navigation_failed`: The page could not be loaded. Check that the address is correct and publicly reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"navigation_failed","error_message":"The page could not be loaded. Check that the address is correct and publicly reachable.","documentation_url":"https://curlshot.com/docs/errors#navigation_failed"}}}},"503":{"description":"`renderer_busy`: All render slots are busy right now. Retry in a moment. `renderer_unavailable`: The rendering service is temporarily unavailable. Retry in a moment. `service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"renderer_busy","error_message":"All render slots are busy right now. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#renderer_busy"}}}},"504":{"description":"`timeout`: The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"timeout","error_message":"The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","documentation_url":"https://curlshot.com/docs/errors#timeout"}}}}}},"post":{"operationId":"takeScreenshotPost","summary":"Take a screenshot (JSON body)","description":"Same as the GET form, with the options sent as a JSON object. Use it for `html`, `markdown`, `styles`, `scripts` and other long values.","tags":["Screenshots"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotOptions"},"examples":{"url":{"summary":"Full-page capture of a URL","value":{"url":"https://example.com","full_page":true,"format":"jpeg"}},"html":{"summary":"Render HTML to an image","value":{"html":"<h1 style=\"font:700 64px sans-serif\">Hello</h1>","viewport_width":1200,"viewport_height":630}}}}}},"responses":{"200":{"description":"The rendered file. With `response_type=json` the body is JSON describing the stored file instead.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotResult"}}}},"202":{"description":"Returned when `async=true`: the render was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"`invalid_url`: The URL is not valid. Use a full http:// or https:// address. `invalid_options`: One or more options are not valid. `invalid_request`: The request could not be read. Send a JSON object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"invalid_url","error_message":"The URL is not valid. Use a full http:// or https:// address.","documentation_url":"https://curlshot.com/docs/errors#invalid_url"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"402":{"description":"`quota_exceeded`: The screenshot quota for this billing period is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"quota_exceeded","error_message":"The screenshot quota for this billing period is used up.","documentation_url":"https://curlshot.com/docs/errors#quota_exceeded"}}}},"403":{"description":"`host_not_allowed`: This host cannot be rendered. Private, local and internal network addresses are blocked. `signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `email_not_verified`: The email address of this account is not verified yet. Open the verification link we emailed you, then retry. `feature_not_available`: Your plan does not include this feature. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"host_not_allowed","error_message":"This host cannot be rendered. Private, local and internal network addresses are blocked.","documentation_url":"https://curlshot.com/docs/errors#host_not_allowed"}}}},"413":{"description":"`content_too_large`: The request or the rendered output is larger than the allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"content_too_large","error_message":"The request or the rendered output is larger than the allowed size.","documentation_url":"https://curlshot.com/docs/errors#content_too_large"}}}},"422":{"description":"`selector_not_found`: No element on the page matches the selector.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"selector_not_found","error_message":"No element on the page matches the selector.","documentation_url":"https://curlshot.com/docs/errors#selector_not_found"}}}},"429":{"description":"`concurrency_limit`: Too many renders are running at once for this account. Retry in a moment. `rate_limited`: Too many requests. Slow down and retry after the indicated delay. `queue_limit`: Too many async jobs of this account are waiting to render. Wait for some to finish, then retry. `failure_limit`: Too many renders of this account failed in the last minute. Fix the failing requests, then retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"concurrency_limit","error_message":"Too many renders are running at once for this account. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#concurrency_limit"}}}},"500":{"description":"`internal_error`: Something went wrong while rendering. The render was not billed; please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"internal_error","error_message":"Something went wrong while rendering. The render was not billed; please retry.","documentation_url":"https://curlshot.com/docs/errors#internal_error"}}}},"502":{"description":"`navigation_failed`: The page could not be loaded. Check that the address is correct and publicly reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"navigation_failed","error_message":"The page could not be loaded. Check that the address is correct and publicly reachable.","documentation_url":"https://curlshot.com/docs/errors#navigation_failed"}}}},"503":{"description":"`renderer_busy`: All render slots are busy right now. Retry in a moment. `renderer_unavailable`: The rendering service is temporarily unavailable. Retry in a moment. `service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"renderer_busy","error_message":"All render slots are busy right now. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#renderer_busy"}}}},"504":{"description":"`timeout`: The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"timeout","error_message":"The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","documentation_url":"https://curlshot.com/docs/errors#timeout"}}}}}}},"/api/v1/take":{"get":{"operationId":"take","summary":"Take a screenshot (alias of /api/v1/screenshot)","description":"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.","tags":["Screenshots"],"parameters":[{"name":"url","in":"query","required":false,"description":"Address of the page to capture.","schema":{"type":"string"},"example":"https://example.com"},{"name":"html","in":"query","required":false,"description":"HTML to render instead of a URL.","schema":{"type":"string"},"example":"<h1>Hello</h1>"},{"name":"markdown","in":"query","required":false,"description":"Markdown to render as a styled page instead of a URL.","schema":{"type":"string"},"example":"# Hello"},{"name":"format","in":"query","required":false,"description":"File format of the result. mp4, webm and gif record a video of the page.","schema":{"type":"string","enum":["png","jpeg","webp","pdf","mp4","webm","gif"],"default":"png"},"example":"png"},{"name":"image_quality","in":"query","required":false,"description":"Compression quality for jpeg and webp. From 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":80},"example":80},{"name":"image_width","in":"query","required":false,"description":"Resize the final image to this width. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":8000},"example":640},{"name":"image_height","in":"query","required":false,"description":"Resize the final image to this height. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":8000},"example":400},{"name":"omit_background","in":"query","required":false,"description":"Keep the page background transparent (png and webp).","schema":{"type":"boolean","default":false},"example":true},{"name":"response_type","in":"query","required":false,"description":"Return the file itself, or JSON with a link to it.","schema":{"type":"string","enum":["by_format","json"],"default":"by_format"},"example":"json"},{"name":"viewport_width","in":"query","required":false,"description":"Width of the browser window. In CSS pixels.","schema":{"type":"integer","minimum":100,"maximum":3840,"default":1280},"example":1280},{"name":"viewport_height","in":"query","required":false,"description":"Height of the browser window. A video uses 720 unless you set it. In CSS pixels.","schema":{"type":"integer","minimum":100,"maximum":4320,"default":1024},"example":1024},{"name":"device_scale_factor","in":"query","required":false,"description":"Pixel density; 2 gives a retina image.","schema":{"type":"number","minimum":1,"maximum":3,"default":1},"example":2},{"name":"viewport_device","in":"query","required":false,"description":"Emulate a phone, tablet or laptop preset.","schema":{"type":"string","enum":["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"]},"example":"iphone_15_pro"},{"name":"viewport_mobile","in":"query","required":false,"description":"Render the mobile layout (honours the viewport meta tag).","schema":{"type":"boolean","default":false},"example":true},{"name":"viewport_landscape","in":"query","required":false,"description":"Rotate the viewport to landscape.","schema":{"type":"boolean","default":false},"example":true},{"name":"full_page","in":"query","required":false,"description":"Capture the whole page, not just the first screen.","schema":{"type":"boolean","default":false},"example":true},{"name":"full_page_scroll","in":"query","required":false,"description":"Scroll through the page first so lazy-loaded images appear.","schema":{"type":"boolean","default":true},"example":false},{"name":"full_page_max_height","in":"query","required":false,"description":"Cut a full-page capture off at this height. In CSS pixels.","schema":{"type":"integer","minimum":100,"maximum":30000,"default":20000},"example":10000},{"name":"selector","in":"query","required":false,"description":"Capture only the first element matching this CSS selector.","schema":{"type":"string"},"example":"#pricing"},{"name":"clip_x","in":"query","required":false,"description":"Left edge of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":0},"example":0},{"name":"clip_y","in":"query","required":false,"description":"Top edge of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":0},"example":0},{"name":"clip_width","in":"query","required":false,"description":"Width of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":8000},"example":600},{"name":"clip_height","in":"query","required":false,"description":"Height of the area to capture. In CSS pixels.","schema":{"type":"integer","minimum":1,"maximum":30000},"example":400},{"name":"wait_until","in":"query","required":false,"description":"Page event that marks the page as loaded.","schema":{"type":"string","enum":["load","domcontentloaded","networkidle","commit"],"default":"load"},"example":"networkidle"},{"name":"delay","in":"query","required":false,"description":"Extra time to wait after the page has loaded. In seconds.","schema":{"type":"number","minimum":0,"maximum":30,"default":0},"example":2},{"name":"timeout","in":"query","required":false,"description":"Give up if the page is not ready after this long. In seconds.","schema":{"type":"number","minimum":1,"maximum":90,"default":30},"example":60},{"name":"wait_for_selector","in":"query","required":false,"description":"Wait until this element is visible before capturing.","schema":{"type":"string"},"example":".chart-ready"},{"name":"dark_mode","in":"query","required":false,"description":"Ask the page for its dark theme.","schema":{"type":"boolean","default":false},"example":true},{"name":"reduced_motion","in":"query","required":false,"description":"Ask the page to turn animations off.","schema":{"type":"boolean","default":false},"example":true},{"name":"media_type","in":"query","required":false,"description":"CSS media type to render with.","schema":{"type":"string","enum":["screen","print"],"default":"screen"},"example":"print"},{"name":"hide_selectors","in":"query","required":false,"description":"Hide every element matching these CSS selectors.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"example":[".cookie-bar","#chat"]},{"name":"styles","in":"query","required":false,"description":"CSS to add to the page.","schema":{"type":"string"},"example":"body{background:#fff}"},{"name":"scripts","in":"query","required":false,"description":"JavaScript to run on the page before the capture.","schema":{"type":"string"},"example":"document.title='Hi'"},{"name":"click","in":"query","required":false,"description":"Click the first element matching this selector before the capture.","schema":{"type":"string"},"example":"#accept"},{"name":"user_agent","in":"query","required":false,"description":"User-Agent header the browser sends.","schema":{"type":"string"},"example":"MyBot/1.0"},{"name":"headers","in":"query","required":false,"description":"Extra HTTP headers, as \"Name: value\". In a query string, repeat the parameter once per item.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"example":["X-Preview: 1"]},{"name":"cookies","in":"query","required":false,"description":"Cookies to set, as \"name=value; Domain=example.com\". In a query string, repeat the parameter once per item.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"example":["session=abc123"]},{"name":"authorization","in":"query","required":false,"description":"Authorization header sent to the target site only.","schema":{"type":"string"},"example":"Basic dXNlcjpwYXNz"},{"name":"time_zone","in":"query","required":false,"description":"IANA time zone the page sees.","schema":{"type":"string"},"example":"Europe/Berlin"},{"name":"block_ads","in":"query","required":false,"description":"Block requests to ad networks.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_trackers","in":"query","required":false,"description":"Block analytics and tracking scripts.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_cookie_banners","in":"query","required":false,"description":"Hide cookie consent banners.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_chats","in":"query","required":false,"description":"Block live-chat widgets.","schema":{"type":"boolean","default":false},"example":true},{"name":"block_resources","in":"query","required":false,"description":"Block whole kinds of resources.","schema":{"type":"array","items":{"type":"string","enum":["document","stylesheet","image","media","font","script","xhr","fetch","websocket","texttrack","eventsource","manifest","other"]}},"style":"form","explode":false,"example":["font","media"]},{"name":"block_requests","in":"query","required":false,"description":"Block requests whose URL matches these patterns (* is a wildcard).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"example":["*.example.com/ads/*"]},{"name":"pdf_paper_format","in":"query","required":false,"description":"Paper size of the PDF.","schema":{"type":"string","enum":["a0","a1","a2","a3","a4","a5","a6","letter","legal","tabloid","ledger"],"default":"a4"},"example":"letter"},{"name":"pdf_landscape","in":"query","required":false,"description":"Use landscape pages.","schema":{"type":"boolean","default":false},"example":true},{"name":"pdf_print_background","in":"query","required":false,"description":"Print background colors and images.","schema":{"type":"boolean","default":true},"example":false},{"name":"pdf_margin","in":"query","required":false,"description":"Margin on all four sides.","schema":{"type":"string"},"example":"10mm"},{"name":"pdf_margin_top","in":"query","required":false,"description":"Top margin; overrides pdf_margin.","schema":{"type":"string"},"example":"20mm"},{"name":"pdf_margin_right","in":"query","required":false,"description":"Right margin; overrides pdf_margin.","schema":{"type":"string"},"example":"10mm"},{"name":"pdf_margin_bottom","in":"query","required":false,"description":"Bottom margin; overrides pdf_margin.","schema":{"type":"string"},"example":"20mm"},{"name":"pdf_margin_left","in":"query","required":false,"description":"Left margin; overrides pdf_margin.","schema":{"type":"string"},"example":"10mm"},{"name":"pdf_fit_one_page","in":"query","required":false,"description":"Put the whole page on a single tall PDF page.","schema":{"type":"boolean","default":false},"example":true},{"name":"video_duration","in":"query","required":false,"description":"Length of the video. Left out, it follows the height of the page. In seconds.","schema":{"type":"number","minimum":1,"maximum":30},"example":8},{"name":"video_max_duration","in":"query","required":false,"description":"Longest the video may get when its length follows the page. A taller page then scrolls faster. In seconds.","schema":{"type":"number","minimum":1,"maximum":30,"default":30},"example":15},{"name":"video_fps","in":"query","required":false,"description":"Frames per second. A gif takes at most 15.","schema":{"type":"integer","minimum":5,"maximum":30,"default":24},"example":30},{"name":"video_scroll","in":"query","required":false,"description":"Scroll from the top of the page to the bottom while recording.","schema":{"type":"boolean","default":true},"example":false},{"name":"video_scroll_back","in":"query","required":false,"description":"Scroll back to the top at the end, so the video loops cleanly.","schema":{"type":"boolean","default":false},"example":true},{"name":"video_scroll_easing","in":"query","required":false,"description":"How the scroll moves: a soft start and stop, or one even speed.","schema":{"type":"string","enum":["ease_in_out","linear"],"default":"ease_in_out"},"example":"linear"},{"name":"cache","in":"query","required":false,"description":"Serve a stored copy when the same request was made before.","schema":{"type":"boolean","default":false},"example":true},{"name":"cache_ttl","in":"query","required":false,"description":"How long a cached copy stays valid. In seconds.","schema":{"type":"integer","minimum":60,"maximum":2592000,"default":14400},"example":86400},{"name":"cache_key","in":"query","required":false,"description":"Change this value to force a fresh render.","schema":{"type":"string"},"example":"v2"},{"name":"async","in":"query","required":false,"description":"Return at once and render in the background.","schema":{"type":"boolean","default":false},"example":true},{"name":"webhook_url","in":"query","required":false,"description":"Address that receives the result when the render is done.","schema":{"type":"string"},"example":"https://example.com/hook"},{"name":"webhook_sign","in":"query","required":false,"description":"Sign the webhook body so you can verify it came from us.","schema":{"type":"boolean","default":true},"example":false},{"name":"signature","in":"query","required":false,"description":"HMAC-SHA256 signature of the query string, for signed links.","schema":{"type":"string"},"example":"9f86d081..."},{"name":"expires","in":"query","required":false,"description":"Unix time in seconds after which the request is refused. Put it in a signed link to give the link a lifetime.","schema":{"type":"integer"},"example":1767225600}],"responses":{"200":{"description":"The rendered file. With `response_type=json` the body is JSON describing the stored file instead.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotResult"}}}},"202":{"description":"Returned when `async=true`: the render was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"`invalid_url`: The URL is not valid. Use a full http:// or https:// address. `invalid_options`: One or more options are not valid. `invalid_request`: The request could not be read. Send a JSON object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"invalid_url","error_message":"The URL is not valid. Use a full http:// or https:// address.","documentation_url":"https://curlshot.com/docs/errors#invalid_url"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"402":{"description":"`quota_exceeded`: The screenshot quota for this billing period is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"quota_exceeded","error_message":"The screenshot quota for this billing period is used up.","documentation_url":"https://curlshot.com/docs/errors#quota_exceeded"}}}},"403":{"description":"`host_not_allowed`: This host cannot be rendered. Private, local and internal network addresses are blocked. `signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `email_not_verified`: The email address of this account is not verified yet. Open the verification link we emailed you, then retry. `feature_not_available`: Your plan does not include this feature. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"host_not_allowed","error_message":"This host cannot be rendered. Private, local and internal network addresses are blocked.","documentation_url":"https://curlshot.com/docs/errors#host_not_allowed"}}}},"413":{"description":"`content_too_large`: The request or the rendered output is larger than the allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"content_too_large","error_message":"The request or the rendered output is larger than the allowed size.","documentation_url":"https://curlshot.com/docs/errors#content_too_large"}}}},"422":{"description":"`selector_not_found`: No element on the page matches the selector.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"selector_not_found","error_message":"No element on the page matches the selector.","documentation_url":"https://curlshot.com/docs/errors#selector_not_found"}}}},"429":{"description":"`concurrency_limit`: Too many renders are running at once for this account. Retry in a moment. `rate_limited`: Too many requests. Slow down and retry after the indicated delay. `queue_limit`: Too many async jobs of this account are waiting to render. Wait for some to finish, then retry. `failure_limit`: Too many renders of this account failed in the last minute. Fix the failing requests, then retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"concurrency_limit","error_message":"Too many renders are running at once for this account. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#concurrency_limit"}}}},"500":{"description":"`internal_error`: Something went wrong while rendering. The render was not billed; please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"internal_error","error_message":"Something went wrong while rendering. The render was not billed; please retry.","documentation_url":"https://curlshot.com/docs/errors#internal_error"}}}},"502":{"description":"`navigation_failed`: The page could not be loaded. Check that the address is correct and publicly reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"navigation_failed","error_message":"The page could not be loaded. Check that the address is correct and publicly reachable.","documentation_url":"https://curlshot.com/docs/errors#navigation_failed"}}}},"503":{"description":"`renderer_busy`: All render slots are busy right now. Retry in a moment. `renderer_unavailable`: The rendering service is temporarily unavailable. Retry in a moment. `service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"renderer_busy","error_message":"All render slots are busy right now. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#renderer_busy"}}}},"504":{"description":"`timeout`: The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"timeout","error_message":"The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","documentation_url":"https://curlshot.com/docs/errors#timeout"}}}}}},"post":{"operationId":"takePost","summary":"Take a screenshot (alias, JSON body)","description":"Same as the GET form, with the options sent as a JSON object. Use it for `html`, `markdown`, `styles`, `scripts` and other long values.","tags":["Screenshots"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotOptions"},"examples":{"url":{"summary":"Full-page capture of a URL","value":{"url":"https://example.com","full_page":true,"format":"jpeg"}},"html":{"summary":"Render HTML to an image","value":{"html":"<h1 style=\"font:700 64px sans-serif\">Hello</h1>","viewport_width":1200,"viewport_height":630}}}}}},"responses":{"200":{"description":"The rendered file. With `response_type=json` the body is JSON describing the stored file instead.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotResult"}}}},"202":{"description":"Returned when `async=true`: the render was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"`invalid_url`: The URL is not valid. Use a full http:// or https:// address. `invalid_options`: One or more options are not valid. `invalid_request`: The request could not be read. Send a JSON object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"invalid_url","error_message":"The URL is not valid. Use a full http:// or https:// address.","documentation_url":"https://curlshot.com/docs/errors#invalid_url"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"402":{"description":"`quota_exceeded`: The screenshot quota for this billing period is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"quota_exceeded","error_message":"The screenshot quota for this billing period is used up.","documentation_url":"https://curlshot.com/docs/errors#quota_exceeded"}}}},"403":{"description":"`host_not_allowed`: This host cannot be rendered. Private, local and internal network addresses are blocked. `signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `email_not_verified`: The email address of this account is not verified yet. Open the verification link we emailed you, then retry. `feature_not_available`: Your plan does not include this feature. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"host_not_allowed","error_message":"This host cannot be rendered. Private, local and internal network addresses are blocked.","documentation_url":"https://curlshot.com/docs/errors#host_not_allowed"}}}},"413":{"description":"`content_too_large`: The request or the rendered output is larger than the allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"content_too_large","error_message":"The request or the rendered output is larger than the allowed size.","documentation_url":"https://curlshot.com/docs/errors#content_too_large"}}}},"422":{"description":"`selector_not_found`: No element on the page matches the selector.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"selector_not_found","error_message":"No element on the page matches the selector.","documentation_url":"https://curlshot.com/docs/errors#selector_not_found"}}}},"429":{"description":"`concurrency_limit`: Too many renders are running at once for this account. Retry in a moment. `rate_limited`: Too many requests. Slow down and retry after the indicated delay. `queue_limit`: Too many async jobs of this account are waiting to render. Wait for some to finish, then retry. `failure_limit`: Too many renders of this account failed in the last minute. Fix the failing requests, then retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"concurrency_limit","error_message":"Too many renders are running at once for this account. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#concurrency_limit"}}}},"500":{"description":"`internal_error`: Something went wrong while rendering. The render was not billed; please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"internal_error","error_message":"Something went wrong while rendering. The render was not billed; please retry.","documentation_url":"https://curlshot.com/docs/errors#internal_error"}}}},"502":{"description":"`navigation_failed`: The page could not be loaded. Check that the address is correct and publicly reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"navigation_failed","error_message":"The page could not be loaded. Check that the address is correct and publicly reachable.","documentation_url":"https://curlshot.com/docs/errors#navigation_failed"}}}},"503":{"description":"`renderer_busy`: All render slots are busy right now. Retry in a moment. `renderer_unavailable`: The rendering service is temporarily unavailable. Retry in a moment. `service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"renderer_busy","error_message":"All render slots are busy right now. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#renderer_busy"}}}},"504":{"description":"`timeout`: The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"timeout","error_message":"The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.","documentation_url":"https://curlshot.com/docs/errors#timeout"}}}}}}},"/api/v1/bulk":{"post":{"operationId":"createBulkScreenshots","summary":"Queue many screenshots at once","description":"Each item in `requests` becomes its own background job, billed separately when it succeeds. Jobs are returned in the same order as the requests. The call counts as one request per item against the rate limit. An account may hold a limited number of unfinished jobs at a time (`queue_limit`), and its jobs render at most `concurrency` at once, in turn with the jobs of other accounts.","tags":["Jobs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRequest"},"example":{"requests":[{"url":"https://example.com"},{"url":"https://example.org","full_page":true}],"webhook_url":"https://your-app.example/webhooks/screenshots"}}}},"responses":{"202":{"description":"The jobs were queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAccepted"}}}},"400":{"description":"`invalid_request`: The request could not be read. Send a JSON object. `invalid_options`: One or more options are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"invalid_request","error_message":"The request could not be read. Send a JSON object.","documentation_url":"https://curlshot.com/docs/errors#invalid_request"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"402":{"description":"`quota_exceeded`: The screenshot quota for this billing period is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"quota_exceeded","error_message":"The screenshot quota for this billing period is used up.","documentation_url":"https://curlshot.com/docs/errors#quota_exceeded"}}}},"403":{"description":"`signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`. `feature_not_available`: Your plan does not include this feature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"signature_required","error_message":"This access key only accepts signed requests. Add a `signature` parameter.","documentation_url":"https://curlshot.com/docs/errors#signature_required"}}}},"429":{"description":"`rate_limited`: Too many requests. Slow down and retry after the indicated delay. `queue_limit`: Too many async jobs of this account are waiting to render. Wait for some to finish, then retry. `failure_limit`: Too many renders of this account failed in the last minute. Fix the failing requests, then retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"rate_limited","error_message":"Too many requests. Slow down and retry after the indicated delay.","documentation_url":"https://curlshot.com/docs/errors#rate_limited"}}}},"503":{"description":"`service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"service_unavailable","error_message":"The service is temporarily unavailable. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#service_unavailable"}}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Get the state of a background job","tags":["Jobs"],"parameters":[{"name":"id","in":"path","required":true,"description":"The `job_id` returned when the job was queued.","schema":{"type":"string"}}],"responses":{"200":{"description":"The job.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"403":{"description":"`signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"signature_required","error_message":"This access key only accepts signed requests. Add a `signature` parameter.","documentation_url":"https://curlshot.com/docs/errors#signature_required"}}}},"404":{"description":"`job_not_found`: No job with this id exists for your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"job_not_found","error_message":"No job with this id exists for your account.","documentation_url":"https://curlshot.com/docs/errors#job_not_found"}}}},"429":{"description":"`rate_limited`: Too many requests. Slow down and retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"rate_limited","error_message":"Too many requests. Slow down and retry after the indicated delay.","documentation_url":"https://curlshot.com/docs/errors#rate_limited"}}}},"503":{"description":"`service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"service_unavailable","error_message":"The service is temporarily unavailable. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#service_unavailable"}}}}}}},"/api/v1/batches/{id}":{"get":{"operationId":"getBatch","summary":"Get every job of one bulk call","description":"One call instead of polling each job: a status summary plus the jobs, in request order. Free to call.","tags":["Jobs"],"parameters":[{"name":"id","in":"path","required":true,"description":"The `batch_id` returned by the bulk call.","schema":{"type":"string"}}],"responses":{"200":{"description":"The batch.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"403":{"description":"`signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"signature_required","error_message":"This access key only accepts signed requests. Add a `signature` parameter.","documentation_url":"https://curlshot.com/docs/errors#signature_required"}}}},"404":{"description":"`job_not_found`: No job with this id exists for your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"job_not_found","error_message":"No job with this id exists for your account.","documentation_url":"https://curlshot.com/docs/errors#job_not_found"}}}},"429":{"description":"`rate_limited`: Too many requests. Slow down and retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"rate_limited","error_message":"Too many requests. Slow down and retry after the indicated delay.","documentation_url":"https://curlshot.com/docs/errors#rate_limited"}}}},"503":{"description":"`service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"service_unavailable","error_message":"The service is temporarily unavailable. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#service_unavailable"}}}}}}},"/api/v1/files/{file}":{"get":{"operationId":"getFile","summary":"Download a stored result","description":"The `url` of a JSON answer, a job or a webhook points here. That link carries `expires` and `token` and needs no access key. Without them, the owner can fetch the file with an access key. Files are removed at their `expires_at` time.","tags":["Screenshots"],"security":[{},{"AccessKeyQuery":[]},{"AccessKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"file","in":"path","required":true,"description":"The file id with its extension, for example `0d03cca8e56b496b9ae71d02a4d20675.png`.","schema":{"type":"string"}},{"name":"expires","in":"query","required":false,"description":"Part of the token link: when it stops working (Unix seconds).","schema":{"type":"integer"}},{"name":"token","in":"query","required":false,"description":"Part of the token link.","schema":{"type":"string"}}],"responses":{"200":{"description":"The file.","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"404":{"description":"`file_not_found`: This file does not exist or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"file_not_found","error_message":"This file does not exist or has expired.","documentation_url":"https://curlshot.com/docs/errors#file_not_found"}}}}}}},"/api/v1/devices":{"get":{"operationId":"listDevices","summary":"List the device presets","description":"Every value `viewport_device` accepts, with its viewport. Public: no access key needed.","tags":["Screenshots"],"security":[],"responses":{"200":{"description":"The presets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceList"}}}}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"Get quota and limits for the current billing period","description":"Free to call; it does not use a screenshot.","tags":["Account"],"responses":{"200":{"description":"Current usage.","headers":{"X-Reference-Id":{"description":"Id of this render. Quote it when you contact support.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Screenshots included in the current billing period.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Screenshots left: what remains of the plan quota plus any bonus screenshots.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"When the billing period resets (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute, for the whole account. On status endpoints (usage, jobs, batches, files) it describes their separate, larger allowance.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate-limit window resets (Unix seconds).","schema":{"type":"integer"}},"X-Concurrency-Limit":{"description":"Renders this account may run at the same time.","schema":{"type":"integer"}},"X-Concurrency-Remaining":{"description":"Free render slots right now.","schema":{"type":"integer"}},"X-Cache":{"description":"HIT when a stored copy was served (not billed), otherwise MISS.","schema":{"type":"string","enum":["HIT","MISS"]}},"X-Render-Ms":{"description":"Time the render took, in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"`access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"access_key_required","error_message":"An access key is required. Pass `access_key` or the `X-Access-Key` header.","documentation_url":"https://curlshot.com/docs/errors#access_key_required"}}}},"403":{"description":"`signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"signature_required","error_message":"This access key only accepts signed requests. Add a `signature` parameter.","documentation_url":"https://curlshot.com/docs/errors#signature_required"}}}},"429":{"description":"`rate_limited`: Too many requests. Slow down and retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"rate_limited","error_message":"Too many requests. Slow down and retry after the indicated delay.","documentation_url":"https://curlshot.com/docs/errors#rate_limited"}}}},"503":{"description":"`service_unavailable`: The service is temporarily unavailable. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error_code":"service_unavailable","error_message":"The service is temporarily unavailable. Retry in a moment.","documentation_url":"https://curlshot.com/docs/errors#service_unavailable"}}}}}}}},"components":{"securitySchemes":{"AccessKeyQuery":{"type":"apiKey","in":"query","name":"access_key","description":"Your access key as a query parameter."},"AccessKeyHeader":{"type":"apiKey","in":"header","name":"X-Access-Key","description":"Your access key as a header."},"BearerAuth":{"type":"http","scheme":"bearer","description":"Your access key as a bearer token."}},"schemas":{"ScreenshotOptions":{"type":"object","description":"Options for one render. Exactly one of `url`, `html` or `markdown` is required. Groups: Source (What to render. Exactly one is required.) Output (File format, quality and size of the result.) Viewport (The browser window the page is rendered in.) Capture (Which part of the page ends up in the image.) Waiting (When the page counts as ready.) Customize (Change how the page looks before the capture.) Request (What the browser sends to the site.) Blocking (Remove ads, banners and other noise.) PDF (Options that apply when format is pdf.) Video (Options that apply when format is mp4, webm or gif.) Cache (Reuse a previous render instead of rendering again.) Async and webhooks (Render in the background.) Authentication (Who is making the request.)","properties":{"url":{"type":"string","description":"Address of the page to capture."},"html":{"type":"string","description":"HTML to render instead of a URL."},"markdown":{"type":"string","description":"Markdown to render as a styled page instead of a URL."},"format":{"type":"string","enum":["png","jpeg","webp","pdf","mp4","webm","gif"],"description":"File format of the result. mp4, webm and gif record a video of the page.","default":"png"},"image_quality":{"type":"integer","description":"Compression quality for jpeg and webp. From 1 to 100.","minimum":1,"maximum":100,"default":80},"image_width":{"type":"integer","description":"Resize the final image to this width. In CSS pixels.","minimum":1,"maximum":8000},"image_height":{"type":"integer","description":"Resize the final image to this height. In CSS pixels.","minimum":1,"maximum":8000},"omit_background":{"type":"boolean","description":"Keep the page background transparent (png and webp).","default":false},"response_type":{"type":"string","enum":["by_format","json"],"description":"Return the file itself, or JSON with a link to it.","default":"by_format"},"viewport_width":{"type":"integer","description":"Width of the browser window. In CSS pixels.","minimum":100,"maximum":3840,"default":1280},"viewport_height":{"type":"integer","description":"Height of the browser window. A video uses 720 unless you set it. In CSS pixels.","minimum":100,"maximum":4320,"default":1024},"device_scale_factor":{"type":"number","description":"Pixel density; 2 gives a retina image.","minimum":1,"maximum":3,"default":1},"viewport_device":{"type":"string","enum":["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"],"description":"Emulate a phone, tablet or laptop preset."},"viewport_mobile":{"type":"boolean","description":"Render the mobile layout (honours the viewport meta tag).","default":false},"viewport_landscape":{"type":"boolean","description":"Rotate the viewport to landscape.","default":false},"full_page":{"type":"boolean","description":"Capture the whole page, not just the first screen.","default":false},"full_page_scroll":{"type":"boolean","description":"Scroll through the page first so lazy-loaded images appear.","default":true},"full_page_max_height":{"type":"integer","description":"Cut a full-page capture off at this height. In CSS pixels.","minimum":100,"maximum":30000,"default":20000},"selector":{"type":"string","description":"Capture only the first element matching this CSS selector."},"clip_x":{"type":"integer","description":"Left edge of the area to capture. In CSS pixels.","minimum":0},"clip_y":{"type":"integer","description":"Top edge of the area to capture. In CSS pixels.","minimum":0},"clip_width":{"type":"integer","description":"Width of the area to capture. In CSS pixels.","minimum":1,"maximum":8000},"clip_height":{"type":"integer","description":"Height of the area to capture. In CSS pixels.","minimum":1,"maximum":30000},"wait_until":{"type":"string","enum":["load","domcontentloaded","networkidle","commit"],"description":"Page event that marks the page as loaded.","default":"load"},"delay":{"type":"number","description":"Extra time to wait after the page has loaded. In seconds.","minimum":0,"maximum":30,"default":0},"timeout":{"type":"number","description":"Give up if the page is not ready after this long. In seconds.","minimum":1,"maximum":90,"default":30},"wait_for_selector":{"type":"string","description":"Wait until this element is visible before capturing."},"dark_mode":{"type":"boolean","description":"Ask the page for its dark theme.","default":false},"reduced_motion":{"type":"boolean","description":"Ask the page to turn animations off.","default":false},"media_type":{"type":"string","enum":["screen","print"],"description":"CSS media type to render with.","default":"screen"},"hide_selectors":{"type":"array","items":{"type":"string"},"description":"Hide every element matching these CSS selectors."},"styles":{"type":"string","description":"CSS to add to the page."},"scripts":{"type":"string","description":"JavaScript to run on the page before the capture."},"click":{"type":"string","description":"Click the first element matching this selector before the capture."},"user_agent":{"type":"string","description":"User-Agent header the browser sends."},"headers":{"description":"Extra HTTP headers, as \"Name: value\".","oneOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"array","items":{"type":"string","description":"\"Name: value\""}}]},"cookies":{"type":"array","description":"Cookies to set, as \"name=value; Domain=example.com\".","items":{"oneOf":[{"type":"string","description":"\"name=value; Domain=example.com\""},{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"},"domain":{"type":"string"},"path":{"type":"string"},"secure":{"type":"boolean"},"http_only":{"type":"boolean"},"same_site":{"type":"string","enum":["Strict","Lax","None"]},"expires":{"type":"integer","description":"Unix time in seconds."}}}]}},"authorization":{"type":"string","description":"Authorization header sent to the target site only."},"time_zone":{"type":"string","description":"IANA time zone the page sees."},"block_ads":{"type":"boolean","description":"Block requests to ad networks.","default":false},"block_trackers":{"type":"boolean","description":"Block analytics and tracking scripts.","default":false},"block_cookie_banners":{"type":"boolean","description":"Hide cookie consent banners.","default":false},"block_chats":{"type":"boolean","description":"Block live-chat widgets.","default":false},"block_resources":{"type":"array","items":{"type":"string","enum":["document","stylesheet","image","media","font","script","xhr","fetch","websocket","texttrack","eventsource","manifest","other"]},"description":"Block whole kinds of resources."},"block_requests":{"type":"array","items":{"type":"string"},"description":"Block requests whose URL matches these patterns (* is a wildcard)."},"pdf_paper_format":{"type":"string","enum":["a0","a1","a2","a3","a4","a5","a6","letter","legal","tabloid","ledger"],"description":"Paper size of the PDF.","default":"a4"},"pdf_landscape":{"type":"boolean","description":"Use landscape pages.","default":false},"pdf_print_background":{"type":"boolean","description":"Print background colors and images.","default":true},"pdf_margin":{"type":"string","description":"Margin on all four sides."},"pdf_margin_top":{"type":"string","description":"Top margin; overrides pdf_margin."},"pdf_margin_right":{"type":"string","description":"Right margin; overrides pdf_margin."},"pdf_margin_bottom":{"type":"string","description":"Bottom margin; overrides pdf_margin."},"pdf_margin_left":{"type":"string","description":"Left margin; overrides pdf_margin."},"pdf_fit_one_page":{"type":"boolean","description":"Put the whole page on a single tall PDF page.","default":false},"video_duration":{"type":"number","description":"Length of the video. Left out, it follows the height of the page. In seconds.","minimum":1,"maximum":30},"video_max_duration":{"type":"number","description":"Longest the video may get when its length follows the page. A taller page then scrolls faster. In seconds.","minimum":1,"maximum":30,"default":30},"video_fps":{"type":"integer","description":"Frames per second. A gif takes at most 15.","minimum":5,"maximum":30,"default":24},"video_scroll":{"type":"boolean","description":"Scroll from the top of the page to the bottom while recording.","default":true},"video_scroll_back":{"type":"boolean","description":"Scroll back to the top at the end, so the video loops cleanly.","default":false},"video_scroll_easing":{"type":"string","enum":["ease_in_out","linear"],"description":"How the scroll moves: a soft start and stop, or one even speed.","default":"ease_in_out"},"cache":{"type":"boolean","description":"Serve a stored copy when the same request was made before.","default":false},"cache_ttl":{"type":"integer","description":"How long a cached copy stays valid. In seconds.","minimum":60,"maximum":2592000,"default":14400},"cache_key":{"type":"string","description":"Change this value to force a fresh render."},"async":{"type":"boolean","description":"Return at once and render in the background.","default":false},"webhook_url":{"type":"string","description":"Address that receives the result when the render is done."},"webhook_sign":{"type":"boolean","description":"Sign the webhook body so you can verify it came from us.","default":true},"signature":{"type":"string","description":"HMAC-SHA256 signature of the query string, for signed links."},"expires":{"type":"integer","description":"Unix time in seconds after which the request is refused. Put it in a signed link to give the link a lifetime."}},"additionalProperties":false,"oneOf":[{"required":["url"]},{"required":["html"]},{"required":["markdown"]}]},"Device":{"type":"string","enum":["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"],"description":"Value accepted by `viewport_device`."},"DeviceList":{"type":"object","properties":{"devices":{"type":"array","items":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/Device"},"label":{"type":"string"},"category":{"type":"string","enum":["phone","tablet","laptop","desktop"]},"viewport_width":{"type":"integer"},"viewport_height":{"type":"integer"},"device_scale_factor":{"type":"number"},"viewport_mobile":{"type":"boolean"},"has_touch":{"type":"boolean"},"user_agent":{"type":"string"}},"required":["name","label","category","viewport_width","viewport_height"]}}},"required":["devices"]},"ScreenshotFile":{"type":"object","properties":{"id":{"type":"string","description":"Reference id of the render."},"url":{"type":["string","null"],"format":"uri","description":"Link to the stored file. It carries its own expiring token and needs no access key."},"format":{"type":"string","enum":["png","jpeg","webp","pdf","mp4","webm","gif"]},"bytes":{"type":"integer"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"render_ms":{"type":["integer","null"]},"cached":{"type":"boolean","description":"True when a stored copy was served."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the stored file is removed and its link stops working."}},"required":["id","url","format","bytes"]},"ScreenshotResult":{"$ref":"#/components/schemas/ScreenshotFile"},"JobAccepted":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued"]},"job_url":{"type":"string","format":"uri","description":"Where to poll the job."},"status_url":{"type":"string","format":"uri","description":"The same address as `job_url`."}},"required":["job_id","status","job_url","status_url"]},"Job":{"type":"object","properties":{"job_id":{"type":"string"},"batch_id":{"type":["string","null"]},"status":{"type":"string","enum":["queued","processing","done","failed"]},"job_url":{"type":"string","format":"uri"},"screenshot":{"oneOf":[{"$ref":"#/components/schemas/ScreenshotFile"},{"type":"null"}]},"error_code":{"type":["string","null"],"enum":["invalid_url","host_not_allowed","navigation_failed","timeout","selector_not_found","concurrency_limit","content_too_large","internal_error","renderer_busy","renderer_unavailable","invalid_options","access_key_required","access_key_invalid","signature_required","signature_invalid","quota_exceeded","rate_limited","job_not_found","service_unavailable","invalid_request","email_not_verified","feature_not_available","request_expired","not_found","file_not_found","method_not_allowed","queue_limit","failure_limit",null]},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}},"required":["job_id","status","job_url"]},"Batch":{"type":"object","properties":{"batch_id":{"type":"string"},"batch_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["processing","done"],"description":"`done` once every job is done or failed."},"total":{"type":"integer"},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"processing":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"}}},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}},"required":["batch_id","status","total","counts","jobs"]},"WebhookEvent":{"description":"Body POSTed to `webhook_url` when a job ends: the `Job` object plus `event`. Signed with the `x-signature` header (hex HMAC-SHA256 of `<x-timestamp>.<raw body>`, keyed with the secret key).","allOf":[{"$ref":"#/components/schemas/Job"},{"type":"object","properties":{"event":{"type":"string","enum":["screenshot.completed","screenshot.failed"]}},"required":["event"]}]},"BulkRequest":{"type":"object","properties":{"requests":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ScreenshotOptions"}},"webhook_url":{"type":"string","format":"uri","description":"Receives one event per finished job."}},"required":["requests"]},"BulkAccepted":{"type":"object","properties":{"batch_id":{"type":"string"},"batch_url":{"type":"string","format":"uri","description":"Where to read the state of every job at once."},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/JobAccepted"}}},"required":["batch_id","batch_url","jobs"]},"Usage":{"type":"object","properties":{"plan":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"quota":{"type":"integer","description":"Screenshots included in this period."},"used":{"type":"integer"},"remaining":{"type":"integer"},"bonus_remaining":{"type":"integer","description":"Bonus screenshots left (referrals, promotions)."},"rate_limit_per_minute":{"type":"integer"},"concurrency":{"type":"integer","description":"Renders that may run at the same time."},"full_page_max_height":{"type":"integer","description":"Tallest full-page capture on this plan, in page pixels."},"full_page_max_scale":{"type":"number","description":"Largest device_scale_factor of a full-page capture on this plan."},"video_max_seconds":{"type":"number","description":"Longest video (format mp4, webm, gif) on this plan, in seconds; 0 when the plan has no video capture."}},"required":["quota","used","remaining"]},"Error":{"type":"object","properties":{"error_code":{"type":"string","enum":["invalid_url","host_not_allowed","navigation_failed","timeout","selector_not_found","concurrency_limit","content_too_large","internal_error","renderer_busy","renderer_unavailable","invalid_options","access_key_required","access_key_invalid","signature_required","signature_invalid","quota_exceeded","rate_limited","job_not_found","service_unavailable","invalid_request","email_not_verified","feature_not_available","request_expired","not_found","file_not_found","method_not_allowed","queue_limit","failure_limit"]},"error_message":{"type":"string","description":"What went wrong, in plain language."},"documentation_url":{"type":"string","format":"uri","description":"The docs section for this error."},"errors":{"type":"array","description":"Only with `invalid_options`: one entry per rejected option.","items":{"type":"object","properties":{"field":{"type":"string","description":"The option name."},"message":{"type":"string"},"index":{"type":"integer","description":"Bulk only: position of the request in `requests`."}},"required":["field","message"]}}},"required":["error_code","error_message"],"x-retryable-codes":["navigation_failed","timeout","internal_error","renderer_busy","renderer_unavailable","service_unavailable"]}}}}