This is the engine behind the Iframely service. Give it a URL and it returns the metadata: title, description, thumbnails, author, canonical URL. If allowed, and if the provider supports it, you also get embed HTML for videos, posts, maps, slideshows, etc.
This engine has powered Iframely in production since 2013. Use it if you’d like to self-host rather than rely on the cloud version.
Iframely uses two kinds of parsers.
Custom domain plugins handle specific providers, from YouTube to Google Maps. You'll find them in the /plugins/domains folder.
Generic parsers read standard markup like oEmbed, Open Graph, Twitter Cards and JSON-LD.
Domain plugins work for the providers they cover. For everything else, the generic parsers only return rich media embeds for providers on the allowlist. We maintain that list for both the open-source and cloud versions, and it's synced to your instance by default. If you'd rather curate your own, you can swap in your own allowlist.
Any other URL still returns metadata and thumbnails, if available.
Some additional plugins are private and only used in the cloud. You can write your own for your instance.
There are two endpoints. Both take url and return JSON:
{your.server}/iframely?url=returns the Iframely format. It looks like the<head>of a page:metafor data,linksfor media.{your.server}/oembed?url=returns a simplified oEmbed version of the same data. It's an adapter, so the engine does the same work for both endpoints.
There's also a visual debugger at {your.server}/debug.
Sample responses from the cloud API: Iframely format and the same URL as oEmbed.
You'll need Node.js 20.19.3 or later.
Start with the install and configuration guide. Then see link rels and types and meta semantics for what comes back.
Coming from a version before 2.0.0? Here are the migration steps.
The Iframely cloud Preview APIs run on the same parsers and the same allowlist, so responses match apart from minor differences. If you keep the default allowlist, coverage is almost the same, apart from the private plugins.
The cloud also adds:
- Hosted iframe rendering in the
htmlfield: preview cards, GIF support, player events, AMP and more. - Per-URL options, predictive sizing to reduce layout shift, lazy-loading and media allowlists by type.
- The Data API, for apps that process URLs automatically (assistants, search, AI). It builds on the preview data and adds entities, excerpts and full text where the provider allows it.
Issues and pull requests are welcome. Please open PRs against develop. Everything lands there before it goes to master. Contributions are under the same MIT license. Questions: support@iframely.com.
MIT License. © 2012–2026 Itteco Software Corp. Nazar Leush, Ivan Paramonau and the contributors.