Put your content anywhere

1. Paste a link — nothing else

Paste a bare episode URL on its own line and a surprising number of editors replace it with the live player automatically. That is the oEmbed protocol, and Demades has been an oEmbed provider since the widget shipped:

https://demades.ai/e/my-episode-1a2b3c4d

Which platforms do it automatically

oEmbed consumers come in two kinds, and the difference decides whether a bare link is enough:

• Discovery-based consumers unfurl automatically. They read the <link rel="alternate" type="application/json+oembed"> tag in our page head and follow it. That covers self-hosted WordPress, Ghost, Confluence, and most CMSs built on oEmbed discovery.
• Allowlist-based consumers need the provider registered. Discord, Slack, WordPress.com and Notion only unfurl providers on a list they maintain. Demades is not in the public oEmbed provider registry yet, so on those platforms use the iframe below — it always works.

Everywhere else, a pasted link still unfurls the standard share card (title, description and cover art) — never a bare URL.

2. Or paste the iframe

Works on every platform that allows an iframe, including the ones above that will not auto-unfurl. Copy it from any episode page's Embed button, or build it by hand:

<iframe src="https://demades.ai/embed/my-episode-1a2b3c4d"
        width="100%" height="180"
        style="border:0;border-radius:12px;max-width:560px"
        loading="lazy" title="My episode — Demades"
        allow="autoplay; clipboard-write; encrypted-media"></iframe>

What each attribute is for

3. What you can embed

Only published episodes embed. A private, unlisted or still-rendering episode returns nothing at all — the embed route cannot be used to probe for content that is not public.

4. Sizing and responsiveness

• Default box: 480×180. Height 180 is the one number to keep.
• Narrow columns are fine. The player has been verified down to a 280 px column; below roughly 240 px the episode title starts to ellipsize, which is cosmetic — the transport still works.
• Full-width layouts: keep width="100%" and set a max-width so the player does not span a 1400 px hero.
• List embeds are taller. A show embed carries a cover, several rows and one shared transport, so it wants 480×300 rather than the single-episode 480×180.
• Two max-widths, both deliberate. The copy-paste snippet uses 560px (roomier, sized for a blog column); the oEmbed descriptor declares 480px, because a consumer needs one numeric box to lay out against. Either way the player is fluid — the number is an aspect hint, not a fixed size.
• Do not put it in a fixed-height flex or grid cell shorter than 180px — the widget cannot grow its own frame, so it clips.
• Dark and light both work: the player ships its own dark chrome and does not inherit your page's theme, so it looks identical on either.

5. The oEmbed endpoint

If you are building the integration yourself, call the provider endpoint directly. It is public, needs no key, and does no I/O beyond resolving the episode:

GET https://demades.ai/api/oembed?url=<public page URL>

The response

A standard oEmbed rich descriptor. The fields that matter:

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "Demades",
  "provider_url": "https://demades.ai",
  "title": "",
  "author_name": "Demades",
  "html": "<iframe src=\"…/embed/<slug>\" …></iframe>",
  "width": 480,
  "height": 180,
  "thumbnail_url": "…/e/<slug>/og.png",
  "thumbnail_width": 1200,
  "thumbnail_height": 630,
  "cache_age": 86400
}

Render html as-is — it is the same player, already escaped and sized. An unknown, private or deleted target returns 404, never a partially-filled descriptor.

6. Attribution and referrals

Every embed is a link home: the brand chip and the episode title both open demades.ai in the top-level window, breaking out of the frame rather than navigating inside your page.

If you have a referral code, put it on the iframe src — once, on the embed itself:

https://demades.ai/embed/my-episode-1a2b3c4d?ref=YOURCODE&utm_source=embed&utm_medium=widget&utm_campaign=embed-episode

• You tag the embed once, not every link. The player carries ref onto every way out of it — the brand chip, the episode title, each row of a list embed, and the closing call to action — so one pasted URL attributes every click that leaves it.
• ref is the one that pays, and it is captured first-touch: the first code a visitor arrives with wins and is remembered for 90 days, so credit survives someone hearing your embed today and signing up next month. Codes are short and alphanumeric, matched case-insensitively.
• A code is never invented. If the embed URL carries no ref, the links leaving it carry none either — Demades will not attribute a visit to a code you did not actually publish.
• The utm_* tags ride the outbound links whether or not you set a ref, so embed-driven traffic stays distinguishable in analytics even when nobody is being paid for it. utm_campaign takes the form embed-<surface> — embed-episode, embed-show, embed-clip, embed-creator, embed-playlist.

Your code lives on your referral overview and on the invite card in settings — this is the same referral rail as an invite link, not a separate program to sign up for.

7. Things worth knowing

• A deleted episode degrades gracefully. If an episode you embedded is later removed, the frame renders a small branded card pointing at the catalog — never a raw error, never a broken box on your page.
• The embed will not compete with you in search. The player is noindex and points its canonical URL at the episode page, so embedding does not create a duplicate of your page.
• Every player says what it is. The AI-generated disclosure is part of the player chrome and cannot be switched off — that is deliberate, and it travels with the embed onto your site.
• Nothing tracks your readers. An embed that is only seen loads no audio and records no play; a play is counted when someone actually presses play.

Every episode is AI-generated by Demades.