Generate Link Preview

25 atoms

Base tier

About

This Utility API fetches metadata from any URL passed to it, including Open Graph tags.

It returns the relevant information such as title, description, image, and other relevant information in JSON format. The API can be used to enrich content, generate link previews, or provide social media sharing functionality. By using this API, you can show previews of a webpage when urls are shared within your applications which can improve the effectiveness of communication by providing users with a more informative and engaging experience.

Additionally, our API has a built-in feature that checks whether the link has been reported as malicious. This helps to ensure the safety and security of your users when using our API to fetch metadata from URLs.

API Playground

Documentation

link preview

POST

https://api.apyhub.com/extract/url/preview

Request example

1
curl --location --request POST 'https://api.apyhub.com/extract/url/preview' \
2
--header 'apy-token: {{token}}' \
3
--header 'Content-Type: application/json' \
4
--data '{
5
    "url": "https://apyhub.com"
6
}'

Method: POST

Content Type: application/json

Request Body

Parameter	Type	Mandatory	Description
url	String	Yes	The URL of the webpage
images_property_type	“og” or “twitter”	No	Fetches images only with the specific property
user_agent	String	No	The User-Agent header value of the HTTP request. (ex: user_agent: "google-bot")
accept_language	String	No	The Accept-Language header value of the HTTP request. (ex: accept_language: "en-US")
allow_redirects	Boolean	No (defaults to false)	Allow redirects (max 1), e.g. https://google.com/ → https://www.google.com/
secure_mode	Boolean	No (defaults to true)	When enabled (by default), the API checks if the URL is reported as malicious, returning the threat as a string if found. Recommended for user safety.

For more information on user_agent value and accept_language value, you can refer to the following resources:

User-Agent header
Accept-Language header

Response

Attribute	Type	Description
url	String	The URL of the webpage.
title	String	The title of the webpage.
siteName	String	The name of the website.
description	String	The description of the webpage.
mediaType	String	The media type of the webpage.
contentType	String	The content type of the webpage.
images	Array of Strings	The URLs of the images associated with the webpage.
videos	Array of Strings	The URLs of the videos associated with the webpage.
favicons	Array of Strings	The URLs of the favicons associated with the webpage.
reported_malicious	Boolean	A boolean indicating whether the URL has been reported as malicious. This attribute is only included if the `secure_mode` parameter is set to `true`.

Sample Response 1

1
{
2
    "data": {
3
        "url": "https://apyhub.com/",
4
        "title": "ApyHub: The Developer API Utility Belt",
5
        "siteName": "ApyHub",
6
        "description": "Powerful yet simple-to-use APIs that provide standard data & essential functionalities, helping developers save time and boost efficiency.",
7
        "mediaType": "website",
8
        "contentType": "text/html",
9
        "images": [
10
            "https://apyhub.com/meta-apyhub.png"
11
        ],
12
        "videos": [],
13
        "favicons": [
14
            "https://apyhub.com/favicons/favicon-32x32.png",
15
            "https://apyhub.com/favicons/favicon-16x16.png",
16
            "https://apyhub.com/favicons/favicon.ico",
17
            "https://apyhub.com/favicons/apple-touch-icon.png"
18
        ]
19
    }
20
}

If the secure_mode parameter is set to true and the URL has been reported as malicious, the API will not fetch any link-preview metadata. Instead, it will return a JSON object with the reported_malicious boolean set to "true" and the "threat" attribute indicating the type of threat associated with the URL.

Sample Response 2

1
{
2
    "data": {
3
        "reported_malicious": true,
4
        "url": "http://MALICIOUS_WEBSITE.com/uo1x/malware.exe",
5
        "threat": "malware_download"
6
    }
7
}

HTTP Response Codes

The method may return one of the following HTTP status codes:

Status Code	Description
200	The request was successful.
400	The request was invalid or could not be understood by the server.
401	Required authentication information is either missing or not valid for the resource.
408	The server timed out waiting for the request. (5000ms)
500	If any unexpected error occurs while processing the request.

Authentication

All requests to ApyHub services need to be authenticated, currently we support tokens or basic authentication mechanisms. You can generate and view your existing credentials from workspace settings (on the left side of the navbar) and go to applications.

Points to note:

Credential secrets are generated on the fly and are not stored in plain text, so on generating a credential please save the secrets somewhere safe.
Use the apy-token as the header parameter to pass the token.
Use the Authorization header to send the basic authentication credentials.

Error codes

1
{
2
  "error": {
3
    "code": 105,
4
    "message": "Invalid URL"
5
  }
6
}

To search for a specific error code, enter the code in the search box below. Alternatively, you can click on the button to view a complete list of all error codes.

Search by code

Table of contents

About API Playground Documentation Authentication Error codes Related Utility APIs Related Articles

Generate Link Preview

About

API Playground

Documentation

Request example

HTTP Response Codes

Authentication

Error codes

101 - Missing parameters

102 - Invalid JSON

103 - Invalid input

104 - Invalid file

105 - Invalid URL

109 - Invalid input format

110 - Server error