What Is oEmbed?
oEmbed is an open protocol that enables automatic embedding of rich content from one website into another. When you paste a YouTube URL into a blog post editor and it automatically transforms into an embedded video player, that is oEmbed at work. The same protocol powers automatic embeds for Spotify, Twitter/X, Vimeo, SoundCloud, CodePen, and hundreds of other services.
The protocol was created in 2008 and is deceptively simple. It works like this: a consumer (the platform where content is being embedded — Notion, WordPress, Ghost, etc.) encounters a URL it does not recognize as its own content. It checks whether the URL matches any known oEmbed providers (the services that host embeddable content). If there is a match, the consumer sends an HTTP request to the provider's oEmbed endpoint, passing the URL as a parameter. The provider responds with a JSON or XML document containing embed instructions — typically an HTML iframe snippet, along with metadata like title, thumbnail, width, and height. The consumer then renders the embed inline.
The entire exchange happens server-side, in the background, in milliseconds. The end user just sees their pasted URL transform into rich embedded content. No embed codes to copy. No iframe HTML to write. Just paste a URL.
How GeometryViewer Implements oEmbed
GeometryViewer operates as an oEmbed provider. Our oEmbed endpoint is available at https://geometryviewer.com/oembed. When a consumer platform sends a request to this endpoint with a GeometryViewer model URL, we respond with the embed data needed to display an interactive 3D viewer.
The request format follows the oEmbed specification. A consumer sends a GET request like: https://geometryviewer.com/oembed?url=https://geometryviewer.com/view/abc123&format=json. We respond with a JSON object containing the embed type ("rich"), the HTML for an iframe embed, the model title, a thumbnail image URL, and the recommended dimensions.
The response includes an iframe that loads GeometryViewer's embed page with the model pre-loaded. The iframe is fully interactive — users can orbit, pan, zoom, and (on supported devices) launch AR. The embed is responsive, adapting to the container width while maintaining aspect ratio. It loads lazily, only initializing the WebGL context when the iframe enters the viewport.
We also provide oEmbed discovery via HTML <link> tags in the head of every model page. This means that even consumer platforms that do not have GeometryViewer in their provider list can discover our oEmbed endpoint automatically by fetching the model page and reading the link header. The discovery link looks like: <link rel="alternate" type="application/json+oembed" href="https://geometryviewer.com/oembed?url=...">.
Which Platforms Support It
oEmbed support varies by platform. Here is the current state of GeometryViewer embeds across popular platforms:
- Notion — Full support. Paste a GeometryViewer URL and Notion automatically creates an interactive 3D embed block. This works in both pages and databases. The embed is interactive and resizable.
- Ghost — Full support. Ghost's editor recognizes GeometryViewer URLs and creates embedded 3D viewers. The embed appears as a rich card in the editor and renders as an interactive viewer on the published page.
- WordPress — Supported via oEmbed allowlist. WordPress maintains a list of trusted oEmbed providers, and site administrators can add custom providers. Once GeometryViewer is added to the allowlist, pasting a model URL in the block editor creates an automatic embed. Self-hosted WordPress sites can add our provider via the
wp_oembed_add_providerfunction infunctions.php. - Medium — Partial support. Medium supports oEmbed for select providers. GeometryViewer embeds appear as rich link cards with a thumbnail and title. Clicking through opens the full interactive viewer on geometryviewer.com.
- Slack — Link preview support. When you paste a GeometryViewer URL in Slack, it shows a rich preview with the model thumbnail, title, and a link to view. The preview is not interactive (Slack does not render iframes in messages), but it provides a clear visual representation.
- Discord — Similar to Slack. Rich link preview with thumbnail and title. Not interactive inline, but provides a good visual preview.
- Confluence — Supported via the oEmbed macro or custom macro. Atlassian products support custom oEmbed providers through admin configuration.
How to Test oEmbed
You can test our oEmbed endpoint directly by sending a request to it. Using curl: curl "https://geometryviewer.com/oembed?url=https://geometryviewer.com/view/YOUR_MODEL_ID&format=json". The response will be a JSON object with the embed HTML and metadata. You can also use online oEmbed testing tools — search for "oEmbed tester" and paste a GeometryViewer model URL.
For testing in a specific platform, the simplest approach is to upload a model to GeometryViewer, copy the URL, and paste it into the platform's editor. If oEmbed is working, the URL will transform into an embed within a second or two. If it remains as a plain link, the platform either does not support oEmbed, does not have GeometryViewer in its provider list, or blocks iframe embeds from unknown domains.
Adding GeometryViewer to Your Platform's Allowlist
If you are a platform developer or administrator and want to enable automatic GeometryViewer embeds, there are three approaches depending on your platform's architecture.
Provider list approach
Most CMS platforms maintain a list of trusted oEmbed providers. To add GeometryViewer, add an entry with our endpoint URL (https://geometryviewer.com/oembed) and a URL scheme pattern (https://geometryviewer.com/view/*). In WordPress, this is done with wp_oembed_add_provider('https://geometryviewer.com/view/*', 'https://geometryviewer.com/oembed').
Discovery approach
If your platform supports oEmbed discovery (fetching the target page and reading the <link rel="alternate" type="application/json+oembed"> tag), GeometryViewer embeds will work automatically without any configuration. Many modern platforms support discovery as a fallback when the URL does not match any known provider. Enable discovery in your oEmbed consumer implementation if it is not already active.
Iframe allowlist approach
Some platforms render oEmbed HTML but restrict which domains can appear in iframes. If your platform uses a Content Security Policy (CSP) or iframe sandbox, add geometryviewer.com to the allowed frame sources. The specific directive is frame-src https://geometryviewer.com in your CSP header.
For Platform Developers
If you maintain a CMS, knowledge base, or documentation platform and want to add GeometryViewer to your oEmbed provider list, reach out to us. We can provide technical documentation, test URLs, and assist with integration testing. Our endpoint follows the oEmbed 1.0 specification exactly, with both JSON and XML response formats available.
Technical Details for Developers
Endpoint specification
Our oEmbed endpoint accepts the following parameters:
- url (required) — The GeometryViewer URL to embed. Must match the pattern
https://geometryviewer.com/view/*. - format (optional) — Response format. Values:
json(default),xml. - maxwidth (optional) — Maximum width in pixels. The embed will not exceed this width. Default: 800.
- maxheight (optional) — Maximum height in pixels. Default: 600.
The response includes type: "rich" (indicating an interactive embed rather than a simple photo or video), version: "1.0", title (the model name), thumbnail_url (a static screenshot of the model), thumbnail_width and thumbnail_height, html (the iframe embed code), and width and height (the iframe dimensions respecting maxwidth/maxheight constraints).
Iframe embed behavior
The iframe loads a lightweight embed page that initializes the 3D viewer with minimal UI. It includes orbit controls, a loading spinner, and an optional AR button. It does not include the full GeometryViewer header, navigation, or upload interface — just the viewer. The embed page communicates with the parent frame via the postMessage API for resize events, allowing responsive layouts.
Caching and performance
Our oEmbed endpoint returns standard HTTP cache headers. Responses are cached for 24 hours at the CDN level. Consumer platforms typically cache oEmbed responses as well (WordPress caches them for 24 hours by default). The thumbnail image is generated server-side when a model is first uploaded and served from our CDN. The iframe embed page itself is cached aggressively and loads in under 200ms on typical connections.
Beyond oEmbed: Open Graph and Twitter Cards
oEmbed handles rich interactive embeds, but not every context supports it. For social media shares, messaging apps, and SEO previews, we also implement Open Graph (OG) meta tags and Twitter Card tags on every model page. When you share a GeometryViewer URL on LinkedIn, Facebook, Twitter/X, or in a messaging app, the link preview shows the model thumbnail, title, and a description. This complements oEmbed — you get rich embeds where the platform supports it and attractive link previews everywhere else.
The combination of oEmbed, Open Graph, and Twitter Cards means that a single GeometryViewer URL adapts to every context. In Notion, it becomes an interactive 3D viewer. In Slack, it becomes a rich preview card. On Twitter, it becomes a large image card. On a raw web page, the URL itself works as a link. One URL, every platform, no manual embedding required.