​
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: 2 credits
    • Additional 1 credit if autoScroll is true
    • Additional 1 credit 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.