Skip to content
ScreenCI

Public URLs and Embeds

Public URLs give a ScreenCI video a stable delivery surface outside the app. Once enabled, each selected language gets its own video, thumbnail, and subtitle URL that you can embed in docs, changelogs, support articles, or product pages.

You will learn

What public URLs look like

Public delivery starts from a stable base:

https://api.screenci.com/public/<videoId>

Then each published language exposes:

  • /public/<videoId>/<language>/video
  • /public/<videoId>/<language>/thumbnail
  • /public/<videoId>/<language>/subtitle

The thumbnail comes in three downscaled sizes. Add ?size=sm (small previews), ?size=md (poster, the default), or ?size=lg (full-screen / downloads). See the public delivery API for exact dimensions.

Latest vs selected output

Public delivery can either:

  • follow the latest finished render automatically
  • stay pinned to the exported version you chose to serve for each language

That lets you choose between automatic freshness and manual editorial control.

When a video is made public, ScreenCI starts in automatic mode. The latest finished render for each language becomes the active public output right away.

Enable public delivery in the app

Open the video in the ScreenCI app and turn on Enable public URL.

That does two things:

  1. creates a stable public route for the video
  2. selects the newest finished render for each existing language that has no selection yet

From there, the served version changes only when you say so:

  • run screenci export --select (typically from CI) so each render that run produces replaces the currently served one as it finishes
  • or review versions in the app and pin one per language

How selection works

Public delivery is tracked separately for each language.

  • each language has its own current selected version
  • only finished renders with an actual video output can be selected
  • failed, still-rendering, or deleted versions are never served publicly

An export selects its renders only when run with --select: each finished render then becomes the selected version of its language (and any dependent videos re-render). Exports without the flag, from CI or a laptop, never touch the selection.

To pick a version by hand, open it in the editor sidebar’s Exported group and choose Serve at the public URL. If a language has no selected version, its public URL exists but that language will not resolve to a video until you pick one.

The selected version cannot be deleted while the public URL is on: select another version first, or switch the public URL off.

Per-run (record-pinned) URLs

Alongside the stable URLs above, every media URL has a record-pinned form that adds a records/<recordId> segment to the path, pinning it to a specific screenci export run:

https://api.screenci.com/public/<videoId>/records/<recordId>/<language>/video

The same single Enable public URL switch turns on both the stable URLs and these record-pinned ones. A record-pinned URL is immutable: it serves that run’s own render, or 404s once the run is cleaned up. It never falls back to a different version, and it always honors the public switch, so it also 404s if the video is made private.

ScreenCI keeps only a bounded number of versions per language (the 5 most recent non-selected versions on every plan), so older runs are eventually pruned. To keep a specific run forever, download it via the authenticated URLs in screenci info, described under Keep a render forever.

Use the stable URL when you always want the newest published render, and the record-pinned URL when you want to reference exactly the run a given CI build produced. The screenci info command prints both URL sets (as static and latestRecord) when run on a machine that made the record.

Shared versions (permanent version-pinned URLs)

When you want one exact render to stay online forever, share the version itself. A shared version gets a version-pinned public URL:

https://api.screenci.com/public/<videoId>/versions/<versionId>/video

Share a version from its row menu on the video overview page (Share with public URL), or share a whole export run from CI with screenci export --share. Shared versions show a blue Shared pill in the version list.

Unlike record-pinned URLs, a shared version:

  • is never pruned by version retention; the URL serves that exact render until you unshare or delete the version
  • keeps working even if the video’s own public URL is switched off (only the explicitly shared versions stay reachable)

Your organization can share up to 1000 versions by default; usage and the limit are shown on the billing page, and the limit can be increased by contacting sales. See version-pinned URLs for endpoint details.

Typical embed

<video
  controls
  crossorigin="anonymous"
  poster="https://api.screenci.com/public/YOUR_VIDEO_ID/en/thumbnail"
>
  <source
    src="https://api.screenci.com/public/YOUR_VIDEO_ID/en/video"
    type="video/mp4"
  />
  <track
    kind="subtitles"
    src="https://api.screenci.com/public/YOUR_VIDEO_ID/en/subtitle"
    srclang="en"
    label="English"
    default
  />
</video>

Good use cases

  • product documentation
  • changelog posts
  • support content
  • release landing pages

Privacy and stability

Only enable public URLs for videos that are meant to be accessible publicly. Once enabled, the route is stable by design, even though the selected underlying render can change later.

What’s next