Name: Link Preview API: URL Metadata, Open Graph, Twitter Card
Brand: spacecmd-kits
SKU: api-spacecmd-kits-url-meta
Availability: InStock
Author: API Market

# URL Meta API

## Overview

The URL Meta API takes a public web address and returns the metadata you need to build a link preview, as one JSON object. It has a single endpoint, `/v1/meta`, with one input: the `url`. The API fetches the page and reads its HTML, then returns the page title and description, the canonical URL, the language, a favicon and a preview image, the Open Graph tags (`og`) and Twitter Card tags (`twitter`) as their own objects, any RSS or Atom feeds the page links to, the full list of icon links, and the theme color when the page sets one. It also reports the HTTP `status` and `content_type` of the page it fetched, so you can tell a working page from a broken link.

It is built for developers of chat and messaging apps, social tools, CMS and bookmarking products, SEO checkers and AI agents that need to unfurl or summarise links. The response uses the same flat shape for every page: top-level fields such as `title`, `description`, `image`, `site_name` and `favicon` for quick rendering, plus the raw `og` and `twitter` objects when you need a specific tag. Fields the page does not provide come back as `null`, an empty string, an empty object or an empty list instead of an error, so your parser does not break.

## Features

*   **1 endpoint**: `GET /v1/meta` returns all metadata for a URL in one call.
*   **Simple input**: One query parameter, `url`, any public `http` or `https` address (URL-encoded).
*   **Preview fields**: `title`, `description`, `image`, `site_name`, `canonical`, `lang` and `favicon` at the top level, ready for a link card.
*   **Open Graph and Twitter Card**: All `og:*` and `twitter:*` tags found on the page, returned as `og` and `twitter` objects with the prefix removed (for example `og.image`, `twitter.card`).
*   **Feeds and icons**: RSS and Atom feeds with their `type`, `href` and `title`, and every icon link with its `rel`, `href` and `sizes`.
*   **Page health**: The HTTP `status` and `content_type` of the fetched page.
*   **Data source**: Metadata is read from the HTML the target site returns. According to the provider, no headless browser is used.
*   **Pay as you go**: $0.003 per call, charged to your API.market wallet. No subscription.
*   **Rate limit**: 10 requests per second.

## Use Cases

*   **Link previews in chat**: Show a title, description and image card when a user pastes a link into a chat or comment box.
*   **Social and CMS tools**: Check how a page will look when it is shared, and catch missing `og:image` or Twitter Card tags before publishing.
*   **Bookmarking and read-later apps**: Save a page with its title, description, image and favicon.
*   **SEO audits**: Check canonical URLs, language tags and social tags across a list of pages.
*   **Feed discovery**: Find the RSS or Atom feed of a blog or news site from its homepage.
*   **AI agents**: Give an agent a quick summary of what a link points to without scraping 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/spacecmd-kits/url-meta
```

### 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 URL metadata

Fetches a web page and returns its link-preview metadata: `url`, the page's HTTP `status` and `content_type`, `title`, `description`, `canonical`, `lang`, `favicon`, `image`, `site_name`, the `og` and `twitter` tag objects, `feeds`, `oembed`, `icons`, and `theme_color` when the page sets one.

**Method:** `GET`

**Endpoint:** `/v1/meta`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | The public `http` or `https` URL to read. URL-encode it, for example `https%3A%2F%2Fgithub.com`. | string | Yes | - | - |

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "url": "https://github.com/",
  "status": 200,
  "content_type": "text/html; charset=utf-8",
  "title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub · GitHub",
  "description": "Join the world&#39;s most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.",
  "canonical": "https://github.com/",
  "lang": "en",
  "favicon": "https://github.com/fluidicon.png",
  "image": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png",
  "site_name": "GitHub",
  "og": {
    "image": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png",
    "image:alt": "Join the world&#39;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",
    "type": "object",
    "title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub",
    "url": "https://github.com/",
    "description": "Join the world&#39;s most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity."
  },
  "twitter": {
    "image": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png",
    "site": "@github",
    "card": "summary_large_image",
    "title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub",
    "description": "Join the world&#39;s most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity."
  },
  "feeds": [],
  "oembed": null,
  "icons": [
    {
      "rel": "fluid-icon",
      "href": "https://github.com/fluidicon.png",
      "sizes": null
    },
    {
      "rel": "mask-icon",
      "href": "https://github.githubassets.com/assets/pinned-octocat-093da3e6fa40.svg",
      "sizes": null
    },
    {
      "rel": "alternate icon",
      "href": "https://github.githubassets.com/favicons/favicon.png",
      "sizes": null
    },
    {
      "rel": "icon",
      "href": "https://github.githubassets.com/favicons/favicon.svg",
      "sizes": null
    }
  ],
  "theme_color": "#1e2327"
}
```

**Example Request (a blog with an RSS feed):**

```bash
curl -X GET "https://prod.api.market/api/v1/spacecmd-kits/url-meta/v1/meta?url=https%3A%2F%2Fblog.cloudflare.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "url": "https://blog.cloudflare.com/",
  "status": 200,
  "content_type": "text/html",
  "title": "Cloudflare Blog",
  "description": "Technical deep dives, product updates, and insights from the teams that are helping to build a better Internet.",
  "canonical": "https://blog.cloudflare.com/",
  "lang": "en-us",
  "favicon": "https://blog.cloudflare.com/favicon.ico",
  "image": "https://blog.cloudflare.com/_emdash/api/media/file/01KXJHDG7CJT3B3133XAY31N4V.png",
  "site_name": "Cloudflare Blog",
  "og": {
    "type": "website",
    "title": "Cloudflare Blog",
    "description": "Technical deep dives, product updates, and insights from the teams that are helping to build a better Internet.",
    "image": "https://blog.cloudflare.com/_emdash/api/media/file/01KXJHDG7CJT3B3133XAY31N4V.png",
    "url": "https://blog.cloudflare.com/",
    "site_name": "Cloudflare Blog"
  },
  "twitter": {
    "site": "@cloudflare",
    "url": "https://blog.cloudflare.com/",
    "card": "summary_large_image",
    "title": "Cloudflare Blog",
    "description": "Technical deep dives, product updates, and insights from the teams that are helping to build a better Internet.",
    "image": "https://blog.cloudflare.com/_emdash/api/media/file/01KXJHDG7CJT3B3133XAY31N4V.png"
  },
  "feeds": [
    {
      "type": "application/rss+xml",
      "href": "https://blog.cloudflare.com/rss/",
      "title": "Cloudflare Blog"
    }
  ],
  "oembed": null,
  "icons": [
    {
      "rel": "icon",
      "href": "https://blog.cloudflare.com/favicon.ico",
      "sizes": null
    }
  ]
}
```

**Response fields:**

| Field | Description |
|---|---|
| `url` | The URL that was fetched. |
| `status` | HTTP status code the target page returned. |
| `content_type` | `Content-Type` header of the target page. |
| `title` | Page title. Can be an empty string when the page has none in its HTML. |
| `description` | Meta description, or `null`. |
| `canonical` | Canonical URL from the page, or `null`. |
| `lang` | Page language, for example `en` or `en-us`. |
| `favicon` | One icon URL picked for display. |
| `image` | Preview image URL, or `null`. |
| `site_name` | Site name, or `null`. |
| `og` | Open Graph tags without the `og:` prefix. Empty object when the page has none. |
| `twitter` | Twitter Card tags without the `twitter:` prefix. Empty object when the page has none. |
| `feeds` | RSS or Atom feeds linked from the page, each with `type`, `href` and `title`. Empty list when there are none. |
| `oembed` | oEmbed data where available, otherwise `null`. |
| `icons` | Every icon link on the page, each with `rel`, `href` and `sizes`. |
| `theme_color` | The page's theme color. Only present when the page sets one. |

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The page was fetched and its metadata returned. Check the `status` field for the target page's own HTTP status. |
| 400 | Bad Request | The `url` parameter is missing or is not a valid public `http` or `https` URL. |
| 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/meta`. |
| 429 | Too Many Requests | You went over the PAYG plan's limit of 10 requests per second. Wait briefly and retry. |
| 500 | Internal Server Error | Something failed while fetching or reading the page. Retry after a short delay. |

## Rate Limits

The PAYG plan allows 10 requests per second. Every successful call costs $0.003 and is charged to your API.market wallet; there is no monthly quota. Requests above the per-second limit return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. When you process a list of links, queue them and send them at up to 10 per second. In our tests each call answered in 0.7 to 1.1 seconds, since the API fetches the target page live.

## FAQ

**Why is the title empty for some pages?**

The API reads the HTML the site returns. Some sites build their head with JavaScript or send a minimal page to non-browser clients. In our test, a YouTube watch URL came back with an empty `title`, `null` description and image, and empty `og` and `twitter` objects, while the favicon and the full `icons` list were still returned.

**Does it return oEmbed data?**

The response always has an `oembed` field. The provider says it is filled where the site supports oEmbed. In our tests it was `null` for all three sites we tried, including YouTube, so treat it as optional.

**Should I use `title` or `og.title`?**

`title` comes from the page itself and `og.title` is the title the site wants shown when the page is shared. They can differ: for github.com the `title` ended with an extra `· GitHub` that `og.title` did not have. For link cards, prefer `og.title` and fall back to `title`.

**Why do I see `&#39;` in descriptions?**

Text is returned as it appears in the page's meta tags, so HTML entities such as `&#39;` (an apostrophe) are not decoded. Decode them on your side before display.

**How do I find a site's RSS feed?**

Call the endpoint with the site's homepage and read `feeds`. For blog.cloudflare.com it returned the `application/rss+xml` feed at `/rss/`. The list is empty when the page links no feeds.

**What does the `status` field mean?**

It is the HTTP status the target page returned, not the status of your API call. Use it to spot broken links in bulk checks.

**How am I billed?**

Pay as you go: $0.003 per call, charged to your API.market wallet. There is no subscription. You only need your `x-api-market-key`.

## 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 title, description, preview image, Open Graph and Twitter Card tags, canonical URL, favicon and RSS feeds for any URL as JSON.