Attach media with Promo API

Promo API gives you ability to attach rich media to your URL and get a media card as embed code. In a sense, Iframely will merge the two links in the following way:

  • semantic attribution meta and click-through link - from original URL,
  • rich media and thumbnail images - from promo URL, for example a friendly GIF
  • result embed code will be a promo card

Define media via promo parameter

Add &promo= parameter in your API calls to oEmbed of Iframely endpoints to merge the two links together.

promo should be an URL-encoded canonical link to exact rich media, say YouTube or Vimeo or any of over 1900 domains that Iframely supports.

If Iframely finds players or images (not just thumbnail images) for your promo URL, it will add it to your own source &url= and will return a Promo Card as HTML embed code.

To make your promo cards accessible to apps outside of Iframely ecosystem, you need to publish it as oEmbed. See for spec details.

It is simple: you just add an oEmbed discovery link into the <head> section of your page's HTML:

<link rel="alternate" type="application/json+oembed" 
href="{your page URL here}&promo=...&api_key=..." />

<link rel="alternate" type="application/xml+oembed"

Replace ... with the actual values of your own page and media attachment. You can skip &promo= link if you already publish it in your meta.

Try it now

Check out our Klip To demo app to attach media manually and have some fun experimenting with this feature.