Developers

Embedding Stillhaven video

A share link, an embed code, and an oEmbed endpoint. Which one you use depends on where the video is going.

The share link

Every published video has a page of its own on https://play.stillhaven.io. Paste the link in an email, a message, or a document, and the reader gets the video on a clean page with your branding. Paste it into an editor that understands oEmbed, and the reader gets the player right there.

https://play.stillhaven.io/s/stillhaven-videos/aeaefa8d799f8877

Turn the share page off in the console and this link stops working; the video then plays only where you embed it.

The embed code

Copy it from the video's page in the console. It is a responsive wrapper around an iframe, and it works on any page that accepts HTML: WordPress, Webflow, Kajabi, Teachable, a custom HTML block in Circle, or your own site.

<div style="position:relative;width:100%;aspect-ratio:16/9;">
  <iframe src="https://play.stillhaven.io/e/stillhaven-videos/aeaefa8d799f8877"
          title="Stillhaven is for course creators"
          style="position:absolute;top:0;left:0;width:100%;height:100%;border:0;"
          allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>
</div>

The /e/ address is the player alone, with no page around it. It is meant to sit inside an iframe and is not a link to share.

Allowed domains

On every paid plan, each video can carry a list of the domains where its embed may play. Paste the embed code anywhere else and viewers see a quiet blocked screen instead of the video. Set it per video, or once for the whole library.

The check reads the referrer of the page that framed the player. Some editors wrap players in a frame of their own that sends no referrer at all; Circle's embed service is one. Each video's unknown-origin setting decides that case: lenient, the default, plays; strict blocks.

Products built on Iframely, among them Notion, HubSpot and most rich-link editors, frame the player from Iframely's own hosts (iframely.net, cdn.iframe.ly), so a video locked to your site is blocked there even though your page is the one showing it. Tick Allow embeds through Iframely under the video's Allowed domains, or in the account default, and those hosts are allowed without listing them.

oEmbed

Editors that resolve a pasted link, among them Circle, Notion, WordPress and Slack, ask the provider for oEmbed. Stillhaven answers at:

GET https://play.stillhaven.io/oembed?url=https%3A%2F%2Fplay.stillhaven.io%2Fs%2Fstillhaven-videos%2Faeaefa8d799f8877

Share pages also carry the discovery tag, so an editor that follows <link rel="alternate" type="application/json+oembed"> finds the endpoint on its own.

Parameter	Meaning
`url`	Required. A share link or embed address on https://play.stillhaven.io. Anything else is a 404.
`maxwidth`, `maxheight`	Optional. The response is scaled to fit, keeping the video's aspect ratio.
`format`	Optional. Only `json`; `xml` answers 501.

The response is an oEmbed video object: the iframe as html, its width and height, the poster as thumbnail_url, and cache_age of an hour. A video that needs a password, or whose share page is off, answers 401. A video that does not exist, or has been removed, answers 404. The endpoint sends Access-Control-Allow-Origin: *, so a browser may call it directly.

{
  "version": "1.0",
  "type": "video",
  "provider_name": "Stillhaven",
  "provider_url": "https://stillhaven.io",
  "title": "Stillhaven is for course creators",
  "author_name": "stillhaven-videos",
  "html": "<iframe src=\"https://play.stillhaven.io/e/stillhaven-videos/aeaefa8d799f8877\" width=\"1920\" height=\"1080\" ...></iframe>",
  "width": 1920,
  "height": 1080,
  "thumbnail_url": "https://play.stillhaven.io/p/stillhaven-videos/aeaefa8d799f8877",
  "thumbnail_width": 1920,
  "thumbnail_height": 1080,
  "cache_age": 3600
}

The REST API, for listing videos and reading their embed codes from your own code, is documented at /docs/api.