Hi

{ "openapi": "3.0.0", "info": { "title": "Open Graph & Twitter Card Validator API: Link Preview Tag Checker", "description": "One GET, one graded JSON report: a headless Open Graph and Twitter Card validator for CI gates, SEO audits and publishing tools. Give it a page URL (or HTML) and get a JSON report on the page's social-sharing tags: required and recommended Open Graph properties, Twitter/X card type and image, title and description lengths, og:url versus canonical mismatches, and - by default - one small ranged request to the image (falling back to twitter:image if there is no og:image) to check that it responds, reports an image content type and a size within platform limits. Includes a best-guess preview object (Open Graph first, then Twitter, then the page's own tags); each platform picks its own fields and this does not reproduce what a platform crawler sees. This is a validator, not a link-preview scraper. Not affiliated with Meta, Facebook, X or LinkedIn.\n\n/v1/check GETs the page (up to 5 redirects, first 1 MB of HTML) and reads the meta tags in the served HTML. /v1/validate checks HTML you send in, offline with no outbound request (the image is not requested).\n\nIssue codes: errors such as og_title_missing, og_image_missing, og_image_relative, og_url_invalid, twitter_card_invalid, twitter_image_missing, og_image_unreachable, og_image_not_image, og_image_too_large and no_social_tags; warnings such as og_type_missing, og_url_missing, og_description_missing, twitter_card_missing, og_url_canonical_mismatch, duplicate_og_tags, og_image_too_small, og_image_not_https, og_image_format_unsupported (SVG) and og_image_too_large_for_x; infos such as og_image_size_missing, og_title_long, og_description_long, image_alt_missing and twitter_site_missing.\n\nLimits: only tags present in the served HTML are read (no JavaScript rendering); platforms cache previews on their side and this report does not refresh them; size rules reflect public platform guidance (Facebook 8 MB and 200x200 minimum, X 5 MB) and may change. The image request is a single 1-byte ranged GET (up to 3 redirects); type and size come from response headers, and the size check is skipped if the host does not report a size. Image dimensions come from the og:image:width/height tags, not from the file. Image hosts that block automated or datacenter requests can produce og_image_unreachable. Severity reflects practical impact on previews, not strict protocol compliance. Use probe=0 to skip the image request. If a site answers HTTP 4xx/5xx the grade is unchecked; a page with no og:/twitter: tags returns grade no_social_tags. /v1/check results are cached for 6 hours per URL; add fresh=1 to bypass. Private-network page URLs are rejected; a private-network image URL is not requested and is flagged as og_image_not_checked. One error scores 75 (grade C), so gate on summary.errors; unchecked and no_social_tags are not passes.", "version": "1.0.0", "x-category": "Data" }, "servers": [ { "url": "https://og-validator.glowhalo.org" } ], "paths": { "/v1/check": { "get": { "summary": "Validate the Open Graph and Twitter Card tags of a URL", "description": "GETs the page (up to 5 redirects, first 1 MB) and, unless probe=0, requests the og:image once. Cached 6 hours; pass fresh=1 to bypass. A scheme-less value such as example.com is treated as https.", "operationId": "checkSocialTags", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Page to inspect. Aliases u, uri, link, target, site, website, domain and host are also accepted (case-insensitive).", "schema": { "type": "string" }, "example": "https://github.com" }, { "name": "probe", "in": "query", "required": false, "description": "Set to 0 to skip the og:image request.", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "fresh", "in": "query", "required": false, "description": "Set to 1 to bypass the result cache.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Validation report. found is false and grade is no_social_tags when the page has no og:/twitter: tags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grade": { "type": "string", "description": "A+ to F derived from score (A+ 97+, A 90+, B 80+, C 70+, D 60+, F below). no_social_tags: the HTML has no og:/twitter: meta tags. unchecked: HTTP 4xx/5xx." }, "score": { "type": "number", "nullable": true, "description": "100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total (minimum 0)." }, "summary": { "type": "object", "properties": { "errors": { "type": "integer" }, "warnings": { "type": "integer" }, "infos": { "type": "integer" } } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "cached": { "type": "boolean" }, "checkedAt": { "type": "string" }, "note": { "type": "string" }, "url": { "type": "string" }, "finalUrl": { "type": "string" }, "statusCode": { "type": "integer" }, "found": { "type": "boolean", "nullable": true }, "preview": { "type": "object", "description": "What a link card would most likely show (Open Graph first, then Twitter, then the page's own tags).", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "url": { "type": "string" }, "siteName": { "type": "string" }, "type": { "type": "string" }, "twitterCard": { "type": "string" }, "locale": { "type": "string" } } }, "tags": { "type": "object", "description": "Raw tags found: openGraph, twitter, article, canonical, title." }, "imageCheck": { "type": "object", "nullable": true, "description": "Result of the og:image request (null with probe=0 or in /v1/validate).", "properties": { "url": { "type": "string" }, "status": { "type": "integer", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "sizeBytes": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Bad input: missing_url, invalid_url, credentials_in_url, unsupported_protocol, forbidden_host (private network), url_too_long.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } }, "502": { "description": "The target could not be fetched (fetch_failed, resolve_failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } }, "504": { "description": "The target did not answer within 10 seconds (timeout).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } } } } }, "/v1/validate": { "post": { "summary": "Validate HTML you send in", "description": "Offline validation, no outbound request. Send the page HTML in html; url is optional and only resolves relative URLs. The body is limited to 512 KB.", "operationId": "validateSocialTags", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "Page HTML containing the meta tags.", "example": "Hi" }, "url": { "type": "string", "description": "Optional page URL used to resolve relative URLs.", "example": "https://example.com/page" } } }, "example": { "html": "Hi", "url": "https://example.com/page" } } } }, "responses": { "200": { "description": "Validation report for the supplied HTML.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grade": { "type": "string", "description": "A+ to F derived from score (A+ 97+, A 90+, B 80+, C 70+, D 60+, F below). no_social_tags: the HTML has no og:/twitter: meta tags. unchecked: HTTP 4xx/5xx." }, "score": { "type": "number", "nullable": true, "description": "100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total (minimum 0)." }, "summary": { "type": "object", "properties": { "errors": { "type": "integer" }, "warnings": { "type": "integer" }, "infos": { "type": "integer" } } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "cached": { "type": "boolean" }, "checkedAt": { "type": "string" }, "note": { "type": "string" }, "url": { "type": "string" }, "finalUrl": { "type": "string" }, "statusCode": { "type": "integer" }, "found": { "type": "boolean", "nullable": true }, "preview": { "type": "object", "description": "What a link card would most likely show (Open Graph first, then Twitter, then the page's own tags).", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "url": { "type": "string" }, "siteName": { "type": "string" }, "type": { "type": "string" }, "twitterCard": { "type": "string" }, "locale": { "type": "string" } } }, "tags": { "type": "object", "description": "Raw tags found: openGraph, twitter, article, canonical, title." }, "imageCheck": { "type": "object", "nullable": true, "description": "Result of the og:image request (null with probe=0 or in /v1/validate).", "properties": { "url": { "type": "string" }, "status": { "type": "integer", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "sizeBytes": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Bad input: invalid_json, invalid_body, missing_html, invalid_url.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } }, "413": { "description": "payload_too_large: the body exceeds 512 KB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } } } } } } }