Guide

Website Archival for Compliance & Legal Records

How to build a website capture record your compliance or legal team can work with: what to capture, what metadata to keep, how to verify integrity end to end, and where a screenshot API's job ends.

Asad AliJanuary 18, 202610 min read

Web pages change without notice. Terms of service get revised, pricing pages are rewritten, a claim on a landing page disappears. When someone later asks "what did this page say on 3 March?", the answer has to come from a record you made at the time.

This guide shows how to build that record with a screenshot API: what to capture, which metadata to keep, how to check integrity from the moment of capture to the moment of export, and which parts of the job belong to your own storage and processes.

This is an engineering guide, not legal advice. Recordkeeping and evidence requirements differ by jurisdiction, industry and purpose. Before you rely on any capture process for litigation, regulatory recordkeeping or audit, confirm the requirements with your counsel or compliance team. Nothing in this guide, or in a screenshot API, makes a capture "compliant" or "admissible" on its own.

What a screenshot records, and what it doesn't

A screenshot is a record of how a page rendered in one browser, at one viewport, at one moment. That's often exactly what's needed: proof of what a visitor would have seen.

It is not a forensic copy of the website. In particular, it does not capture:

  • Server-side state: what the server stored, logged, or would have shown to a different visitor.
  • Personalized or geo-dependent content: the capture shows what the capture browser was served, which can differ from what a logged-in user or a visitor in another country saw.
  • Interactive states: collapsed sections, tabs, hover menus and multi-step flows stay as they rendered on load unless you change them before capture.
  • Media and live data: in Screenshotly, video/audio and WebSocket requests are not loaded during capture.

A replayable web archive is a different artifact. Tools that crawl a site and write WARC files (the format used by web archives such as the Wayback Machine) preserve the HTTP responses themselves. Screenshotly does not produce WARC files. If you need replay, run a WARC crawler alongside screenshot capture rather than instead of it.

Choosing output formats

Output Request Plan What it gives you
Full-page PNG format: "png", fullPage: true Free Lossless image of the whole scrollable page as rendered on screen. The primary record.
Rendered HTML format: "html" Basic The page's DOM after scripts ran, serialized as HTML. Searchable text without OCR. External CSS, images and fonts are referenced by URL, not embedded, so it won't re-render the same way later.
PDF format: "pdf" Basic Chromium print rendering, fixed A4 with 1 cm margins, backgrounds included. Print stylesheets apply, so it can differ from the screen. Not PDF/A.

For most archival use, keep the PNG as the record of what was displayed and add the rendered HTML as a searchable companion. Avoid JPEG and WebP for the primary record: both are re-encoded with lossy compression.

Two request settings to be careful with:

  • Leave cache off (it's off by default). With caching enabled, the API can return an earlier capture of the same request, which defeats the point of a dated record.
  • Record any overlay removal. aiRemoval and hideSelectors change what's in the image. For evidence of what a visitor saw, leave them off, or record exactly what was hidden in the sidecar.

A capture record with metadata

The function below captures one URL, hashes the bytes on arrival, and returns the image together with a JSON sidecar describing the capture. It uses the synchronous endpoint, which returns the file in the response body.

// archive-capture.mjs (Node.js 18+)
import { createHash, randomUUID } from 'node:crypto';

const API_URL = 'https://screenshotly.app/api/screenshot';
const API_KEY = process.env.SCREENSHOTLY_API_KEY;

export async function captureRecord(url, { purpose, requestedBy, format = 'png' }) {
  const request = {
    url,
    format,
    fullPage: true,
    width: 1440,
    height: 900,
    timezone: 'UTC',
    waitForNetworkIdle: true,
  };

  const requestedAt = new Date().toISOString();
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify(request),
  });
  const receivedAt = new Date().toISOString();

  if (!response.ok) {
    throw new Error(`Capture failed: ${response.status} ${await response.text()}`);
  }

  const bytes = Buffer.from(await response.arrayBuffer());
  const sidecar = {
    recordId: randomUUID(),
    url,
    purpose,
    requestedBy,
    request,
    requestedAt,
    receivedAt,
    response: {
      status: response.status,
      contentType: response.headers.get('content-type'),
      size: bytes.length,
      captureDurationMs: Number(response.headers.get('x-screenshot-duration')),
    },
    sha256: createHash('sha256').update(bytes).digest('hex'),
    tool: 'Screenshotly API (headless Chromium)',
  };

  return { bytes, sidecar };
}

Notes on the fields:

  • requestedAt and receivedAt come from your clock. The rendering happened between the two. If the timing needs to stand up independently, see "Proving when" below.
  • request is stored verbatim. Viewport, wait settings and format all affect the image, so anyone reviewing the record later can see exactly how it was made.
  • The hash is computed before the bytes touch disk. Any later copy can be checked against it.

To keep a searchable companion (Basic plan or higher), call the same function with format: 'html' and store both records under one folder. Each call is a separate render, so the two can differ slightly if the page changes between them; the sidecar timestamps show that.

Larger runs: async jobs with a server-side checksum

For scheduled runs over many URLs, the async jobs API (Basic plan or higher) is a better fit than holding a connection open per capture. Jobs are retried by the service, and each completed job records a SHA-256 checksum of the stored file. That gives you a second, independent hash to compare against.

// archive-jobs.mjs (Node.js 18+)
import { createHash } from 'node:crypto';

const BASE = 'https://screenshotly.app';
const headers = {
  'x-api-key': process.env.SCREENSHOTLY_API_KEY,
  'Content-Type': 'application/json',
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function submitCapture(url, idempotencyKey) {
  const response = await fetch(`${BASE}/api/jobs`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify({ url, format: 'png', fullPage: true, width: 1440, height: 900, waitForNetworkIdle: true }),
  });
  if (!response.ok) throw new Error(`Submit failed: ${response.status} ${await response.text()}`);
  return response.json(); // { id, status, replayed, statusUrl }
}

export async function collectCapture(jobId, { pollMs = 5000, maxPolls = 120 } = {}) {
  for (let i = 0; i < maxPolls; i++) {
    const job = await (await fetch(`${BASE}/api/jobs/${jobId}`, { headers })).json();
    if (job.status === 'SUCCEEDED') {
      // resultUrl is a short-lived signed URL; don't send your API key to it
      const bytes = Buffer.from(await (await fetch(job.resultUrl)).arrayBuffer());
      const sha256 = createHash('sha256').update(bytes).digest('hex');
      if (sha256 !== job.asset.checksum) {
        throw new Error(`Checksum mismatch for job ${jobId}`);
      }
      return { bytes, sha256, job };
    }
    if (job.status === 'FAILED' || job.status === 'CANCELED') {
      throw new Error(`Job ${jobId} ${job.status}: ${job.errorMessage ?? 'no message'}`);
    }
    await sleep(pollMs);
  }
  throw new Error(`Job ${jobId} did not finish in time`);
}

Things to know about the jobs API:

  • Use a deterministic Idempotency-Key, such as <url-hash>-<schedule-date>. If your scheduler retries a submit, the API returns the original job instead of creating a duplicate.
  • Store the job's id, createdAt, completedAt and asset.checksum in your sidecar. They are the service's own record of the capture.
  • The download link expires quickly. Read the job again to get a fresh resultUrl.
  • Screenshotly is not your archive. Stored results are deleted after the account's retention period, which you can set between 1 and 30 days. Copy every file and sidecar into your own storage as soon as the job completes.
  • Batches: on Growth and Scale, POST /api/jobs/batch queues up to 20 captures in one request.

The full contract, including webhooks for completion instead of polling, is in the async jobs reference.

Storing records so they can't be quietly changed

The capture is only as trustworthy as the place you keep it. A practical layout:

archive/
  2026/11/13/
    <recordId>/
      page.png
      page.html          (optional companion)
      record.json        (sidecar)
      record.tsr         (optional RFC 3161 timestamp token)

Then make the storage enforce what your policy says:

  • Write-once retention. Amazon S3 Object Lock and Azure immutable blob storage can prevent objects from being overwritten or deleted until a retention date passes. Read the provider documentation on retention modes and legal holds carefully: which mode you choose determines whether anyone, including administrators, can shorten retention.
  • Hashes kept separately. Write each sha256 to a log or database that the archive's writers can't edit, so a changed file can't be "fixed" by also changing its sidecar.
  • Access logging. Record who read or exported each record, and when. Cloud storage access logs or your application's audit log both work, as long as they are retained at least as long as the records.

Proving when, and verifying later

Your own timestamps show when your system says it captured a page. If a record may be challenged, an independent timestamp helps: an RFC 3161 timestamping authority signs a hash together with the time it received it. You send the record's SHA-256, keep the returned token next to the record, and anyone can later check that the hash existed at that time. Choose an authority your legal team is comfortable with.

Verification is then a straightforward re-hash:

// verify-record.mjs (Node.js 18+)
import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import path from 'node:path';

export async function verifyRecord(dir, expectedSha256) {
  const bytes = await readFile(path.join(dir, 'page.png'));
  const actual = createHash('sha256').update(bytes).digest('hex');
  return { ok: actual === expectedSha256, actual, expected: expectedSha256 };
}

Pass expectedSha256 from your separate hash log, not from the sidecar in the same folder. Run verification on a schedule and on every export, and log the result.

Scheduling and coverage

The API captures what you ask for, when you ask; the schedule and the URL list are yours. Common patterns:

  • Change-triggered capture: capture a terms or pricing page whenever a lightweight check (an ETag, a text hash of the rendered HTML) shows it changed, plus a periodic capture regardless.
  • Fixed schedule: daily or weekly captures of a defined URL list, submitted as async jobs with date-based idempotency keys.
  • On demand: a form or chat command your legal or compliance team can use to capture a URL right now, which writes the same record and sidecar.

For scheduling, change detection and alerting patterns, see the website monitoring guide. For PDF-specific output, see the HTML to PDF generation guide.

Limits to plan around

  • Public pages only, by default. Private and internal network addresses are rejected. Logged-in pages need session cookies or headers (Basic plan or higher), and capturing a page behind someone else's login raises its own legal questions.
  • One browser, one viewport per capture. If mobile and desktop layouts differ in content, capture both and record which is which.
  • Bot protection. Some sites block or serve different content to automated browsers. Record failures in your log; a missing capture is information too.
  • Quota and rate limits. Every capture counts against your plan. Size the URL list and schedule against the limits on the pricing page.

Summary

A defensible web capture is mostly about process, not pixels:

  1. Capture a lossless, full-page image with the request parameters recorded.
  2. Hash the bytes on arrival and compare against the service's checksum when using jobs.
  3. Copy everything into storage you control, with write-once retention and a separate hash log.
  4. Add independent timestamps where the timing may be disputed.
  5. Re-verify on a schedule and on every export, and confirm the overall process with your legal or compliance team.

Building a capture archive?

Create a free account → to test the capture and sidecar flow with 100 free captures. The API reference lists every request field.

compliance
legal
archival
enterprise
documentation

About the Author

Asad Ali

Asad Ali

CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.

Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients

Frequently Asked Questions

What metadata should I keep with each capture?

At minimum: the exact URL requested, the full request parameters (viewport, device, wait settings), the UTC time you sent the request and received the response, a SHA-256 hash of the returned bytes, the response's content type and size, and who or what triggered the capture and why. Store it as a JSON sidecar next to the file. Whether that is sufficient for a particular legal or regulatory purpose is a question for your counsel or compliance team, not for the capture tool.

Is the PDF output suitable for long-term retention?

Screenshotly's PDF output is Chromium's print rendering of the page on fixed A4 pages with 1 cm margins. It is not produced as PDF/A, and print stylesheets can make it look different from the screen. If your retention policy names a specific format, convert or validate the file with a dedicated tool, and keep a full-page PNG alongside it as the record of what the screen showed.

How do I make captures tamper-evident?

Hash the bytes as soon as you receive them, store the hash in a separate system from the file, and write the file to storage that enforces write-once retention, such as Amazon S3 Object Lock or Azure immutable blob storage. Re-hash periodically and on every export. For independent proof of when a hash existed, you can obtain an RFC 3161 timestamp from a trusted timestamping authority. None of these steps happen inside the screenshot API; they are part of your archive.

Ready to capture your first screenshot?

Get started with 100 free screenshots. No credit card required.

Related Articles