Name: Peek Link Preview API: any URL, one link card
Brand: hybrid-forge-lab
SKU: api-hybrid-forge-lab-peek
Availability: InStock
Author: API Market

# Peek Link Preview API

## Overview

The Peek API turns any URL into a link card: title, description, image, favicon, site name, theme colour, Twitter card, oEmbed and video. It reads Open Graph first and falls back to plain HTML when a page has no tags.

It is built for chat apps, CMS editors, newsletters and bookmark tools that need rich link previews without running their own crawler. The fetcher only reaches the public internet, so it can't be pointed at your network.

## Features

*   **Four endpoints**: a preview by query string, the same preview with a JSON body, a bulk preview and a health check.
*   **Title and description**: `og:title` and `og:description` first, then Twitter tags, JSON-LD, the `<title>`, the meta description, the first heading and the first real paragraph.
*   **The right image**: `og:image` with `secure_url` preferred, width, height and alt, plus every other candidate. Relative URLs are always made absolute.
*   **Favicon and theme**: the largest icon the page declares, the theme colour and the site name.
*   **Video and oEmbed**: `og:video` for players, and the oEmbed discovery link when the page advertises one.
*   **Article facts**: author, published and modified time, locale, canonical URL, `og:type` and the Twitter card fields.
*   **Bulk**: up to 20 URLs per call, results in your order. A bad URL gets its own error and never fails the call.
*   **Honest statuses**: every URL gets a `status` and a `reason` with HTTP 200, so your code can choose between a rich card and a plain link.

## Use Cases

*   **Chat and community apps**: unfurl links in messages, comments and posts, without running your own crawler.
*   **CMS and newsletters**: turn pasted links into rich cards in the editor, or render "read more" blocks with the article's own image.
*   **Bookmarks and read-later**: save the real title, image, site name and final URL (after redirects and short links) with every bookmark.
*   **Link-in-bio and directories**: show a thumbnail and description for every listed site.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/hybrid-forge-lab/peek
```

### 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. Health check

Returns `ok`, the service version and its uptime.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/peek/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "0.2.1",
  "uptime_s": 457
}
```

#### 2. Preview one URL (GET)

Fetches one page and returns its link card. A bare domain such as `github.com` is accepted and gets `https://` added.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Page to preview: an http(s) URL or a bare domain. URL-encode it. | string | Yes | - | 2048 characters |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/peek/v1/preview?url=https%3A%2F%2Fgithub.com%2Fpython%2Fcpython' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "url": "https://github.com/python/cpython",
  "final_url": "https://github.com/python/cpython",
  "status": "ok",
  "reason": null,
  "http_status": 200,
  "content_type": "text/html",
  "type": "object",
  "title": "GitHub - python/cpython: The Python programming language",
  "description": "The Python programming language. Contribute to python/cpython development by creating an account on GitHub.",
  "site_name": "GitHub",
  "image": {
    "url": "https://opengraph.githubassets.com/cfe53823e0739df4f583749f7f35622a70c1ef3169c500edd44e30a76d173c09/python/cpython",
    "width": 1200,
    "height": 600,
    "alt": "The Python programming language. Contribute to python/cpython development by creating an account on GitHub."
  },
  "images": [
    {
      "url": "https://opengraph.githubassets.com/cfe53823e0739df4f583749f7f35622a70c1ef3169c500edd44e30a76d173c09/python/cpython",
      "width": 1200,
      "height": 600,
      "alt": "The Python programming language. Contribute to python/cpython development by creating an account on GitHub."
    },
    {
      "url": "https://github.githubassets.com/assets/platform-4ce65ae0bf273ce2.png",
      "width": 240,
      "height": 150,
      "alt": null
    }
  ],
  "favicon": "https://github.githubassets.com/favicons/favicon.png",
  "theme_color": "#1e2327",
  "locale": "en",
  "author": null,
  "published_time": null,
  "modified_time": null,
  "canonical_url": "https://github.com/python/cpython",
  "twitter": {
    "card": "summary_large_image",
    "site": "@github",
    "creator": null
  },
  "oembed": null,
  "video": null,
  "cached": false,
  "took_ms": 608
}
```

#### 3. Preview one URL (POST)

The same preview as the GET endpoint, with the URL in a JSON body. Use it when the URL is long or hard to encode.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | body | Page to preview: an http(s) URL or a bare domain. | string | Yes | - | 2048 characters |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/peek/v1/preview' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://hybridforgelab.com"}'
```

**Example Response (200 OK):**

```json
{
  "url": "https://hybridforgelab.com/",
  "final_url": "https://hybridforgelab.com/",
  "status": "ok",
  "reason": null,
  "http_status": 200,
  "content_type": "text/html",
  "type": "website",
  "title": "Hybrid Forge Lab — Developer APIs and automation tools",
  "description": "Hybrid Forge Lab builds and runs focused developer APIs, from email validation and company enrichment to GDPR scans, cron parsing and link previews.",
  "site_name": "hybridforgelab.com",
  "image": {
    "url": "https://hybridforgelab.com/logo.png",
    "width": null,
    "height": null,
    "alt": null
  },
  "images": [
    {
      "url": "https://hybridforgelab.com/logo.png",
      "width": null,
      "height": null,
      "alt": null
    }
  ],
  "favicon": "https://hybridforgelab.com/apple-touch-icon.png",
  "theme_color": "#07090d",
  "locale": "en-US",
  "author": null,
  "published_time": null,
  "modified_time": null,
  "canonical_url": "https://hybridforgelab.com/",
  "twitter": {
    "card": "summary",
    "site": null,
    "creator": null
  },
  "oembed": null,
  "video": null,
  "cached": false,
  "took_ms": 408
}
```

#### 4. Preview up to 20 URLs

Previews up to 20 URLs in one call, with results in the same order as the input. A URL that can't be accepted gets an `error` item in its place, and the other URLs are still previewed.

**Method:** `POST`

**Endpoint:** `/v1/bulk`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `urls` | body | The URLs to preview, as http(s) URLs or bare domains. | array of strings | Yes | - | 20 items |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/peek/v1/bulk' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"urls": ["https://www.python.org", "localhost", "https://www.wikipedia.org"]}'
```

**Example Response (200 OK):**

```json
{
  "count": 3,
  "results": [
    {
      "url": "https://www.python.org/",
      "final_url": "https://www.python.org/",
      "status": "ok",
      "reason": null,
      "http_status": 200,
      "content_type": "text/html",
      "type": "website",
      "title": "Welcome to Python.org",
      "description": "The official home of the Python Programming Language",
      "site_name": "Python.org",
      "image": {
        "url": "https://www.python.org/static/opengraph-icon-200x200.png",
        "width": null,
        "height": null,
        "alt": null
      },
      "images": [
        {
          "url": "https://www.python.org/static/opengraph-icon-200x200.png",
          "width": null,
          "height": null,
          "alt": null
        }
      ],
      "favicon": "https://www.python.org/static/apple-touch-icon-precomposed.png",
      "theme_color": "#3673a5",
      "locale": "en",
      "author": null,
      "published_time": null,
      "modified_time": null,
      "canonical_url": "https://www.python.org/",
      "twitter": {
        "card": null,
        "site": null,
        "creator": null
      },
      "oembed": null,
      "video": null,
      "cached": false,
      "took_ms": 118
    },
    {
      "url": "localhost",
      "error": "send a full hostname, e.g. example.com"
    },
    {
      "url": "https://www.wikipedia.org/",
      "final_url": "https://www.wikipedia.org/",
      "status": "ok",
      "reason": null,
      "http_status": 200,
      "content_type": "text/html",
      "type": "website",
      "title": "Wikipedia, the free encyclopedia",
      "description": "Wikipedia is a free online encyclopedia, created and edited by volunteers around the world and hosted by the Wikimedia Foundation.",
      "site_name": "wikipedia.org",
      "image": {
        "url": "https://upload.wikimedia.org/wikipedia/en/thumb/8/80/Wikipedia-logo-v2.svg/250px-Wikipedia-logo-v2.svg.png",
        "width": null,
        "height": null,
        "alt": null
      },
      "images": [
        {
          "url": "https://upload.wikimedia.org/wikipedia/en/thumb/8/80/Wikipedia-logo-v2.svg/250px-Wikipedia-logo-v2.svg.png",
          "width": null,
          "height": null,
          "alt": null
        }
      ],
      "favicon": "https://www.wikipedia.org/static/apple-touch/wikipedia.png",
      "theme_color": null,
      "locale": "en",
      "author": null,
      "published_time": null,
      "modified_time": null,
      "canonical_url": null,
      "twitter": {
        "card": null,
        "site": null,
        "creator": null
      },
      "oembed": null,
      "video": null,
      "cached": false,
      "took_ms": 587
    }
  ],
  "took_ms": 624
}
```

### Preview statuses

A preview always comes back with HTTP 200 and one of these `status` values:

| `status` | `reason` | Meaning |
|---|---|---|
| `ok` | - | Preview built from an HTML page or a direct image or video link. |
| `blocked` | `private_address`, `port_not_allowed`, `bot_protection` | The target is not on the public internet, or the site's bot wall refused the request. |
| `robots_txt` | `disallowed`, `robots_unavailable` | The site opted out of PeekBot in robots.txt, or robots.txt answered with a 5xx. |
| `not_html` | - | A file such as a PDF; `content_type` tells you what it is. |
| `http_error` | `HTTP 404` and similar | The page answered with a 4xx or 5xx. |
| `unreachable` | `dns`, `timeout`, `too_many_redirects`, `connection_failed` | The page could not be reached. |
| `throttled` | `per_site_limit` | That site had 20 fresh previews in the last minute. Retry shortly. |

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request was handled. Check `status` in each preview to see whether a card was built. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 404 | Not Found | The path is wrong. This API has `GET /v1/health`, `GET /v1/preview`, `POST /v1/preview` and `POST /v1/bulk`. |
| 422 | Unprocessable Entity | The URL is missing or malformed, or `POST /v1/bulk` got more than 20 URLs. The `detail` field says why, for example `send a full hostname, e.g. example.com`. |
| 429 | Too Many Requests | You sent more requests per second than your plan allows. Wait a moment and try again. |
| 500 | Internal Server Error | Something failed on the provider side. Retry once; if it keeps failing, contact us. |

## Rate Limits

Plans and limits:

*   **Free**: 15 requests, a 7-day free trial, once per customer, 2 requests per second. Single previews only: `POST /v1/bulk` is not in the Free plan.
*   **Pro**: 20,000 requests per month, 10 requests per second.
*   **Ultra**: 100,000 requests per month, 20 requests per second.
*   **Mega**: 500,000 requests per month, 50 requests per second.

Each request counts as one call, a bulk request included. Calls stop when the quota runs out until the next month.

Going over your plan's requests per second returns `429 Too Many Requests`. Back off for a moment before retrying.

## FAQ

*   **What if a page has no Open Graph tags?**

    Peek falls back to Twitter tags, JSON-LD, the `<title>`, the meta description, the first heading, the first real paragraph and the first large image. `site_name` falls back to the hostname, so an `ok` preview is never blank.

*   **Can someone use Peek to reach my internal network?**

    No. Every connection and every redirect must resolve only to public addresses on ports 80 or 443, and anything else comes back as `blocked`, never with content.

*   **Does it get past bot protection?**

    No, on purpose. PeekBot uses an honest user agent, and sites behind bot walls come back as `blocked` with reason `bot_protection`, so you can show a plain link.

*   **Does it fetch oEmbed?**

    Peek reports the oEmbed URL the page advertises, but doesn't call it. You decide whether to fetch embed HTML from that provider.

*   **Is anything stored?**

    Previews are kept in memory for up to 6 hours so repeat lookups are fast, then dropped. There are no request logs, so the URLs you send aren't logged.

## 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.


Turn any URL into a link card: title, description, image, favicon, theme colour, oEmbed and video, with HTML fallbacks and SSRF-safe fetching.

Peek Link Preview API: any URL, one link card

Peek Link Preview API