Additional API parameters

Together with your API settings, optional query-string API parameters help you fine-tune what you receive from APIs.

If not given with an API call, your defaults from settings will be used. If you haven't set up and saved your preferences at least once, the default cloud-wide settings will be used.

There's also URL Options editor for your articles that adds provider-specific _-prefixed parameters, so that your authors can fine-tune individual rich media in their posts.

Required parameters


The API key you see in your profile. If your code faces users, you may replace api_key with key parameter, which should be the MD5 hash of your actual API key.

See how to restrict API access with your key in that case.

URL-encoded value of the URL. Also, make sure it's HTTP or HTTPs link (we suggest you match against /^https?:\/\//i)

Please URL-encode the URLs you send to Iframely. Seriously.

iFrame helpers & features


Explicitly activates our async iFrames.

Embed will be wrapped into Iframely iFrame and include required display helper. The media inside an iFrame will be kept up-to-date in background on our end.


Wraps rich media into a summary card. Works for players, images and some apps.

Use &iframe=card-small to insist on a compact card layout.


Disables any required or configured Iframely HTML helpers powered by our iFrames.

You get embed codes from publisher as-is and need to take care of any technical matters yourself. The autoplaying videos will be omitted in oEmbed API response.

Formats HTML code output for Accelerated Mobile Pages framework. See our AMP guide

If your plan supports it, or during initial trial period, the parameter adds Content ID to the API response. For all cases, including when Iframely returns native embed code from publisher as-is, without hosted iFrame.

You can use those IDs to re-fetch data in batches of up to 100 URLs when you need to refresh the cache.


Excludes embed.js from HTML codes, if you load it yourself.

It also forces script-based embeds with variable height (say, Twitter and Facebook) be returned as <iframe> instead of <a> element. (useful e.g. for React)

In Chrome, when embed code has our embed.js script, it may decide to use Web Components instead of iFrames to bulk-insert some embeds and make it even faster. import=0 disables shadow DOM and imports and our script will use iFrame renders only.

Formats HTML with CSS classnames instead of inline styles.

Also lets you fine-tune embed codes via CSS. It will add iframely-embedclass, rel classes such as iframely-player, and domain classes such as iframely-youtube

Removes default center aligning of Twitter, Facebook, Instagram and other max-width'ed media embeds.
Activates Player.js events to control players where possible. Requires and is delivered via Iframely iFrame helper.
Activates lazy-loading when Iframely returns an iFrame helper.

Content filters


Accept-Language - default is en-US. Sets rich media interface language for number of publishers. For all publishers, makes Iframely parsers to request HTTP responses in that locale as top choice in accept-language header (many sites render different meta depending on locale).

The parameter value is an ISO 639-1 fully specified locale of two-letter language code and two-letter region code. For example, fr-CA or fr-FR are both valid values. For some languages, Iframely might accept just the two-letter language code and add the default region code automatically.

Please test your locale choice with Twitter, Facebook, YouTube and TED before pushing it live. Instagram should also use either this language, or the one from user's browser.

Returns only embeds that can be used under HTTPs without our iFrame fallbacks and with no active SSL mixed-content warnings (images and mp4 videos trigger only passive warnings and thus will pass this check).
Returns only embeds that can be viewed without our iFrame fallbacks on mobile devices or desktops with no Flash plugin installed.
"Prefer media-only". For some publishers, Iframely knows status-like app embeds AND simple media, such as photos or video. This option will make Iframely return actual media in the html field instead of branded embeds. It affects, for example, Instagram, Tumblr, Imgur, Pinterest (for videos), etc.
Disables any rich media from a publisher and forces URL to try and resolve into a summary card instead.
Activates Autoplay for players when possible. Check for autoplay in primary rel to confirm. Add &mute=1 to mute the playback.
In pixels, returns only embeds that do not exceed the requested width. It affects the rare cases of fixed-width embeds as in most cases Iframely gives the responsive embed code anyway.

maxwidth doesn't restrict the size of responsive media because many WordPress sites have this setting wrong. Use omit_css instead.


Integer in pixels (without unit of measure, as e.g. =600), or as a percent of viewport height (with unit, as in =100vh).

Parameter applies only in the following cases:

For responsive apps, players and images with fixed aspect-ratio: Iframely takes maxheight and media's aspect-ratio and calculates the max width that would match your maxheight. We then set the max-width style in HTML output so that responsive media isn't taller than your maxheight.

For HTML-based embeds like Twitter, Facebook, Instagram, Gists whose height is calculated during renders, and only when used with Iframely iFrames: the maxheight= parameter in pixels is respected and such widget won't exceed the requested height. Instead, once the maxheight is reached, Iframely iFrame will start showing a scrollbar.

Maxheight is ignored in all other cases.

Code helpers


Optional text value tag that will help you later search links in your dashboard. It represents the hashtag to group your links. E.g. project or chat room name, category, app, if you got several, etc.

You may also use it to indicate your end-customer. In that way you'll be able to make a requests to our support to delete all links by such hashtag from your account. It addresses the "right to be forgotten" act in European GDPR.

Name of a JavaScript function, if you’d like response to be wrapped as JSONP.
For oEmbed API only, if you'd like to get your response as XML.

Adds title attribute to all iFrames in the embed codes (hosted or native). Use this if you need to meet Level AA of Web Content Accessibility Guidelines (WCAG) 2.1.

For <a>-based hosted code, it adds title as the content of <a>...</a> tag. Use this if your CMS sanitizes links with no content or if you have SEO concerns. This title also makes the links that are no longer available at the origin (e.g. 404) to keep falling back to a regular HTML link (otherwise Iframely removes such N/A widgets by default).

For individual embeds publishers

Number of publishers provide different embedding options. By default, Iframely provides embeds that we believe are the best fit for most common use cases. But you, of course, might want it differently.

Most frequently requested adjustments are available for self-service in your settings. For other cases, Iframely team can configure the exact embeds you like for your favourite publishers. Ask away.

For individual URLs

_ ... =

In addition your default account's settings and parameters, your users may choose embed's settings for ab individual URL to get exact variant they need for their specific post.

Add our URL Options editor to your site, and make it shine in a whole new way. Iframely will suggest additional query-string parameters for each URL and rich media publisher, all starting with underscore _ prefix.

You give these options to your editors to choose from, then repeat requests to Iframely APIs with the chosen query-string for a specific rich media variant.

Read the details.

Previous article: Iframely API
Next article: Result codes