About this endpoint
What it does
Generates preview metadata for a URL. The request body supplies the URL and optional fetch/extraction settings, and the response returns either preview fields for a normal URL or threat information when the URL is detected as malicious.
Request Body
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| url | String | Yes | The URL to generate a preview for. Protocol is optional — http:// is prepended if absent. |
| user_agent | String | No | Custom User-Agent header sent when fetching the URL. |
| secure_mode | Boolean | No | When true, the URL is checked against the malicious-URL database before fetching. Default: true. |
| accept_language | String | No | Custom Accept-Language header sent when fetching the URL. |
| allow_redirects | Boolean | No | Whether to follow HTTP redirects when fetching the URL. Default: false. |
| images_property_type | ENUM | No | Preferred image meta-tag property to extract. Allowed values: og, twitter. Default: og. |
Response
Returns a JSON object with a required data field. data is an object that contains either normal preview metadata (url, title, images, videos, favicons, siteName, mediaType, contentType, description, and optionally reported_malicious) or malicious-URL information (url, threat, reported_malicious).
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| data | Object | Yes | Preview result object. It follows one of two shapes: normal response metadata or malicious URL detection details. |
Notes
secure_mode defaults to true, which means the URL is checked against the malicious-URL database before fetching. In the normal preview shape, reported_malicious is present only when secure_mode is true, and it is always false for a clean URL.