URL Unfurl API — Extract Social Media Metadata

TryUnfurl's URL unfurl API is a simple REST endpoint for website metadata extraction. Send a URL, get back a clean JSON object containing Open Graph tags, Twitter Card data, page title, description, canonical URL, and favicon — everything a social network, chat app, or CMS needs to render a rich link preview.

This page is the complete API documentation for the TryUnfurl link preview API. It covers how to get started, authentication, request and response shapes, error handling, code examples in JavaScript, Python, PHP and cURL, real-world use cases, pricing, and a FAQ answering common questions from developers integrating the URL unfurl API.

Getting Started

The URL unfurl API is a single POST endpoint that accepts a JSON body and returns structured metadata. There is nothing to install and no SDK required — any language that can make an HTTP request can call it.

Base URL

https://api.tryunfurl.com

Endpoint

POST /api/unfurl

Send a JSON body with the URL you want to unfurl:

{
  "url": "https://example.com/page"
}

If the URL is reachable and well-formed, the API responds in under a second with a normalized metadata object. You can use the response to build a link preview card, validate Open Graph tags, or feed a downstream system like a CMS or social scheduler.

Authentication

The URL unfurl API is open for use from browsers and servers without an API key on the free tier. Requests are authenticated at the origin level and rate-limited per IP address to prevent abuse — see the Rate Limits section below.

For higher-volume or server-to-server integrations, we recommend getting in touch at support@tryunfurl.com to discuss scoped API keys, IP allow-listing, and private rate-limit pools. This is the same pattern used by most social media metadata API providers: start unauthenticated for prototyping, then add a key when you move to production.

Request

All requests are POST with a JSON body:

{
  "url": "https://example.com/page"
}

Headers

Request body fields

Private networks, localhost, and IP literal addresses are blocked at the server for safety — you cannot use the API to probe internal infrastructure.

Response

The API returns a comprehensive metadata object grouping basic HTML meta, Open Graph tags, and Twitter Card data:

{
  "success": true,
  "data": {
    "url": "https://example.com/page",
    "basic": {
      "title": "Page Title",
      "description": "Page description from meta tag"
    },
    "openGraph": {
      "title": "OG Title",
      "description": "OG Description",
      "image": "https://example.com/og-image.jpg",
      "type": "website",
      "siteName": "Example Site"
    },
    "twitterCard": {
      "card": "summary_large_image",
      "title": "Twitter Title",
      "description": "Twitter description",
      "image": "https://example.com/twitter-image.jpg"
    },
    "favicon": "https://example.com/favicon.ico"
  }
}

Any field that is not present on the target page is returned as null or omitted, so clients can fall back through openGraph.title → twitterCard.title → basic.title the same way a real social platform does when it unfurls a link.

Rate Limits

The URL unfurl API uses the same tiered plan structure as the bulk URL unfurl checker:

Rate limit state is returned in the response headers so you can back off gracefully. If you exceed the limit, the API responds with HTTP 429 and the body shown in Error Handling.

Both paid tiers are coming soon — email support@tryunfurl.com to join the waitlist.

Error Handling

If an error occurs, the link preview API returns a consistent shape:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common error codes:

Treat any non-2xx status as a failure and use the error string to show a useful message to end users or log entry.

Code Examples

Here is how to call the URL unfurl API from the most common languages and tools.

cURL

curl -s -X POST https://api.tryunfurl.com/api/unfurl \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/page"}'

JavaScript (fetch)

const res = await fetch("https://api.tryunfurl.com/api/unfurl", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/page" }),
});

const { success, data, error } = await res.json();
if (!success) throw new Error(error);
console.log(data.openGraph.title);

Python (requests)

import requests

res = requests.post(
    "https://api.tryunfurl.com/api/unfurl",
    json={"url": "https://example.com/page"},
    timeout=10,
)
res.raise_for_status()
payload = res.json()
if not payload["success"]:
    raise RuntimeError(payload["error"])
print(payload["data"]["openGraph"]["title"])

PHP

<?php
$ch = curl_init("https://api.tryunfurl.com/api/unfurl");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["url" => "https://example.com/page"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$response["success"]) {
    throw new Exception($response["error"]);
}
echo $response["data"]["openGraph"]["title"];

Use Cases

Teams use the TryUnfurl link preview API for website metadata extraction in a wide range of workflows:

• CMS platforms — auto-generate link previews for content editors when a URL is pasted into a rich-text field.
• Social media tools — validate Open Graph metadata before scheduling or publishing a post, so previews render correctly on Facebook, LinkedIn, Twitter/X, and Slack.
• SEO audit tools — scan pages for missing or misconfigured og:title, og:description, and og:image at scale.
• Chat applications — generate rich link previews inside in-house messaging products without writing your own crawler.
• CI/CD pipelines — automatically verify that Open Graph tags are correct after every deployment, before traffic hits the page.
• GitHub Actions — add a post-deploy step that calls the unfurl API to assert og:image, og:title, and og:description are present and non-empty on key URLs.
• Azure DevOps Pipelines — integrate Open Graph API validation as a release gate so broken previews are caught before production.
• Pre-publish checks — run link preview validation as part of a content workflow to block publishing if required metadata is missing.

Validating link previews in CI/CD pipelines

The TryUnfurl URL unfurl API is designed to be called from automated workflows. A common pattern is to add a post-deployment step that checks critical URLs after each release:

# Example: assert og:image is present after deployment
curl -s -X POST https://api.tryunfurl.com/api/unfurl \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/"}' \
  | jq -e '.data.openGraph.image != null'

This can be added to a GitHub Actions workflow, an Azure DevOps release pipeline, or any shell-based CI step. If the assertion fails, the pipeline fails — catching missing preview metadata before your users share broken links.

Pricing

The URL unfurl API uses a simple, transparent four-tier plan structure:

• Ad hoc (no account) — 30 requests. Available now. Great for prototyping and one-off integrations.
• Free (with account) — 100 requests per day. Available now. Ideal for personal projects and small CMS integrations.
• Paid Basic — 1,000 requests per day. Coming soon. For production social media tools, schedulers, and CMS platforms.
• Paid Enterprise — 5,000 requests per day. Coming soon. For high-traffic integrations, platform partners, and white-label tooling.

Paid tiers are coming soon — email support@tryunfurl.com to join the waitlist or discuss custom limits.

Frequently Asked Questions

What is the TryUnfurl URL unfurl API?

The TryUnfurl URL unfurl API is a REST endpoint that performs website metadata extraction on any public URL. Send a URL, get back Open Graph tags, Twitter Card data, title, description, and favicon in a single JSON response — the same data social networks and chat apps use to build rich link previews.

Do I need an API key?

Not for the ad hoc tier. You can call the link preview API directly from a browser or server with no authentication — up to 30 requests. A free account raises the limit to 100 requests/day. For higher-volume use (1,000 or 5,000 requests/day, coming soon), contact support@tryunfurl.com for early access.

How is this different from scraping pages myself?

The URL unfurl API handles every edge case you would otherwise have to rebuild: SSRF protection, correct User-Agent handling, redirects, character encoding, broken HTML, missing tags, and fallbacks from Open Graph to Twitter Card to basic HTML meta. You get a clean JSON shape in a single call instead of writing and maintaining your own crawler.

Does the API follow redirects?

Yes. The URL unfurl API follows HTTP redirects and returns metadata for the final resolved URL, which is what you want when sharing links that go through shorteners or tracking redirectors.

Can I use it to check my own site's Open Graph tags?

Absolutely — that is one of the most common use cases. Many teams use the Open Graph API in CI/CD to assert that og:title, og:description, and og:image are present on every deployed page. See Validating link previews in CI/CD pipelines above.

What happens if the target page has no Open Graph tags?

The response still returns. The openGraph object will have null fields, and you should fall through to twitterCard and then basic (HTML <title> and <meta name="description">) for a sensible preview. This mirrors what real platforms like Slack, Discord, and iMessage do when they unfurl a link.

Is the URL unfurl API free?

Yes. Ad hoc access (no account) is free up to 30 requests, and a free account raises the limit to 100 requests per day. Paid Basic (1,000 requests/day) and Paid Enterprise (5,000 requests/day) are coming soon.

When will the paid tiers be available?

Paid Basic and Paid Enterprise are coming soon. Email support@tryunfurl.com to join the waitlist for early access.

Need help integrating the TryUnfurl link preview API? Contact us at support@tryunfurl.com — we read every message.