Folders¶

Folders organize your video library the way a file system does: a video lives in at most one folder, folders nest up to 5 levels deep, and a project holds up to 200 folders in total. Folders are private organization only. Being in a folder never changes who can watch a video, and links, embeds and playback are unaffected. For cross-cutting labels that a video can carry several of, use tags instead.

Browsing folders in the dashboard¶

The Videos page doubles as the folder browser. Folder tiles sit above the video grid: each tile shows the folder's color, poster thumbnails from up to 3 of its newest videos, its direct video count and its subfolder count. Click a tile to open the folder; a breadcrumb trail at the top walks back up, and a Not in a folder tile at the root collects the videos you haven't filed yet.

A folder shows its direct contents: its own videos plus its child folders. The search box inside a folder searches that folder's videos, and folder titles matching a search appear as tiles above the results.

To move a video, drag its tile onto a folder tile (or onto a breadcrumb entry, including All videos to un-file it). To move many at once, select them and use Move to folder in the floating bulk bar; both paths are described in the Videos page. You can also set the folder on a video's edit page. To apply a settings profile across a folder's videos, open the folder, select them, and use Set profile in the same bulk bar.

Creating and managing folders¶

Folders are created and managed right on the Videos page. ＋ New folder (above the folder tiles) opens a dialog: a title, an optional description, a preset color, and the parent — pre-filled to the folder you're standing in, so a folder is created where you are unless you pick another spot. All folders beside it shows the whole tree with per-folder video counts; click a row to jump there.

To edit a folder, hover its tile and click the pen — or use the pen next to the folder's name in the breadcrumb when you're inside it. The same dialog renames, recolors, or moves the folder under another parent. Moving a folder takes its subfolders with it; a folder cannot be moved into its own subtree, and a move that would exceed the 5-level depth is refused. Sibling folders must have distinct titles; the same title can exist under different parents.

Delete folder sits inside the edit dialog. Deleting a folder moves it and all its subfolders to Recently deleted, where they can be restored for 31 days. The videos inside are kept and moved out of any folder, unless you tick "Also delete the videos inside", which deletes them the same way deleting each video would — those videos land in Recently deleted alongside the folder and come back with it when you restore it.

Publish as a showcase¶

Any folder can be published as a showcase: a public, branded page showing every video in the folder and its subfolders at one shareable link, with public, unlisted, or password privacy. Open the folder and click the screen icon next to its name to set one up — filing and moving videos is all the curation there is.

Uploading into a folder¶

The upload page has a Folder select: every video uploaded or fetched on that page lands in the chosen folder. Opening the upload page from inside a folder pre-selects it (the button reads "Upload to X"). On the API, pass metadata.folder_id on direct upload or fetch.

Folder analytics¶

The analytics page's folder filter scopes every metric to a folder and all of its subfolders. Attribution happens at view time: a view belongs to the folder the video was in when it was watched. That means folder analytics start when a video is filed; views recorded before that (or before folders existed) are not included, and moving a video does not move its history. There is no "Not in a folder" analytics option for the same reason.

API¶

Folders are a project-scoped resource with the usual five operations. The list returns every folder as a flat array; build the tree from each row's parent_id (null means a root folder). It is not paginated, since a project holds at most 200 folders.

Create a folder (optionally nested, with a preset color):

curl -u :$API_KEY -H 'Content-Type: application/json' \
  -d '{"title": "Product", "color": "#009ef7"}' \
  https://staging.heapstream.com/api/v1/project/$PROJECT_ID/folder

List folders (each row carries video_count and up to 3 poster thumbnails):

curl -u :$API_KEY https://staging.heapstream.com/api/v1/project/$PROJECT_ID/folder

Rename a folder, or move it by setting parent_id (0 or null moves it to the root):

curl -u :$API_KEY -X PUT -H 'Content-Type: application/json' \
  -d '{"parent_id": "91882736402"}' \
  https://staging.heapstream.com/api/v1/project/$PROJECT_ID/folder/$FOLDER_ID

Delete a folder (add ?delete_videos=true to also delete the videos inside):

curl -u :$API_KEY -X DELETE \
  https://staging.heapstream.com/api/v1/project/$PROJECT_ID/folder/$FOLDER_ID

On videos, folder_id appears on the video object, is settable on edit (0 or null removes the video from its folder), and filters the video list: ?folder_id=<id> returns the folder's direct videos, ?folder_id=0 returns un-filed videos, and omitting it returns everything.

There are no separate folder.* webhook events; folder changes ride the existing video events where those already fire.

Limits and errors¶

See also Limits.