Skip to main content
POST
/
api
/
v1
/
screenshot
Screenshot webpage
curl --request POST \
  --url https://app.dumplingai.com/api/v1/screenshot \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com",
  "fullPage": true,
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "wait": 1000
}
'
{}

​
Description

This endpoint captures a screenshot of a specified URL, with options to customize the viewport, block cookie banners, set a wait time before capturing, and more.

​
Endpoint

POST https://app.dumplingai.com/api/v1/screenshot

​
Headers

  • Content-Type: application/json
  • Authorization: Bearer <API_KEY> (required)

​
Request Body

{
  "url": "string", // Required. The URL to capture.
  "fullPage": "boolean", // Optional. Whether to capture the full page. Default: false.
  "viewport": {
    // Optional. The viewport dimensions. Default: { width: 1024, height: 1024 }
    "width": "number",
    "height": "number"
  },
  "clipRectangle": {
    // Optional. The area of the screen to clip. fullPage must be false to use this. Defaults to viewport.
    "top": "number",
    "left": "number",
    "width": "number",
    "height": "number"
  },
  "blockCookieBanners": "boolean", // Optional. Whether to block cookie banners. Default: true.
  "wait": "number", // Optional. Time to wait before capture in ms. Max: 5000. Default: 0.
  "autoScroll": "boolean" // Optional. Whether to automatically scroll the page (e.g. for lazy loaded images). Default: false.
}

​
Responses

​
Success (200)

Returns the screenshot data and related information. 
{
  "screenshotUrl": "string" // URL of the captured screenshot
}
  • Content-Type: application/json
  • X-RateLimit-Limit: The rate limit for the user.
  • X-RateLimit-Remaining: The remaining number of requests for the user.

​
Bad Request (400)

Returned if the request is invalid. 
{
  "error": "Error message describing the issue"
}

​
Internal Server Error (500)

Returned if there’s an error during the screenshot process. 
{
  "error": "Failed to screenshot: [error message]"
}

​
Example Request

curl -X POST https://app.dumplingai.com/api/v1/screenshot \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "url": "https://example.com",
  "fullPage": true,
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "blockCookieBanners": true,
  "wait": 1000,
  "autoScroll": true
}'

​
Example Response

{
  "screenshotUrl": "https://storage.example.com/screenshots/abcdef123456.png"
}

​
Notes

  • The viewport width must be less than or equal to 3840 pixels, and the height must be less than or equal to 10240 pixels.
  • The maximum wait time is 5000 milliseconds (5 seconds).
  • Credit usage:
    • Base cost: 20 credits
    • Additional 10 credits if autoScroll is true
    • Additional 10 credits if wait is set (any non-zero value)
  • If the URL doesn’t include a protocol, https:// will be used by default.
  • The clipRectangle option can only be used when fullPage is set to false.
  • Usage is recorded with detailed parameters for each request.
  • Events may be logged to PostHog for analytics purposes if enabled.

​
Rate Limiting

Rate limit headers (X-RateLimit-Limit and X-RateLimit-Remaining) are included in the response to indicate the user’s current rate limit status.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Options for capturing a screenshot of a webpage.

​
url
string<uri>
required

Fully-qualified URL to capture.

​
fullPage
boolean
default:false

Capture the entire scrollable page.

​
viewport
object

Browser viewport size in pixels.

​
clipRectangle
object

Clipping rectangle when capturing a partial screenshot.

​
blockCookieBanners
boolean
default:true

Attempt to hide cookie banners before capturing the screenshot.

​
wait
integer
default:0

Delay in milliseconds before capturing, allowing the page to finish loading.

Required range: 0 <= x <= 5000
​
autoScroll
boolean
default:false

Scroll the page to trigger lazy-loaded content before capturing.

​
requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

Screenshot data returned.

Flexible JSON structure; fields differ per endpoint.