{"openapi":"3.1.0","info":{"title":"Screenshot API","version":"1.0.0","description":"Take a screenshot of any public web page. Optionally from a chosen country, with a signed technical attestation of the country observed."},"servers":[{"url":"https:\/\/localscreenshot.com\/v1"}],"paths":{"\/screenshot":{"get":{"summary":"Take a screenshot","description":"Waits for the screenshot and returns the image. A failed screenshot is not charged. Send an Idempotency-Key header to make a retry safe: the same key returns the same screenshot without charging twice.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The image, or the JSON document when response=json.","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"}},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Screenshot"}}}},"202":{"description":"Still running (async=true, or it took longer than the wait). Read it again at the Location header.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Screenshot"}}}},"default":{"$ref":"#\/components\/responses\/Error"}},"operationId":"takeScreenshot","parameters":[{"name":"url","in":"query","required":true,"description":"The public http or https page to capture.","schema":{"type":"string","format":"uri"}},{"name":"country","in":"query","required":false,"description":"Load the page from this country (ISO 3166-1 alpha-2 code, see \/v1\/countries). The response reports the country actually observed. If it cannot be obtained, the request fails and is not charged. Costs 2 credits instead of 1.","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"viewport","in":"query","required":false,"description":"Screen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height.","schema":{"type":"string","pattern":"^\\d+x\\d+$"}},{"name":"viewport_width","in":"query","required":false,"description":"Width of the browser window, in pixels.","schema":{"type":"integer","minimum":320,"maximum":3840,"default":1440}},{"name":"viewport_height","in":"query","required":false,"description":"Height of the browser window, in pixels. With full_page, the image is taller than this.","schema":{"type":"integer","minimum":320,"maximum":2160,"default":900}},{"name":"device_scale_factor","in":"query","required":false,"description":"Pixel density. 2 gives a sharper, larger image.","schema":{"type":"number","minimum":1,"maximum":3,"default":1}},{"name":"device","in":"query","required":false,"description":"Capture as this device (screen size, pixel density, mobile browser).","schema":{"type":"string","enum":["desktop","desktop_hd","laptop","ipad","ipad_pro","ipad_mini","iphone_15","iphone_15_pro_max","iphone_se","pixel_8","galaxy_s24"]}},{"name":"full_page","in":"query","required":false,"description":"Capture the whole scrollable page instead of the visible part.","schema":{"type":"boolean","default":false}},{"name":"selector","in":"query","required":false,"description":"Capture only the first element matching this CSS selector.","schema":{"type":"string","maxLength":200}},{"name":"format","in":"query","required":false,"description":"File format. pdf saves the whole page as a document; it cannot be combined with selector or max_width.","schema":{"type":"string","enum":["png","jpeg","webp","pdf"],"default":"png"}},{"name":"quality","in":"query","required":false,"description":"Quality for jpeg and webp. Ignored for png and pdf.","schema":{"type":"integer","minimum":1,"maximum":100,"default":80}},{"name":"color_scheme","in":"query","required":false,"description":"Ask the page for its light or dark theme.","schema":{"type":"string","enum":["light","dark"]}},{"name":"language","in":"query","required":false,"description":"Browser language, for example fr or fr-FR.","schema":{"type":"string","default":"en-US"}},{"name":"timezone","in":"query","required":false,"description":"Browser time zone, for example Europe\/Paris.","schema":{"type":"string"}},{"name":"wait_for","in":"query","required":false,"description":"Wait until an element matching this CSS selector is visible.","schema":{"type":"string","maxLength":200}},{"name":"delay_ms","in":"query","required":false,"description":"Extra wait before the capture, in milliseconds.","schema":{"type":"integer","minimum":0,"maximum":5000,"default":0}},{"name":"hide_selectors","in":"query","required":false,"description":"Hide every element matching these CSS selectors. In a URL, separate them with commas.","schema":{"type":"array","maxItems":20,"items":{"type":"string"}},"style":"form","explode":false},{"name":"disable_animations","in":"query","required":false,"description":"Freeze animations and transitions.","schema":{"type":"boolean","default":false}},{"name":"hide_sticky_elements","in":"query","required":false,"description":"Hide headers, bars and buttons that stay fixed on screen.","schema":{"type":"boolean","default":false}},{"name":"block_cookie_banners","in":"query","required":false,"description":"Removes most cookie banners. A banner the filters do not know stays in the picture.","schema":{"type":"boolean","default":false}},{"name":"block_ads","in":"query","required":false,"description":"Block ads.","schema":{"type":"boolean","default":false}},{"name":"block_chat_widgets","in":"query","required":false,"description":"Hide chat bubbles.","schema":{"type":"boolean","default":false}},{"name":"close_popups","in":"query","required":false,"description":"Close pop-ups and newsletter overlays.","schema":{"type":"boolean","default":false}},{"name":"max_width","in":"query","required":false,"description":"Scale the image down to this width. Useful to keep it small for a vision model.","schema":{"type":"integer","minimum":320,"maximum":3840}},{"name":"response","in":"query","required":false,"description":"image returns the picture itself. json returns its link, the page details and the attestation.","schema":{"type":"string","enum":["image","json"],"default":"image"}},{"name":"async","in":"query","required":false,"description":"Return an id right away instead of waiting. Read the result at \/v1\/screenshots\/{id}.","schema":{"type":"boolean","default":false}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]},"post":{"summary":"Take a screenshot","description":"Waits for the screenshot and returns the image. A failed screenshot is not charged. Send an Idempotency-Key header to make a retry safe: the same key returns the same screenshot without charging twice.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The image, or the JSON document when response=json.","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"}},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Screenshot"}}}},"202":{"description":"Still running (async=true, or it took longer than the wait). Read it again at the Location header.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Screenshot"}}}},"default":{"$ref":"#\/components\/responses\/Error"}},"operationId":"takeScreenshotPost","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ScreenshotRequest"}}}}}},"\/screenshots":{"get":{"operationId":"listScreenshots","summary":"List your screenshots, newest first","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"How many to return, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The next_cursor of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of screenshots. next_cursor is null on the last page.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Screenshot"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"$ref":"#\/components\/responses\/Error"}}}},"\/screenshots\/{id}":{"delete":{"operationId":"deleteScreenshot","summary":"Delete a screenshot","description":"The image and its details are destroyed and its links stop working. A screenshot still running is cancelled and not charged. Credits already used are not given back.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#\/components\/parameters\/Id"}],"responses":{"204":{"description":"Deleted."},"default":{"$ref":"#\/components\/responses\/Error"}}},"get":{"operationId":"getScreenshot","summary":"Read a screenshot","security":[{"apiKey":[]}],"parameters":[{"$ref":"#\/components\/parameters\/Id"}],"responses":{"200":{"description":"The screenshot.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Screenshot"}}}},"default":{"$ref":"#\/components\/responses\/Error"}}}},"\/screenshots\/{id}\/attestation":{"get":{"operationId":"getAttestation","summary":"Read the signed attestation of a screenshot taken from a chosen country","security":[{"apiKey":[]}],"parameters":[{"$ref":"#\/components\/parameters\/Id"}],"responses":{"200":{"description":"The attestation.","content":{"application\/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#\/components\/responses\/Error"}}}},"\/credits":{"get":{"operationId":"getCredits","summary":"Credits left and limits","security":[{"apiKey":[]}],"responses":{"200":{"description":"Credits.","content":{"application\/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#\/components\/responses\/Error"}}}},"\/countries":{"get":{"operationId":"listCountries","summary":"Countries a screenshot can be taken from","responses":{"200":{"description":"Countries.","content":{"application\/json":{"schema":{"type":"object"}}}}}}},"\/attestation-keys":{"get":{"operationId":"listAttestationKeys","summary":"Public keys to verify an attestation signature (Ed25519)","responses":{"200":{"description":"Keys.","content":{"application\/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key, in the Authorization header. Never in the URL."}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}},"responses":{"Error":{"description":"An error. \"code\" is stable; \"retryable\" says whether trying again as is can work.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}},"schemas":{"ScreenshotRequest":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","description":"The public http or https page to capture."},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Load the page from this country (ISO 3166-1 alpha-2 code, see \/v1\/countries). The response reports the country actually observed. If it cannot be obtained, the request fails and is not charged. Costs 2 credits instead of 1."},"viewport":{"type":"string","pattern":"^\\d+x\\d+$","description":"Screen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height."},"viewport_width":{"type":"integer","minimum":320,"maximum":3840,"default":1440,"description":"Width of the browser window, in pixels."},"viewport_height":{"type":"integer","minimum":320,"maximum":2160,"default":900,"description":"Height of the browser window, in pixels. With full_page, the image is taller than this."},"device_scale_factor":{"type":"number","minimum":1,"maximum":3,"default":1,"description":"Pixel density. 2 gives a sharper, larger image."},"device":{"type":"string","enum":["desktop","desktop_hd","laptop","ipad","ipad_pro","ipad_mini","iphone_15","iphone_15_pro_max","iphone_se","pixel_8","galaxy_s24"],"description":"Capture as this device (screen size, pixel density, mobile browser)."},"full_page":{"type":"boolean","default":false,"description":"Capture the whole scrollable page instead of the visible part."},"selector":{"type":"string","maxLength":200,"description":"Capture only the first element matching this CSS selector."},"format":{"type":"string","enum":["png","jpeg","webp","pdf"],"default":"png","description":"File format. pdf saves the whole page as a document; it cannot be combined with selector or max_width."},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80,"description":"Quality for jpeg and webp. Ignored for png and pdf."},"color_scheme":{"type":"string","enum":["light","dark"],"description":"Ask the page for its light or dark theme."},"language":{"type":"string","default":"en-US","description":"Browser language, for example fr or fr-FR."},"timezone":{"type":"string","description":"Browser time zone, for example Europe\/Paris."},"wait_for":{"type":"string","maxLength":200,"description":"Wait until an element matching this CSS selector is visible."},"delay_ms":{"type":"integer","minimum":0,"maximum":5000,"default":0,"description":"Extra wait before the capture, in milliseconds."},"hide_selectors":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Hide every element matching these CSS selectors. In a URL, separate them with commas."},"disable_animations":{"type":"boolean","default":false,"description":"Freeze animations and transitions."},"hide_sticky_elements":{"type":"boolean","default":false,"description":"Hide headers, bars and buttons that stay fixed on screen."},"block_cookie_banners":{"type":"boolean","default":false,"description":"Removes most cookie banners. A banner the filters do not know stays in the picture."},"block_ads":{"type":"boolean","default":false,"description":"Block ads."},"block_chat_widgets":{"type":"boolean","default":false,"description":"Hide chat bubbles."},"close_popups":{"type":"boolean","default":false,"description":"Close pop-ups and newsletter overlays."},"max_width":{"type":"integer","minimum":320,"maximum":3840,"description":"Scale the image down to this width. Useful to keep it small for a vision model."},"response":{"type":"string","enum":["image","json"],"default":"image","description":"image returns the picture itself. json returns its link, the page details and the attestation."},"async":{"type":"boolean","default":false,"description":"Return an id right away instead of waiting. Read the result at \/v1\/screenshots\/{id}."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","account_blocked","insufficient_credits","rate_limited","concurrency_limit","failure_budget_exceeded","spend_limit_reached","url_not_allowed","domain_blocked","domain_busy","country_not_available","service_paused","idempotency_conflict","not_found","country_not_obtained","challenge_page","timeout","page_too_heavy","too_many_redirects","selector_not_found","wait_for_timeout","navigation_failed","image_too_large","option_unavailable","image_withheld","engine_busy","canceled","internal_error"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}}}},"Screenshot":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"image":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Short-lived link to the image."},"mime":{"type":"string"},"bytes":{"type":"integer"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"pages":{"type":["integer","null"],"description":"Number of pages, for a pdf."},"sha256":{"type":"string"},"truncated":{"type":"boolean"},"available_until":{"type":"string","format":"date-time"}}},"page":{"type":["object","null"],"properties":{"status":{"type":["integer","null"],"description":"HTTP status of the page. A page that answers 404 or 451 is still captured and charged."},"final_url":{"type":["string","null"]},"title":{"type":["string","null"]},"redirects":{"type":"array","items":{"type":"object"}}}},"country":{"type":["object","null"],"properties":{"requested":{"type":"string"},"observed":{"type":["string","null"],"description":"The country observed at capture time, never the one requested."}}},"attestation":{"type":["object","null"],"description":"Signed technical attestation, only when a country was requested. It is not legal proof."},"credits":{"type":"object","properties":{"charged":{"type":["integer","null"]},"reserved":{"type":"integer"},"remaining":{"type":["integer","null"]}}},"error":{"type":["object","null"]}}}}}}