oEmbed
Definition
oEmbed is a short specification, first published in 2008, for converting a URL into embeddable markup without anyone copying an embed code by hand. A consumer — WordPress, Notion, Discourse, a CMS — takes a pasted link, asks the publisher's oEmbed endpoint about it, and receives JSON back. That JSON carries a type of photo, video, link or rich, a title, an author, thumbnail details, and for the video and rich types a ready-made html string containing an iframe. The consumer drops that html into the page. Discovery usually happens through a link tag in the publisher's page head with rel set to alternate and type set to application/json+oembed, pointing at the endpoint; some consumers instead keep a hard-coded list of URL patterns they trust.
Why It Matters
oEmbed is the difference between a bare blue link and a playable video in someone else's post. If the platform you publish to supports it, your work appears inline wherever it is shared, with a title and a thumbnail, and you never have to explain to a client how to paste an iframe. The catch matters just as much: serving oEmbed requires a program that reads a query string and returns different JSON for every URL, which a static file host cannot do. Knowing that in advance saves an afternoon of wondering why the endpoint returns the same file every time.
How It Works
The consumer builds a request such as https://publisher.example/oembed?url=THE-PAGE&format=json and performs a GET. The publisher's server parses the url parameter, looks up the matching content, and returns a JSON object with version 1.0, a type, and the fields that type requires — width and height for photo and video, an html string for video and rich. Optional maxwidth and maxheight parameters ask the publisher to scale the markup down. A 404 means the URL is not embeddable and a 501 means the requested format is unsupported. On a static host such as 99helpers there is no process to answer that request, so the practical route is the other direction: publish clean Open Graph tags so consumers can build a preview from the page itself, and hand out an iframe embed for anyone who wants the live thing.
Real-World Example
A studio publishes an interactive chart at metrics-2026.99helpers.site and wants it to appear inside a client's Notion page. Pasting the address gives Notion nothing to expand, because there is no endpoint to ask. Pasting the same address into Notion's own embed block does work, because that block builds a raw iframe rather than negotiating with the publisher. The studio adds a one-line snippet to its handover note, and the chart renders live inside the client's document at 900 pixels wide.
Common Mistakes
- ✕Expecting a static host to serve an oEmbed endpoint — it needs server code that reads a query string, which plain file hosting does not run
- ✕Returning the html field over plain HTTP while the consuming page is on HTTPS — browsers block the mixed content and the embed shows as empty space
- ✕Leaving out the discovery link tag and assuming consumers will guess the endpoint address — most will not even look
Related Terms
Embed Code
An embed code is a snippet of HTML you paste into a page so that content hosted somewhere else appears inside it. Most embed codes are an iframe; some are a script tag.
iframe Embed
An iframe embed places another web page or file inside a rectangle on your page, as a separate document with its own address. It is the usual way to show a hosted PDF, map or demo in place.
Social Preview
The card a social platform builds from your page's tags when someone posts your URL — an image, a headline and a line of text instead of a bare address. You control it by what you put in the page head.
Open Graph Tags
Meta tags in the head of a page that tell other sites how to draw a link to it — the title, the summary and the picture in a shared card. Without them a link shows as a bare URL.
Query String
A query string is the part of a URL after the question mark, carrying key-value pairs such as src=newsletter and page=2. It passes small pieces of data along with the request.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →