1. Docs
  2. API endpoints

oEmbed API endpoint

One of the (only) two Iframely endpoints follows the oEmbed protocol:

  • You make an HTTP GET request with your link as the &url= query-string parameter.
  • If any, HTML embed code is in the html field of JSON response.

The html and rich media content depend on your API settings and optional request parameters.

If we cannot find third-party rich media for your URL, we will prepare a summary card. We deliver it via a hosted iFrame. You may request to get an iFrame every time if you need any other technical improvements or Iframely interactives it brings.

API request

  • url and api_key parameters are required.
  • url needs to be URL-encoded.
  • For additional security, you may substitute api_key with the key parameter. It should be the md5 hash value of your actual API key (see Allow origins guide).
  • There are also other optional query-string parameters available.

If you make API calls for each user via client-side JavaScript, use our CDN at cdn.iframe.ly/api/oembed/….

If you use Content IDs, you can repeat the API call at iframe.ly/{ID}.oembed. You can even fetch data in batches of up to 100 content IDs, separated by - hyphen.

API Response

Iframely responds with a JSON that has a top-level html field for embed code and other oEmbed-specific data.

Here’s an example response for Vimeo:

{
  "url": "https://vimeo.com/141567420",
  "type": "video",
  "version": "1.0",
  "title": "Input/Output",
  "description": "A new short from Terri Timely and Park Pictures",
  "author": "Terri Timely",
  "author_url": "https://vimeo.com/user1946955",
  "provider_name": "Vimeo",
  "thumbnail_url": "https://i.vimeocdn.com/…5aebf015a6472-d_295x166",
  "thumbnail_width": 295,
  "thumbnail_height": 166,
  "html": "<div style="left: 0px; width: 100%; height: 0px; position: relative; padding-bottom: 56.25%;"><iframe src="https://player.vimeo.com/video/141567420" style="top: 0px; left: 0px; width: 100%; height: 100%; position: absolute;"></iframe></div>"
}

Iframely supports photo, video and rich types as oEmbed output.

For valid links, oEmbed API returns link type object and URL data when Iframely doesn’t have any embed code for your URL. You can also get an error code if URL fails.

Beware: photo type in oEmbed spec provides url as a hotlink to the image, no html.

On plans that support it, Iframely also returns options object. Use it to pass URL embed options to your authors.

Docs