Endpoints
Screenshot
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 /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 whenfullPage
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.