1. Docs
  2. Getting started

Let’s connect

If you know where you are heading to, use links to the left. Otherwise, read on.
This introduction gives the same links in proper context.

Basic flow

Iframely takes your URL as an input, fetches its semantics from the origin server and tries to return rich media embed codes and other URL data. If successful, you’ll get html as embed code that follows your API settings and optional query-string parameters. If the request fails, you’ll get an error code and a message.

API endpoint

Iframely API follows JSON format. There are (just) two API endpoints available: one follows oEmbed spec, another provides detailed Iframely data. Think of it as the <head> of the origin URL with <meta> and media <link>s.

oEmbed is excellent for simple embedding. Iframely data brings more URL meta and details about rich media types & feature flags.

Embed.js lets you use Iframely without API calls.

What URLs to send

We suggest you send everything you have. Iframely knows rich media from over 1900 domains but recognizes thousands more. We offer that you control what you get by allowing rich media types.

What to expect as output

Rich media from third-party publishers comes in a variety of types. Many rich media embeds can be used as-is. Some may require an Iframely-hosted iFrame helper to display correctly. For example, React does not add third-party scripts, and you will need to omit scripts.

Hosted iFrames deliver Iframely interactives such as summary cards, click-to-play and player events.

Customize & fine-tune

You can control every aspect of Iframely via your settings, API query-string parameters and WYSIWYG editors. Initially, your account is configured for the most common use cases.

You can give your authors our URL options for individual URLs to choose the media variant just the way they want it.

Deliver the content

You should cache API responses, including error codes, on your end and refresh your local data periodically. We recommend cache time-to-live of 1 to 24 hours.

You can have longer TTLs if you use hosted iFrames because Iframely will keep updating its rich media for you in the background. You may deliver iFrames via your own CDN.

For CMS use, we recommend our content IDs so that you can refresh Iframely data in batches of up to 100 URLs in your articles. Otherwise, we recommend that you manage your origins.

Available integrations & guides

Some Iframely integrations are available. WordPress plugin, Meteor package, Medium–like text editor add-on, CKEditor supports Iframely, NodeBB forums, to mention a few. There are also integration guides for React, Angular and AMP.

Become a publisher

Learn about our robot and how to recognize and allow it on your network. Publish your rich media for Iframely. If you already provide embed codes for your users, submit your site as a provider.