Name: Link Preview API: Open Graph, Meta Tags and oEmbed
Brand: rasareka
SKU: api-rasareka-url-preview
Availability: InStock
Author: API Market

Khairul Fauzy Khairudin

# URL Preview API

## Overview

The URL Preview API turns a link into the data you need for a preview card, the way Slack, WhatsApp and iMessage unfurl links. For any public URL it returns the title, description, main image, favicon, site name, author, canonical URL, Open Graph and Twitter Card fields and the final URL after redirects. YouTube, TikTok and Spotify links are resolved through their official oEmbed services, so you also get the embed HTML.

It is built for developers of chat apps, social and community platforms, CMS editors, bookmarking tools and link-in-bio products. In our tests a GitHub repository URL returned its Open Graph title, description and image in 1.3 seconds, a YouTube link returned the video title, author and thumbnail through oEmbed, and a bulk call previewed three links at once.

## Features

*   **2 endpoints**: single preview and bulk preview of up to 10 URLs.
*   **Open Graph and Twitter Cards**: title, description, image, site name, card type and creator.
*   **oEmbed**: YouTube, TikTok and Spotify links return media details and embed HTML.
*   **Redirects followed**: `final_url` shows where the link ended up.
*   **1 hour cache**: repeat requests are fast, and `fresh=true` skips the cache.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Chat apps**: show a rich card when a user pastes a link.
*   **Social platforms**: preview shared links in posts and comments.
*   **CMS editors**: fill in title, image and description when an editor adds a link.
*   **Bookmarking tools**: save a title and thumbnail with each link.
*   **SEO checks**: see how a page presents its Open Graph data.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/rasareka/url-preview
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

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

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Preview one URL

Fetches a public URL and returns its preview data.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Full URL of the public page, for example `https://github.com/cloudflare/workers-sdk` | string | Yes | - | - |
| `fresh` | query | Set `true` to skip the 1 hour cache | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/url-preview/preview/v1/preview?url=https%3A%2F%2Fgithub.com%2Fcloudflare%2Fworkers-sdk' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "url": "https://github.com/cloudflare/workers-sdk",
  "final_url": "https://github.com/cloudflare/workers-sdk",
  "status_code": 200,
  "content_type": "text/html",
  "response_time_ms": 398,
  "title": "GitHub - cloudflare/workers-sdk: ⛅️ Home to Wrangler, the CLI for Cloudflare Workers®",
  "description": "⛅️ Home to Wrangler, the CLI for Cloudflare Workers® - cloudflare/workers-sdk",
  "image": "https://opengraph.githubassets.com/db3d9c86612013eeac8389b2f011a20d3b369e314e98954c6f5e23106d87b84e/cloudflare/workers-sdk",
  "image_alt": "⛅️ Home to Wrangler, the CLI for Cloudflare Workers® - cloudflare/workers-sdk",
  "site_name": "GitHub",
  "media_type": "object",
  "author": null,
  "published_time": null,
  "keywords": [],
  "locale": "en",
  "canonical_url": "https://github.com/cloudflare/workers-sdk",
  "favicon": "https://github.githubassets.com/favicons/favicon.png",
  "theme_color": "#1e2327",
  "video": null,
  "twitter": {
    "card": "summary_large_image",
    "site": "@github",
    "creator": null
  },
  "schema_types": [],
  "raw_html_title": "GitHub - cloudflare/workers-sdk: ⛅️ Home to Wrangler, the CLI for Cloudflare Workers® · GitHub",
  "error": null,
  "source": "html",
  "cached": false
}
```

A YouTube link is resolved through oEmbed:

```json
{
  "ok": true,
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "final_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "status_code": 200,
  "content_type": "application/json+oembed",
  "response_time_ms": 51,
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "description": null,
  "image": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "image_alt": null,
  "site_name": "YouTube",
  "media_type": "video",
  "author": "Rick Astley",
  "author_url": "https://www.youtube.com/@RickAstleyYT",
  "published_time": null,
  "keywords": [],
  "locale": null,
  "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "favicon": "https://www.google.com/s2/favicons?domain=www.youtube.com&sz=64",
  "theme_color": null,
  "video": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "embed_html": "<iframe width=\"200\" height=\"113\" src=\"https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed\" frameborder=\"0\"...",
  "twitter": {
    "card": null,
    "site": null,
    "creator": null
  },
  "schema_types": [],
  "raw_html_title": null,
  "source": "oembed",
  "error": null,
  "cached": false
}
```

When the site refuses the request, the call still returns 200 with `ok: false` and the site status in `error`:

```json
{
  "ok": false,
  "url": "https://www.bbc.com/news",
  "final_url": "https://www.bbc.com/news",
  "status_code": 403,
  "content_type": "text/html",
  "response_time_ms": 4563,
  "title": null,
  "description": null,
  "image": null,
  "image_alt": null,
  "site_name": "bbc.com",
  "media_type": "website",
  "author": null,
  "published_time": null,
  "keywords": [],
  "locale": null,
  "canonical_url": null,
  "favicon": "https://www.bbc.com/favicon.ico",
  "theme_color": null,
  "video": null,
  "twitter": {
    "card": null,
    "site": null,
    "creator": null
  },
  "schema_types": [],
  "raw_html_title": null,
  "error": "http_403",
  "source": "html",
  "cached": false
}
```

#### 2. Preview up to 10 URLs

Previews several URLs in one call and reports how many succeeded.

**Method:** `POST`

**Endpoint:** `/preview/v1/preview-bulk`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `urls` | body | List of public URLs | array of strings | Yes | - | 10 URLs |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/rasareka/url-preview/preview/v1/preview-bulk' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"urls": ["https://github.com", "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT", "https://example.com"]}'
```

**Example Response (200 OK):**

```json
{
  "count": 3,
  "ok": 3,
  "results": [
    {
      "ok": true,
      "url": "https://github.com/",
      "final_url": "https://github.com/",
      "status_code": 200,
      "content_type": "text/html",
      "response_time_ms": 39,
      "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.",
      "image": "https://images.ctfassets.net/8aevphvgewt8/76epZKB2wF998m4e4bLLXn/c505f20b00ec70b88b1be5aec42c4be4/OG_image.jpg",
      "image_alt": "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",
      "media_type": "object",
      "author": null,
      "published_time": null,
      "keywords": [],
      "locale": "en",
      "canonical_url": "https://github.com/",
      "favicon": "https://github.githubassets.com/favicons/favicon.png",
      "theme_color": "#1e2327",
      "video": null,
      "twitter": {
        "card": "summary_large_image",
        "site": "@github",
        "creator": null
      },
      "schema_types": [],
      "raw_html_title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub · GitHub",
      "error": null,
      "source": "html",
      "cached": false
    }
  ]
}
```

The `results` list above is shortened to the first of the three URLs.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 400 | Bad Request | A required parameter is missing or invalid. The body has an `error` code and a `message`. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API. Check the Base URL and path. |
| 429 | Too Many Requests | You went over 10 requests per second or used up the quota of your plan. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second, and each subscription plan has its own monthly quota. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Why did a page return ok false?**
    The site answered with an error or blocked the request, for example `http_403` from a news site that blocks automated fetching. Check `ok` and `error` on every result.

*   **Is a failed preview billed?**
    Yes. The call itself succeeded and reported the site status, so it counts as a request.

*   **Which video and music links are supported?**
    YouTube, TikTok and Spotify are resolved through their official oEmbed services and include `embed_html`.

*   **How fresh is the data?**
    Previews are cached for 1 hour. Set `fresh=true` to fetch the page again.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Turn any URL into a preview card with title, description, image, favicon and Open Graph data. YouTube, TikTok and Spotify links via oEmbed.

Link Preview API: Open Graph, Meta Tags and oEmbed