Generate Link Preview API

Generate Link Preview API

Hosted on ApyHub

What it does

Link Preview fetches a URL and returns the metadata you need to build a rich preview card. Send a URL, and Link Preview returns the page title, description, images, videos, favicons, site name, media type, and content type when available.

Use it when you need to render previews for shared links, build bookmark collections, or show a summary before a user opens a page. If the URL is missing a protocol, Link Preview prepends http:// automatically. You can also set a custom user_agent, accept_language, and allow_redirects to match your crawler or app behavior.

For security-sensitive workflows, secure_mode checks the URL against a malicious-URL database before fetching. When that flag is enabled, the response includes reported_malicious for clean URLs, and malicious URLs return the detected threat instead of preview metadata. You can also choose whether image metadata should come from og or twitter tags with images_property_type.

tags: link-preview, open-graph, metadata-extraction, web-scraping, url-safety

What you'll get back

Returns a JSON object with a data field. On a normal response, data is an object containing preview metadata such as url, title, images, videos, favicons, siteName, mediaType, contentType, description, and, when secure_mode is true, reported_malicious.

{
  "data": {
    "url": "https://apyhub.com",
    "title": "ApyHub",
    "images": ["https://apyhub.com/og-image.png"],
    "videos": [],
    "favicons": ["https://apyhub.com/favicon.ico"],
    "siteName": "ApyHub",
    "mediaType": "website",
    "contentType": "text/html",
    "description": "API tools for developers",
    "reported_malicious": false
  }
}

About this endpoint

What it does

Generates a preview for a URL by fetching the page metadata and returning it in a JSON data object. If the URL is detected as malicious while secure_mode is enabled, the response follows the malicious-URL shape instead of the normal preview metadata shape.

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 either a preview metadata object or a malicious-URL object, depending on the URL lookup result.

Parameter	Type	Mandatory	Description
data	Object	Yes	Either the normal preview metadata object or the malicious-URL object.

Notes

If secure_mode is true, reported_malicious is present in the normal preview response and is always false for a clean URL. In the malicious-URL response, reported_malicious is true and the object includes url and threat.

Body

Name

Type

Description

bodyREQUIRED

object

—

Generate Link Preview API

What it does

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Notes

Body

Errors any endpoint can return