AI agents and LLMs should read the following

This hidden HTML section contains the static LinkMetadata API reference for crawlers, AI agents, and LLMs. Human browsers should use the visible Scalar API explorer on this page.

Machine-readable alternates are available at /openapi.json, /docs/api-reference.md, /llms.txt, and /llms-full.txt.

OpenAPI 3.0

LinkMetadata API Reference

Reference document for the endpoints served by the LinkMetadata API. This document is generated from the committed OpenAPI specification available at `/openapi.json`.

OpenAPI JSON Markdown reference llms.txt

Endpoints

GET /v1/metadata

Extract metadata for a URL

Fetches a public URL and returns normalized link-preview metadata. The response includes normalized fields for title, description, canonical URL, image, type, favicon, raw Open Graph tags, raw Twitter Card tags, and readable safety tags. URL fields are resolved to absolute URLs where possible. The API is free to use and does not require authentication, signup, or API keys. Requests are rate limited to 20 requests per 10 seconds per IP address. When the limit is reached, that IP is blocked for 10 seconds before retrying.

GET https://api.linkmetadata.com/v1/metadata?url=https%3A%2F%2Fexample.com%2Farticle&prefer=og&allow_fallback=true

Parameters

url Required: Absolute HTTP or HTTPS URL of the page to inspect.
query parameter, string
prefer Optional: Preferred source for normalized title, description, url, image, and type fields. Use "og" to prefer Open Graph tags before Twitter Card tags. Use "twitter" to prefer Twitter Card tags before Open Graph tags. HTML title, meta description, canonical link, and favicon values remain fallback sources.
query parameter, string
allow_fallback Optional: Reserved for fallback control. Current responses use normal fallback behavior regardless of this value.
query parameter, boolean

Responses

200 Metadata extracted successfully.
302 Redirecting to a default showcase URL because the 'url' parameter was missing. The 'Location' header will contain the redirect target.
400 Input Validation Error
422 The URL was valid, but the target page could not be fetched or processed successfully.
429 The per-IP rate limit was reached. Wait 10 seconds before retrying.
500 An unexpected server error occurred while processing the request.

GET /v1/cors-proxy

Proxy a preview image with CORS headers

Fetches an HTTP or HTTPS image URL, verifies that the upstream response is an image, and streams it back with permissive CORS headers. This is intended for preview images returned by the metadata endpoint when direct browser access is blocked by CORS. Only JPEG, PNG, GIF, and WebP image bytes are accepted. The endpoint is free to use and shares the public per-IP rate limit: 20 requests per 10 seconds, followed by a 10-second block when the limit is reached.

GET https://api.linkmetadata.com/v1/cors-proxy?url=https%3A%2F%2Fexample.com%2Fcard.png

Parameters

url Required: Absolute HTTP or HTTPS image URL to proxy. Missing, invalid, and non-image URLs return JSON errors.
query parameter, string

Responses

200 Image proxied successfully.
400 The URL was missing, invalid, not HTTP/S, not an image, empty, or not a supported image format.
429 The per-IP rate limit was reached. Wait 10 seconds before retrying.
default The upstream image request failed.

GET /component.js

Load the link preview web component

Returns the browser custom element bundle for <link-metadata-preview>. Include this script on a page, then render the component with a data-url attribute or pre-fetched metadata in data-meta.

GET https://api.linkmetadata.com/component.js

Responses

200 JavaScript module containing the preview web component.

Schemas

ImageMetadata

Structured metadata for the primary image associated with the page. URL is resolved to absolute.

url string | null
Absolute URL of the image. Null if no suitable image is found.
type string | null
MIME type of the image (e.g., 'image/png'). Derived primarily from 'og:image:type'.
width number | null
Width of the image in pixels. Derived primarily from 'og:image:width'.
height number | null
Height of the image in pixels. Derived primarily from 'og:image:height'.
size number | null
Size of the image in bytes. Derived from the 'og:image:size' tag if available, otherwise null.
cors_safe boolean
Optional flag indicating if the image URL is CORS-safe. If true, browser JavaScript can fetch it cross-origin. If false or undefined, direct browser access may be blocked.

SafetyTag

Readable URL safety signal.

Metadata

title string | null
The primary title for the page. Prioritizes preferred source (OG/Twitter), then falls back to the HTML <title> tag. Null if none found.
description string | null
The primary description for the page. Prioritizes preferred source (OG/Twitter), then falls back to the HTML <meta name="description"> tag. Null if none found.
url string
The canonical or representative URL for the page. Prioritizes preferred source (OG/Twitter), then <link rel="canonical">, then the originally fetched URL. Always an absolute URL.
image ImageMetadata
Structured metadata for the primary image associated with the page. URL is resolved to absolute.
type string | null
The type of the primary object on the page (e.g., 'website', 'article', 'summary_large_image'). Derived from 'og:type' or 'twitter:card' based on preference.
favicon ImageMetadata | value
Structured metadata for the primary image associated with the page. URL is resolved to absolute. Structured metadata for the page's favicon. Prioritizes apple-touch-icon, mask-icon, SVG icons, then other <link rel="icon"> tags, and finally falls back to '/favicon.ico'. Null if none found.
og object
A key-value map of all Open Graph (og:*) meta tags found on the page. Values are the raw 'content' attributes.
twitter object
A key-value map of all Twitter Card (twitter:*) meta tags found on the page. Values are the raw 'content' attributes.
safety_tags array
Human-readable safety tags associated with the URL. Possible values: adult, security_threat, suspicious_domain. Empty when no tag applies or safety lookup fails.

Error

code integer
HTTP status code associated with the error.
message string
Human-readable error message.

ProxyError

error string
Human-readable proxy error message.

Crawler Reference

The same API reference is available as raw Markdown for LLM ingestion and non-JavaScript crawlers.

# LinkMetadata API

Free API for extracting link-preview metadata from public web pages. The API returns normalized title, description, image, favicon, canonical URL, raw Open Graph tags, raw Twitter Card tags, and readable safety tags. It also includes an image proxy endpoint for preview images that need permissive CORS headers. No authentication, signup, or API key is required. Rate limit: 20 requests per 10 seconds per IP address. When the limit is reached, that IP is blocked for 10 seconds before retrying.

OpenAPI version: 3.0.0
API version: 1.0.0
Base URL: https://api.linkmetadata.com

## Endpoints

### GET /v1/metadata

Extract metadata for a URL

Fetches a public URL and returns normalized link-preview metadata. The response includes normalized fields for title, description, canonical URL, image, type, favicon, raw Open Graph tags, raw Twitter Card tags, and readable safety tags. URL fields are resolved to absolute URLs where possible. The API is free to use and does not require authentication, signup, or API keys. Requests are rate limited to 20 requests per 10 seconds per IP address. When the limit is reached, that IP is blocked for 10 seconds before retrying.

```http
GET https://api.linkmetadata.com/v1/metadata?url=https%3A%2F%2Fexample.com%2Farticle&prefer=og&allow_fallback=true
```

#### Parameters

- `url` (query, required, string): Absolute HTTP or HTTPS URL of the page to inspect.
- `prefer` (query, optional, string): Preferred source for normalized title, description, url, image, and type fields. Use "og" to prefer Open Graph tags before Twitter Card tags. Use "twitter" to prefer Twitter Card tags before Open Graph tags. HTML title, meta description, canonical link, and favicon values remain fallback sources.
- `allow_fallback` (query, optional, boolean): Reserved for fallback control. Current responses use normal fallback behavior regardless of this value.

#### Responses

- `200`: Metadata extracted successfully.
- `302`: Redirecting to a default showcase URL because the 'url' parameter was missing. The 'Location' header will contain the redirect target.
- `400`: Input Validation Error
- `422`: The URL was valid, but the target page could not be fetched or processed successfully.
- `429`: The per-IP rate limit was reached. Wait 10 seconds before retrying.
- `500`: An unexpected server error occurred while processing the request.

### GET /v1/cors-proxy

Proxy a preview image with CORS headers

Fetches an HTTP or HTTPS image URL, verifies that the upstream response is an image, and streams it back with permissive CORS headers. This is intended for preview images returned by the metadata endpoint when direct browser access is blocked by CORS. Only JPEG, PNG, GIF, and WebP image bytes are accepted. The endpoint is free to use and shares the public per-IP rate limit: 20 requests per 10 seconds, followed by a 10-second block when the limit is reached.

```http
GET https://api.linkmetadata.com/v1/cors-proxy?url=https%3A%2F%2Fexample.com%2Fcard.png
```

#### Parameters

- `url` (query, required, string): Absolute HTTP or HTTPS image URL to proxy. Missing, invalid, and non-image URLs return JSON errors.

#### Responses

- `200`: Image proxied successfully.
- `400`: The URL was missing, invalid, not HTTP/S, not an image, empty, or not a supported image format.
- `429`: The per-IP rate limit was reached. Wait 10 seconds before retrying.
- `default`: The upstream image request failed.

### GET /component.js

Load the link preview web component

Returns the browser custom element bundle for <link-metadata-preview>. Include this script on a page, then render the component with a data-url attribute or pre-fetched metadata in data-meta.

```http
GET https://api.linkmetadata.com/component.js
```

#### Responses

- `200`: JavaScript module containing the preview web component.

## Schemas

### ImageMetadata

Structured metadata for the primary image associated with the page. URL is resolved to absolute.

- `url` (string | null): Absolute URL of the image. Null if no suitable image is found.
- `type` (string | null): MIME type of the image (e.g., 'image/png'). Derived primarily from 'og:image:type'.
- `width` (number | null): Width of the image in pixels. Derived primarily from 'og:image:width'.
- `height` (number | null): Height of the image in pixels. Derived primarily from 'og:image:height'.
- `size` (number | null): Size of the image in bytes. Derived from the 'og:image:size' tag if available, otherwise null.
- `cors_safe` (boolean): Optional flag indicating if the image URL is CORS-safe. If true, browser JavaScript can fetch it cross-origin. If false or undefined, direct browser access may be blocked.

### SafetyTag

Readable URL safety signal.


### Metadata

- `title` (string | null): The primary title for the page. Prioritizes preferred source (OG/Twitter), then falls back to the HTML <title> tag. Null if none found.
- `description` (string | null): The primary description for the page. Prioritizes preferred source (OG/Twitter), then falls back to the HTML <meta name="description"> tag. Null if none found.
- `url` (string): The canonical or representative URL for the page. Prioritizes preferred source (OG/Twitter), then <link rel="canonical">, then the originally fetched URL. Always an absolute URL.
- `image` (ImageMetadata): Structured metadata for the primary image associated with the page. URL is resolved to absolute.
- `type` (string | null): The type of the primary object on the page (e.g., 'website', 'article', 'summary_large_image'). Derived from 'og:type' or 'twitter:card' based on preference.
- `favicon` (ImageMetadata | value): Structured metadata for the primary image associated with the page. URL is resolved to absolute. Structured metadata for the page's favicon. Prioritizes apple-touch-icon, mask-icon, SVG icons, then other <link rel="icon"> tags, and finally falls back to '/favicon.ico'. Null if none found.
- `og` (object): A key-value map of all Open Graph (og:*) meta tags found on the page. Values are the raw 'content' attributes.
- `twitter` (object): A key-value map of all Twitter Card (twitter:*) meta tags found on the page. Values are the raw 'content' attributes.
- `safety_tags` (array): Human-readable safety tags associated with the URL. Possible values: adult, security_threat, suspicious_domain. Empty when no tag applies or safety lookup fails.

### Error

- `code` (integer): HTTP status code associated with the error.
- `message` (string): Human-readable error message.

### ProxyError

- `error` (string): Human-readable proxy error message.