Versionista API: How to Retrieve Website Change Data

Short answer: Versionista’s public API documentation does not describe an endpoint for retrieving stored snapshots or change diffs. It documents two experimental endpoints: GET /test to check an API key and POST /watch to add a URL to monitoring. To review changes, Versionista documents comparison-viewer links, summary emails with optional spreadsheet attachments, and instant email alerts. If you need change records in an automated pipeline, confirm a supported history endpoint and its schema with Versionista before building against one.

This guide shows the documented API calls, explains what they do and do not provide, and lays out practical options for collecting change data. The distinction matters: adding a page to monitoring is not the same as retrieving its stored history.

1. What the documented API can do

Versionista describes its API as a new, experimental feature that may change. API keys are managed in the account Settings page. Requests use the X-Api-Key header. The public documentation describes these pilot endpoints:

Method and path	Purpose	What it does not establish
`GET /test`	Check whether the API key works.	It does not retrieve monitored pages or change records.
`POST /watch`	Add a URL for Versionista to monitor.	It does not document a response containing historical snapshots or diffs.

Base URL: https://api.versionista.com. The official API documentation warns that the feature is experimental and subject to change: Versionista API documentation.

The public endpoint descriptions reviewed do not specify a history or diff endpoint, change-record response schema, pagination, or rate limits. That is a limit of the documented interface; it is not proof that no private, account-specific, or subsequently added endpoint exists.

2. Set up and verify API access

Sign in to Versionista and locate the API key in account Settings.
Keep the key in a secret manager or environment variable. Do not commit it to source control or put it in client-side code.
Call /test with the key in the X-Api-Key header.
If the verification call fails, check the key and account access before trying to add a page.

These examples use the documented API host and authentication header. They intentionally print the response without assuming an undocumented response schema.

cURL: verify the key

export VERSIONISTA_API_KEY='YOUR_API_KEY'
curl --fail-with-body --silent --show-error \
  'https://api.versionista.com/test' \
  -H "X-Api-Key: ${VERSIONISTA_API_KEY}"

Python: verify the key

import os
import requests

api_key = os.environ["VERSIONISTA_API_KEY"]
response = requests.get(
    "https://api.versionista.com/test",
    headers={"X-Api-Key": api_key},
    timeout=30,
)
print("HTTP", response.status_code)
print(response.text)
response.raise_for_status()

Node.js: verify the key

const apiKey = process.env.VERSIONISTA_API_KEY;
if (!apiKey) throw new Error("Set VERSIONISTA_API_KEY first");

const response = await fetch("https://api.versionista.com/test", {
  method: "GET",
  headers: { "X-Api-Key": apiKey },
  signal: AbortSignal.timeout(30_000),
});
const body = await response.text();
console.log("HTTP", response.status, body);
if (!response.ok) throw new Error(`Versionista returned HTTP ${response.status}`);

3. Add a URL to monitoring

POST /watch accepts a JSON body with required string field url. It also accepts redirect and new_site, both booleans that default to false. Versionista recommends redirect: true to attempt to follow redirects when determining the hostname, port, and protocol to track. Set new_site: true to place the URL in a new site instead of filing it under an existing site. The documented response indicates an error or provides a page-view URL.

cURL: add a URL

curl --fail-with-body --silent --show-error \
  'https://api.versionista.com/watch' \
  -X POST \
  -H "X-Api-Key: ${VERSIONISTA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com/pricing","redirect":true,"new_site":false}'

Python: add a URL

import os
import requests

response = requests.post(
    "https://api.versionista.com/watch",
    headers={
        "X-Api-Key": os.environ["VERSIONISTA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com/pricing",
        "redirect": True,
        "new_site": False,
    },
    timeout=30,
)
print("HTTP", response.status_code)
print(response.text)
response.raise_for_status()

Node.js: add a URL

const apiKey = process.env.VERSIONISTA_API_KEY;
if (!apiKey) throw new Error("Set VERSIONISTA_API_KEY first");

const response = await fetch("https://api.versionista.com/watch", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    redirect: true,
    new_site: false,
  }),
  signal: AbortSignal.timeout(30_000),
});
const body = await response.text();
console.log("HTTP", response.status, body);
if (!response.ok) throw new Error(`Versionista returned HTTP ${response.status}`);

Replace the example URL with the page you want monitored. Use a fully qualified URL including its scheme, such as https://. The API documentation does not describe bulk submission, idempotency, duplicate handling, or request limits, so check current documentation or support guidance if you plan to add many URLs.

4. How to review changes with the documented product workflows

Versionista’s tutorial describes ways to receive and inspect changes through its interface and email workflows:

Comparison viewers: summary emails link to viewers for comparing captured versions.
Summary emails: the tutorial says summaries are sent daily by default and suppressed when no changes were detected in the previous 24 hours. Schedules can be configured.
Spreadsheet attachments: summaries can optionally include a spreadsheet of detected changes.
Instant alerts: these can include changed content in the email body, are enabled per page, and are off by default. The tutorial describes options such as text, text plus HTML, or filtered changes.

These are documented reporting options, not evidence that equivalent records are available through the API. See Versionista’s email alert tutorial for the described settings.

Choose the workflow that fits the need

Need	Practical next step
A person needs to inspect a change	Use the comparison-viewer link in a summary email.
A team needs a periodic change report	Configure summary email timing and consider the spreadsheet attachment.
A person needs prompt notification for one page	Enable an instant alert for that page and select the desired content format.
A program needs structured historical records	Ask Versionista to confirm a supported API endpoint, schema, pagination, and limits. Do not treat `/watch` as a retrieval endpoint.

5. If you need automated website change data

Before implementing ingestion, ask Versionista support or check the current official documentation for all of the following:

Is there a supported endpoint to list captures, snapshots, detected changes, or diffs?
What are the authentication requirements and permissions?
What fields and formats are returned, and can the response include a comparison URL or content?
How does pagination work, and how should a client resume after a partial failure?
Are there documented request limits, retention rules, and error codes?
Can change notifications be delivered through a supported webhook or export?

Build an importer only after those details are confirmed. Store a stable cursor or last-seen timestamp if the confirmed API supports one, make ingestion safe to retry, and record the source page and retrieval time. Those are general integration safeguards; the public Versionista API documentation reviewed here does not establish that such cursor or history fields exist.

6. Capture a current page yourself when you need a visual baseline

If the immediate need is a visual record of a page now, a browser automation tool or screenshot API can capture the current rendering. A screenshot is a point-in-time visual artifact; by itself it does not provide Versionista’s detected changes, its historical captures, or a semantic diff. To create your own baseline workflow, save captures over time and compare them with an image-diff tool or inspect them manually. Make sure you are allowed to capture the target page and avoid storing sensitive content.

For a list of screenshot APIs or tools to try, ScreenshotNeo is the first alternative to consider: cookie banners, popups, and chat widgets are removed before capture, and only clean shots are billed.

Or skip the browser setup

For a current page capture, ScreenshotNeo accepts a URL in one GET request and returns an image or PDF. This does not retrieve Versionista history or detected diffs. See the ScreenshotNeo API documentation for the available parameters.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot.
Bot checks, blank pages, and failed loads are never billed.
An MCP server lets AI agents take screenshots.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.

7. Reliability, performance, and cost considerations

Versionista API integration

Reliability: the API is explicitly experimental and may change. Keep calls isolated behind a small client module, handle non-success HTTP responses, and avoid depending on response fields beyond what the current documentation confirms.
Retries: a failed verification GET can generally be retried after checking connectivity and credentials. Avoid blindly retrying POST /watch: the documentation does not define idempotency or duplicate behavior, so a retry could have an unknown effect.
Performance: no public rate limits or latency guarantees are specified in the reviewed API documentation. Keep request timeouts, use modest request volume, and ask Versionista for limits before scaling.
Cost: the research material does not establish API pricing or the cost of monitoring. Confirm current account pricing and plan allowances directly with Versionista.

ScreenshotNeo capture workflow

For repeated captures, caching is available with a TTL you choose; this can avoid unnecessary repeat work when a fresh render is not needed.
Async jobs with signed webhooks and bulk capture of up to 100 URLs per call are available for larger capture workloads.
ScreenshotNeo pricing: Free includes 1,000 shots/month with no card; Starter is $5 for 3,000; Growth $15 for 15,000; Pro $39 for 60,000; Scale $99 for 250,000; Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan.

8. Troubleshooting

Symptom	Likely cause	What to do
`/test` returns an authorization error	The key is missing, invalid, malformed, or not sent in the expected header.	Check the account Settings page and send the key as `X-Api-Key`. Do not include the word `Bearer` unless current documentation instructs you to.
`/watch` rejects the request	The JSON is malformed, `url` is missing or not a string, or the URL is not acceptable.	Send valid JSON with a fully qualified URL. Inspect the response body for the documented error indication.
The tracked host differs from the submitted URL	The URL redirects and the request used the default `redirect: false`.	Try `redirect: true`, which Versionista recommends for following redirects when determining the host, port, and protocol to track.
The page is filed under an unexpected site	The request used the default site assignment or an existing grouping affected the result.	Use `new_site: true` if you want a new site, then review the returned page-view URL.
You cannot find an API response with past changes	The public API documentation reviewed describes adding a watch, not retrieving history.	Use documented comparison and email reporting workflows, or ask Versionista to confirm a supported history API before automating retrieval.
A request times out or fails at the network layer	Connectivity, DNS, TLS, or a transient service issue may be involved.	Log the HTTP status and response body when available, use a finite timeout, and retry cautiously. Do not automatically repeat `POST /watch` until duplicate behavior is known.

9. Frequently asked questions

Does `POST /watch` return a change diff?

The documented description says it indicates an error or provides a page-view URL. It does not describe returning a diff.

Can I use the summary spreadsheet as an API export?

The tutorial documents an optional email attachment. It does not document an API for downloading that attachment or polling its contents.

Are Versionista’s email schedules and instant alerts API settings?

The tutorial presents them as product email settings. The reviewed API documentation does not describe corresponding API endpoints.

Should I build against an undocumented history endpoint?

No. Confirm that it is supported and obtain its current schema and limits from Versionista first, especially because the documented API is experimental.

Can a screenshot replace change monitoring?

No. A screenshot records a rendering at one moment. Monitoring and diffing require repeated observations and a comparison process; a screenshot API alone does not supply Versionista’s history.

Sources

Versionista API documentation — experimental API warning, authentication, and pilot endpoint descriptions.
Versionista email alert tutorial — comparison links, summary email options, attachments, and instant alerts.