Validate link previews from scripts, release workflows or internal QA tools. Get a JSON report of Open Graph and X card metadata, image delivery and crawler access.
Make a link preview API request
Send a GET request to /api/v1/check with the public page URL. The curl option below encodes the URL for you, including any query parameters. Bare domains are normalized to HTTPS.
The public endpoint requires no API key. Its report includes preview data and diagnostic findings. It does not read a platform's private cache or refresh an existing social post.
Check a release from CI
Save the Node.js example and run it against a published page. It exits with code 1 for blocking findings, an incomplete check, an unsupported response or an HTTP error. Warnings remain available for review. Adjust that threshold to your release policy.
const targetUrl = process.argv[2];
try {
if (!targetUrl) throw new Error("Usage: node check-preview.mjs https://example.com/page");
const endpoint = new URL("https://previewchecks.com/api/v1/check");
endpoint.searchParams.set("url", targetUrl);
const response = await fetch(endpoint, { signal: AbortSignal.timeout(20_000) });
if (!response.ok) throw new Error(`PreviewChecks API returned HTTP ${response.status}.`);
const report = await response.json();
if (
report.schemaVersion !== 2 ||
!["pass", "notice", "warning", "error"].includes(report.summary?.status) ||
!Array.isArray(report.server?.issues) ||
!Array.isArray(report.issues)
) {
throw new Error("Unsupported PreviewChecks response. Review the API contract.");
}
if (report.server.issues.some((issue) => issue.id === "probe-service-unavailable")) {
throw new Error(
"The preview check did not complete. Run it again before relying on the result.",
);
}
console.log(JSON.stringify({ summary: report.summary, issues: report.issues }, null, 2));
process.exitCode = report.summary.status === "error" ? 1 : 0;
} catch (error) {
console.error(error instanceof Error ? error.message : "The preview check could not finish.");
process.exitCode = 1;
}
Read the response
The response includes the normalized URL, final URL, overall and server-only summaries, preview card, platform checks, crawler results, metadata, image diagnostics, TLS result and ordered fixes.
HTTP 200 means a report was returned. A report can contain blocking findings. Read summary.status and issues when deciding whether to continue. schemaVersion: 2 identifies the JSON contract. The endpoint remains /api/v1/check.
If server.issues includes probe-service-unavailable, the check did not obtain a server response before its deadline. Run it again before relying on the metadata findings. HTTP 400 indicates an invalid request. HTTP 429 indicates a fair-use limit.
Version of the JSON response contract. The current version is 2.
summary.status
Highest-level result: pass, notice, warning or error.
summary.score
0-100 live-origin readiness score normalized against the checks applicable to each platform. It does not inspect platform-owned caches or an already published card.
server
Server-only score, status and issues for HTTP, redirects, crawlers, WAF, TLS and image delivery.
issues
Ordered fixes with severity, detail and suggested action.
platforms
Per-platform live-origin score, passed/total coverage and issues for Open Graph, X, Facebook, LinkedIn, Pinterest and chat previews.
readability
Optional ready/unavailable envelope from readability=1 with the selected image URL, report and separate larger-text, small-detail, size, contrast, crop and overlay results.
Limits
The public API is free for fair-use validation. It allows 20 uncached checks per minute for the same client IP and target host, and 60 uncached checks per minute for that IP across all hosts. Cached responses do not use that allowance.
Banner readability
Readability is an opt-in check for the large social banner. Normal URL checks do not run OCR. Add the query parameters below to the regular check, or use the dedicated image endpoint when you already have an image URL.
Supported profiles are X large cards, Facebook, LinkedIn, Pinterest and chat previews. The default simulation is a 320 CSS-pixel screen at DPR2 (640 physical pixels), with 17 CSS-pixel app insets on each side, leaving a 286 CSS-pixel post image (572 physical pixels). Use viewport values from 320 to 480 and independent inset_left and inset_right values. The simulated image width must stay at least 160 CSS px. fit accepts cover or contain; aspect_ratio accepts 0.1 through 10; and dpr accepts 1 through 4, with DPR2 as the documented target. DPR changes rasterization only; size verdicts remain in CSS pixels. The image must be English text in PNG, JPEG or WebP format, up to 5 MB and 4 million pixels.
The API returns separate larger-text, small-detail and uncertain-text groups, with text-size, local-contrast, crop and platform-overlay verdicts shown independently; they do not change the normal technical score. The current product policy uses 4 CSS px as a critical level, 5.5 CSS px as the minimum visible glyph height and 8 CSS px as the guide, plus 4.5:1 minimum and 7:1 recommended local contrast. These are product policy thresholds for visible glyphs, not font-size claims. DPR improves raster detail but does not make a small CSS glyph easier to read. Results cover detected English text; faint or stylized text can be missed. Uncertain OCR, crop, overlay or background measurements require manual review. A full check with readability=1 keeps every normal response field and adds a separate readability envelope for the selected platform image; X requires summary_large_image because the mini icon card is excluded.
The website can run the same analysis locally in the browser after an explicit Analyze action. The API performs the opt-in analysis on the server. Both use the existing fair-use limits: 20 uncached checks per minute for the same client IP and target host, and 60 uncached checks per minute for that IP across all hosts.