SavePage
·SavePage Team

SavePage.io v2 API: What Changed and Why

announcementapiv2

We are releasing version 2 of the SavePage.io API. This update introduces several new features, improves performance, and makes a few breaking changes to clean up the API design.

What is new

WebP output (all plans)

WebP is now available on all plans, including Free. Previously it was Pro-only. Use format=webp for 25-35% smaller files than JPEG at equivalent quality.

Element targeting improvements

The selector parameter now supports complex CSS selectors including pseudo-classes and combinators. You can target :first-of-type, :nth-child(), and descendant selectors.

New: the selectorAll parameter captures all matching elements as separate images, returned as an array in the response.

Webhook callbacks

Pro and Enterprise plans can now use asynchronous capture with webhooks. Submit a capture request with a callback_url and receive the result as a POST to your server when the capture completes.

PDF output

Pro plans can now request PDF output in addition to image formats. Use format=pdf for a PDF rendering of the page.

Custom HTTP headers

Enterprise plans can pass custom HTTP headers that are included when loading the target page. This enables capturing pages behind basic authentication or pages that require specific headers.

Breaking changes

Base URL change

The base URL has changed from /v1/ to /v2/. The v1 endpoint continues to work but is deprecated and will be removed in 12 months.

# Old
https://api.savepage.io/v1/?url=...

# New
https://api.savepage.io/v2/?url=...

Response format

The response JSON structure has changed:

// v1 response
{
  "status": "success",
  "image": "https://cdn.savepage.io/captures/abc123.png",
  "width": 1440,
  "height": 900
}

// v2 response
{
  "status": "success",
  "data": {
    "image_url": "https://cdn.savepage.io/captures/abc123.png",
    "viewport": {"width": 1440, "height": 900},
    "output": {"format": "png", "size_bytes": 847291},
    "timing": {"queue_ms": 120, "render_ms": 2340, "total_ms": 2460}
  },
  "meta": {
    "capture_id": "cap_abc123",
    "api_version": "v2",
    "captured_at": "2026-01-08T12:00:00Z"
  }
}

Key changes:

  • Image URL moved from image to data.image_url
  • Viewport dimensions grouped under data.viewport
  • New timing information in data.timing
  • Metadata in meta object

Error format

Error responses now include a code field with a machine-readable error code:

{
  "status": "error",
  "error": {
    "code": "INVALID_URL",
    "message": "The url parameter must be a valid HTTP or HTTPS URL",
    "param": "url"
  }
}

Migration guide

  1. Update your base URL from /v1/ to /v2/
  2. Update response parsing to use the new nested structure
  3. Update error handling to use the new error format
  4. Update any webhook integrations to use the new callback format

The v1 API will continue to work until January 2027. We recommend migrating to v2 as soon as practical to take advantage of the new features and improved error handling.

Performance improvements

The v2 infrastructure includes a redesigned render queue that reduces average capture time by 30%. Queue waiting time is now included in the response (data.timing.queue_ms) so you can see how much of the total time was spent waiting vs. rendering.

All posts