Profiles¶

A Profile is a named, reusable bundle of video settings. Instead of repeating the same choices on every upload — encoding tier, watermark, caption languages, visibility, allowed domains, player — you save them once as a Profile and attach it where you need it.

Profiles are sparse: a Profile carries only the settings it has an opinion on. Every setting a video needs is resolved through three layers, most specific first:

The video's own value — anything you set directly on the video always wins.
The video's Profile — the Profile attached at upload or later (optional).
The project's default Profile — every project has one; it is the last word.

A setting nobody carries falls back to the built-in default (private, full encoding tier, originals kept, no restrictions).

Fixed at encoding vs. live¶

Some settings are consumed while your video is being encoded and are stamped onto it: the encoding tier, watermark, audio normalization, caption languages and the AI flags. Editing a Profile never re-encodes anything — stamped settings only affect videos created after the edit.

Allowed domains, the player and keep-originals are live: they re-resolve on every request, so editing a Profile applies immediately to every video resolving through it. Flip a Profile's player and every attached embed uses it on the next load.

public and folder_id are creation defaults: the Profile decides a new video's visibility and where it is filed, once, at upload. After that both are ordinary video attributes you change on the video itself — editing the Profile never changes existing videos. To flip many at once, use Make public / Make private in the bulk bar.

Settings a Profile can carry¶

Key	Kind	Notes
`encoding_tier`	stamped	`full` or `baseline`
`watermark_id`	stamped	burned in during encoding
`normalize_audio`	stamped	loudness normalization
`auto_tt`	stamped	caption languages; `[]` means "caption nothing"
`auto_chapters`	stamped	chapters generate right after auto-captions complete at ingest
`auto_shots`	stamped	shot detection runs when the encode is ready
`public`	creation default	stamped at upload; floor: private
`allowed_domains`	live	comma-separated registered domains; `""` = unrestricted
`player_id`	live	the player used by embeds
`keep_originals`	live	applies as each video's encode finishes; already-stored originals are never deleted by a profile edit
`folder_id`	creation default	where new videos are filed

The default Profile¶

Every project has a Profile named Default that is created with the project — the project settings page edits it. It cannot be deleted, and it is where project-wide defaults live: what used to be "project settings" for encoding tier, caption languages, allowed domains, keep-originals and the default player is simply the default Profile now.

Using Profiles¶

Create and manage Profiles under Settings → Profiles in the dashboard, or via the API:

curl -u :$API_KEY https://api.heapstream.com/api/v1/project/$PROJECT_ID/profile \
  -H 'Content-Type: application/json' \
  -d '{"title": "Marketing site",
       "player_id": "1234567890",
       "settings": {"public": true, "allowed_domains": "example.com", "auto_tt": ["en"]}}'

Attach one at upload (metadata.profile_id), on fetch, or to an existing video (profile_id on video edit — attaching later applies the live settings immediately, but never re-encodes). Detach with profile_id: 0. To attach a profile to many videos at once — a whole folder, say — select them in the gallery and use Set profile in the bulk bar.

Editing is sparse, key by key:

# set a key, clear another (null = back to "no opinion"), leave the rest untouched
curl -u :$API_KEY -X PUT https://api.heapstream.com/api/v1/project/$PROJECT_ID/profile/$PROFILE_ID \
  -H 'Content-Type: application/json' \
  -d '{"settings": {"public": false, "normalize_audio": null}}'

The same tri-state applies to a video's own dynamic settings: setting keep_originals, allowed_domains or player_id on a video shadows its Profiles for that key; setting it to null clears the video's value so the Profile answers again. public is different — it was stamped at upload and edits simply flip the video itself (null is rejected).

A Profile that videos still use, or that is a project default, cannot be deleted — the API answers 412 with the attached-video count, so a delete can never silently change what a video resolves to.

Limits¶

Up to 100 Profiles per project; titles are unique within a project (up to 100 characters).

July 27, 2026