Name: Link Preview API: Title, Image and Metadata for Any URL
Brand: compasslab-1
SKU: api-compasslab-1-link-preview
Availability: InStock
Author: API Market

WPTOOLS

# Link Preview API

## Overview

The Link Preview API returns the data you need to draw a link preview card for any public web page. It has 1 endpoint: you send a URL and get back the page title, description, preview image, favicon, site name, canonical URL, language and Open Graph type, plus the author and publication date when the page declares them. The values are read from the page's Open Graph tags, Twitter Card tags and standard HTML tags. Relative image and icon paths are turned into absolute URLs, and redirects are followed (up to 5) so `final_url` shows where the page really lives. The request gives up after 5 seconds, so a slow site never holds your request open, and every response carries a `status` field that says what happened (`ok`, `timeout`, `blocked_by_site`, `not_found` and so on).

It is built for chat and community apps that unfurl links in messages, social schedulers and CMSs that show a card before publishing, bookmarking and read-later tools, newsletter builders, SEO checks that look for pages missing an image or description, and AI agents that want a short summary of a link before deciding to read the whole page. Every response is one flat JSON object: the requested `url`, the `final_url`, the `status`, an `error` message when something went wrong, the preview fields (each `null` when the page does not publish it), and a `metadata` block with the fetch time, elapsed milliseconds, HTTP status, content type, page size in bytes, redirect count and whether the answer came from cache.

## Features

*   **1 endpoint**: `GET /v1/preview` returns the full preview for one URL.
*   **Simple input**: One absolute `http` or `https` URL, 4 to 2,048 characters.
*   **Standard tags only**: Values come from Open Graph, Twitter Card and HTML tags on the page itself. The API does not guess an image from the page body.
*   **HTML fetch, no browser**: The page's HTML is downloaded and parsed. JavaScript is not run, so pages that build their tags in the browser may return empty fields.
*   **Fails fast**: The request stops after 5 seconds and returns `status: timeout` instead of hanging.
*   **Clear outcome**: The `status` field tells you whether the page was read, blocked by the site, blocked by robots.txt, not found, unreachable, too large or of an unsupported type.
*   **Redirects followed**: Up to 5 redirects, each one checked again, with the end point in `final_url` and the count in `metadata.redirects`.
*   **Respects robots.txt**: Pages that disallow the crawler return `blocked_by_robots`. Login walls and anti-bot challenges are never bypassed.
*   **Short cache**: Results are kept in memory for 10 minutes, and `metadata.cached` tells you when an answer came from that cache.
*   **Rate limit**: 1 request per second on FREE, 5 on PRO, 10 on ULTRA and 20 on MEGA.

## Use Cases

*   **Chat and community apps**: Unfurl links in messages with a title, image and site name.
*   **Social schedulers and CMSs**: Show editors how a link card will look before a post goes out.
*   **Bookmarks and read-later tools**: Save a title, description and image with every saved link.
*   **Newsletters and link-in-bio pages**: Build link cards automatically from a list of URLs.
*   **SEO checks**: Find pages that are missing an `og:image`, a description or a canonical URL.
*   **AI agents**: Give a model a short summary of a link so it can decide whether to fetch the full page.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/compasslab-1/link-preview
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Get link preview

Fetches one public page and returns its title, description, preview image, favicon, site name, canonical URL, language, Open Graph type, author and publication date, with a `status` that says what happened and a `metadata` block describing the fetch. Fields the page does not publish come back as `null`.

**Method:** `GET`

**Endpoint:** `/v1/preview`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Absolute `http` or `https` URL of one page. URL-encode it in the query string. Minimum 4 characters. | string | Yes | - | 2,048 characters |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/link-preview/v1/preview?url=https%3A%2F%2Fgithub.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "url": "https://github.com",
  "final_url": "https://github.com",
  "status": "ok",
  "error": null,
  "title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub",
  "description": "Join the world's most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.",
  "site_name": "GitHub",
  "image": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png",
  "favicon": "https://github.com/fluidicon.png",
  "canonical_url": "https://github.com",
  "language": "en",
  "type": "object",
  "author": null,
  "published_at": null,
  "metadata": {
    "fetched_at": "2026-10-17T14:54:42Z",
    "elapsed_ms": 243,
    "cached": false,
    "http_status": 200,
    "content_type": "text/html",
    "bytes": 572402,
    "redirects": 0
  }
}
```

`type` is the page's `og:type` value, for example `article`, `website` or `product`. `metadata.bytes` is the decompressed page size and `metadata.http_status` is the status code the target site returned.

The `status` field takes one of these values:

| Value | Meaning |
|---|---|
| `ok` | The page was fetched and read. |
| `empty_content` | The page was fetched but had nothing usable, often because it is built with JavaScript. |
| `blocked_by_robots` | The site's robots.txt disallows the crawler. |
| `blocked_by_site` | The site answered with HTTP 401, 403, 429 or 451, or showed an anti-bot challenge. |
| `not_found` | The site answered with HTTP 404 or 410. |
| `dead_link` | The host does not resolve or refuses connections. |
| `timeout` | The site did not answer in time, even after one retry. |
| `unsupported_type` | The URL does not serve a supported document type such as HTML. |
| `too_large` | The page is over the size limit (5 MB for HTML). |
| `fetch_failed` | Any other failure, for example an HTTP 5xx from the site after a retry. |

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request was processed. Check the `status` field in the body: a page that timed out, was blocked or was not found is reported there, with the reason in `error`. |
| 400 | Bad Request | The input was rejected, for example a `url` that is not an absolute `http` or `https` URL. The body has an `error` code and a readable `detail`. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Check that you are calling `/v1/preview` under the base URL. |
| 422 | Unprocessable Entity | The `url` parameter is missing or is shorter than 4 or longer than 2,048 characters. The response says which parameter failed. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Each plan has its own per-second limit: FREE allows 1 request per second, PRO 5, ULTRA 10 and MEGA 20. The plans include 500, 10,000, 50,000 and 250,000 calls respectively. The FREE plan stops at its 500 calls, while the paid plans keep working past their included calls and bill the extra calls. Requests above the per-second limit, or on the FREE plan after its calls are used up, return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. The provider gives a median answer time of about 0.2 seconds, and each request stops after 5 seconds at most.

## FAQ

**Why is the `image` field empty?**

The page has no `og:image` or `twitter:image` tag. The API reads only the tags the page publishes and does not guess an image from the page body. The same applies to `description`, `author` and `published_at`.

**What happens with slow sites?**

After 5 seconds the request stops and you get `status: timeout`, so your app never waits longer than that. You can show a plain link instead of a card in that case.

**Does it follow redirects?**

Yes, up to 5, and each redirect target is checked again. `final_url` shows the page the API ended up on and `metadata.redirects` shows how many redirects were followed.

**Can I preview pages behind a login?**

No. Only public pages are read. The API never logs in and does not bypass bot walls, so those pages come back as `blocked_by_site`.

**Why are some fields empty for a page that looks fine in my browser?**

The API reads the HTML the server sends and does not run JavaScript. Sites that add their meta tags in the browser can return empty fields or `status: empty_content`.

**Are results cached?**

Yes, for 10 minutes in memory. `metadata.cached` is `true` when the answer came from that cache and `metadata.fetched_at` shows when the page was fetched.

**Does the provider store the URLs I send?**

The provider states that requests are processed in memory and that its logs keep only counts, timings and status codes, not URLs or results.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Link preview API that returns the title, description, Open Graph image, favicon, site name and canonical URL of any public page, with a status for every fetch.

Link Preview API: Title, Image and Metadata for Any URL

FREE