Social Media Preview

Input Contract

Provide url as an http or https URL up to 2048 characters. If no scheme is supplied, https is assumed. The checker follows up to five redirects. Private or reserved page targets and non-standard ports are blocked.

Output Contract

Returns a ready, partial, missing, or unavailable status; normalized and final URLs; redirect and HTTP status details; resolved title, description, site name, content type, canonical URL, Twitter card type, image URL, dimensions, fetch status, response content type, accessibility, and safety; boolean checks; warnings; and errors. Open Graph values take priority, followed by Twitter Card and ordinary HTML metadata.

Errors

Empty or invalid URL, unsupported scheme, embedded credentials, unsupported port, DNS resolution failure, private or reserved network target, request failure, invalid redirect, or redirect loop. Missing preview fields are returned as warnings with HTTP 200.

Auth and Limits

Anonymous JSON API for initial rollout. Use the /api/v1 endpoint for agents; browser form submissions remain protected by CSRF and reCAPTCHA.

JSON API uses the standard API throttle. Each request may perform up to five outbound page requests and up to three requests while validating the preview image.

Examples

Requests

GET /api/v1/social-preview?url=https://example.com/article

POST /api/v1/social-preview {"url":"https://example.com/article"}

Responses

{"skill":"socialpreview","status":"ready","has_preview":true,"title":"Example article","description":"An example summary.","image":{"url":"https://example.com/social.jpg","width":1200,"height":630,"status_code":200,"content_type":"image/jpeg","accessible":true,"display_safe":true},"checks":{"has_open_graph":true,"has_title":true,"has_description":true,"has_image":true,"image_is_accessible":true}}