Create and manage playlists
Organize and manage multiple media assets by creating playlists, adding or removing videos, arranging their order, and controlling playback settings.
FastPix improves content discovery and viewer retention by letting you group On-Demand videos into playlists for curated, continuous playback. Create a manual playlist where you pick each mediaId, or a smart playlist where FastPix auto-populates the collection from metadata filters such as creation date, by sending a POST to https://api.fastpix.com/v1/on-demand/playlists. The API returns a playlistId you use to update, reorder, fetch, and delete the playlist.
mediaId to add to manual playlists (Upload videos from URL)https://api.fastpix.com/v1/playlistId is the UUID FastPix assigns to each playlist on creation. Use it as the path parameter for every update, reorder, fetch, or delete call.mediaId is the unique identifier FastPix assigns to each uploaded video asset. Manual playlists reference videos by mediaId.referenceId is a client-supplied unique string stored with the playlist. It must be unique within the workspace and supports idempotency and external lookup.playbackId is the separate, access-controlled identifier used to stream a video at https://stream.fastpix.com/<playbackId>.m3u8. The player consumes playbackId values, not mediaId values.Both types use the same POST /v1/on-demand/playlists endpoint. The type field in the request body (manual or smart) controls the behavior.
You can create both manual and smart playlists directly from the FastPix Dashboard.
You can add existing media to a manual playlist directly from the FastPix dashboard by searching for a media ID or entering one or more media IDs manually.
To add videos to a manual playlist, you need to:
A smart playlist automatically organizes videos based on metadata filters and rules you define. FastPix populates the playlist dynamically based on the criteria you set during creation.
To add videos to a smart playlist, you need to:
Important Notes:
Manual playlists start empty and require you to manually add media. They give you complete control over which videos appear and in what order.
Smart playlists automatically populate based on date filters at creation time.
Both playlist types support up to 1,000 videos maximum.
Playlists created through the dashboard can also be managed through the API using their unique playlist ID.
In manual mode, you define the playlist metadata and create an empty list. Media must be added explicitly after creation. This mode fits workflows where curation is handled by a person or where external systems decide which media to add.
Make a POST request to the Create a playlist API:
Here’s an example of the request body for creating a manual playlist:
Field descriptions
"manual" for manually managed playlists.Smart playlists auto-populate based on dynamic metadata filters. This fits workflows where inclusion logic is temporal or based on specific attributes. You specify a date range for media creation, and optionally a limit and sort order.
Request: Make a POST request to the Create a playlist API.
Here’s an example of the request body for creating a smart playlist:
Field descriptions
"smart" for auto-generated playlists."createdDate ASC" or "createdDate DESC".startDate and endDate are included. Media can be filtered by created date, updated date, or a combination of both.Response:
NOTE
Both manual and smart playlists are created using the same endpoint. The behavior of the endpoint is determined by the
typefield in the payload. ThereferenceIdmust be globally unique per workspace.In manual playlists,
mediaListis empty on creation. In smart playlists, the initialmediaListis populated automatically based on the metadata filters.Smart playlist inclusion rules are evaluated at the time of creation. If new media is added later that fits the criteria, it is not added automatically unless the playlist is recreated.
A maximum of 1,000 videos can be added to a playlist.
Use manual playlists for curated sets such as featured reels, highlight compilations, or brand collections. Use smart playlists to auto-generate collections such as “Videos from last week”, “March 2025 uploads”, or “All media from event XYZ”. Smart playlists fit scheduled publishing, analytics, or backend workflows where the logic is deterministic based on metadata.
After you create a playlist, you can play it using the FastPix web player. The player handles video transitions automatically and provides playback controls.
Add the FastPix player element to your HTML and load the playlist.
In the following code, replace playbackId_1 and playbackId_2 with the actual playbackId values from your videos.
By default, when a video in the playlist ends, playback stops. To auto-play the next video in the playlist, add the loop-next attribute to the player element:
With autoplay enabled:
The first video starts playing automatically when the page loads. When a video ends, the next video in the playlist starts immediately. The playlist stops when the last video finishes.
NOTE:
Some browsers block autoplay with sound until the viewer interacts with the page. If autoplay fails, click the play button or interact with the page to start playback.
You can update a playlist’s name and description by referencing its playlistId.
This is useful for adjustments after a playlist has been created, for example:
NOTE
Only the name and description fields can be modified; all other playlist details remain unchanged.
Request:
Make a PUT request to the Update a playlist endpoint:
Here playlistId is the path parameter. It is the unique identifier of the playlist to be updated. Must be a valid playlist belonging to the current workspace.
The request body must include both the name and the description fields, even if only one of them is being changed. Partial updates are not allowed.
Field descriptions
Response:
On a successful update, the API returns the full playlist object with updated metadata. Other fields remain unchanged, including media list, type, and creation timestamp.
IMPORTANT NOTES
- The
playlistIdmust belong to a valid playlist in the authenticated user’s workspace; otherwise, a 404 error is returned.- Both
nameanddescriptionmust be non-empty strings.- Updating either value refreshes the
updatedAttimestamp of the playlist.- The update does not affect the media list or type (
manualorsmart).
To see all playlists in a workspace, use the Get all playlists endpoint to fetch a paginated list. This lets you browse through playlists in manageable chunks, which matters when dealing with a large collection.
Pagination is controlled with optional limit and offset parameters, so you can navigate through the data without overwhelming the UI.
Request:
Query Parameters
limit(integer, optional): Specifies the number of playlists to return per page. This controls the size of the response for efficient frontend rendering and API consumption. Defaults to 10 if not provided.
offset(integer, optional): Indicates the page number to fetch. The first page starts at offset 1. Useful for navigating through large result sets.
Response:
The response includes a list of playlist objects along with pagination metadata to enable paginated UIs and “Load More” flows.
Here are the response field descriptions:
playlistId).NOTE
- If limit and offset are not provided, the backend returns a maximum of 10 playlists from the first page.
- The API is optimized for frontend usage with fast paginated retrieval, especially for large media catalogs.
- Only playlists visible to the authenticated user’s workspace context are returned.
Using this endpoint, you can:
To access the details of a particular playlist, provide its unique playlistId to the Get playlist by ID endpoint. This request returns full metadata about the playlist, including its settings, any applied filters (for smart playlists), and the list of associated media assets.
This is a reliable way to review how a playlist is set up and what content it includes.
Request:
Response:
Returns the complete details of the playlist, including metadata and associated media.
NOTE
- The API returns full playlist detail including metadata and media items.
- Smart playlists contain
metadataandplayOrderfields.- Thumbnail links are pre-rendered images; safe for direct rendering in UI.
- The playlist is returned only if it belongs to a valid workspace.
You can add one or more media assets to an existing playlist by specifying the target playlistId along with the media items you want to include.
This fits building or updating playlists. Media can be added in bulk, which makes it efficient to organize large sets of content.
After you add media, it becomes part of the playlist and appears wherever the playlist is used or displayed.
Request: Make a PATCH request to Add media to playlist:
Here’s an example of the request body:
Replace Media_ID1 and Media_ID2 with your actual mediaId values to add media to a playlist.
Field description:
- mediaIds : A list of UUIDs representing the media items to be added to the playlist. The order of the items in this list determines the order in which they appear in the playlist. This gives precise control over playback or presentation sequence.
Response:
IMPORTANT NOTES
- Duplicate media IDs are not added multiple times.
- If any of the
mediaIdsare already associated with the playlist, they are ignored silently.- The order in which media is added follows the order in the request body.
- The
mediaCountreflects the total number of unique media items in the playlist after the update.
Using this endpoint you can:
You can update the sequence of media items in an existing playlist by providing a new ordered list of mediaId values.
This action replaces the current order with the one specified in the request. Only media items already present in the playlist can be reordered — no new items can be added through this operation.
Use this to fine-tune the flow of content for presentations, storytelling, or playback experiences.
Request: Make a PUT request to Change media order endpoint:
Here playlistId is the unique identifier of the playlist whose media order is to be updated.
Replace Media_ID1 and Media_ID2 with your actual mediaId values to change the order of media in a playlist.
Field description:
- mediaIds : A list of UUIDs representing media items already present in the playlist, arranged in the new desired order. All existing media items in the playlist must be included in this list — partial reordering is not supported. This ensures the playlist is fully restructured without omitting any content.
Response:
IMPORTANT NOTES
- Only reordering is supported. New media cannot be added here — use Add media to playlist to add.
- All existing media in the playlist must be included in the
mediaIdsarray.- If any ID is missing or unknown, the request is rejected with a validation error.
Using this endpoint, you can:
Specific media items can be removed from a playlist by providing their corresponding mediaId values. This operation updates the playlist to exclude only the selected items, leaving the rest of the media unchanged and in their existing order.
This fits refining a playlist’s content — such as removing outdated clips, trimming overly long collections, or adjusting the playlist to fit a new purpose. It supports maintaining playlists without requiring full re-creation or manual reordering of the remaining items.
Request: Make a DELETE request to Delete media from playlist:
Here playlistId is the unique identifier of the playlist to delete media from.
Replace Media_ID with the actual mediaId of the video you want to remove from the playlist.
Field description:
- mediaIds : List of media UUIDs to be removed from the playlist. These must be currently present in the playlist.
Response:
NOTE
- If any
mediaIdis not found in the playlist, the request is rejected with a validation error.- This operation only affects playlist linkage; it does not delete the media asset from the system.
Using this endpoint, you can:
A playlist can be deleted by providing its unique playlistId. After deletion, it no longer appears in the workspace. Any linked media is disconnected, but remains in the library.
This action is permanent and cannot be undone, so use it carefully — especially for playlists that are shared or in active use.
Request: Make a DELETE request to Delete a playlist:
Here playlistId is the unique identifier of the playlist to be deleted.
Response:
NOTE
- After deletion, the playlist cannot be recovered.
- Associated media is not deleted from the system — only the playlist reference is removed.
- If the
playlistIdis invalid or the playlist does not exist, an appropriate error is returned (for example, 404 Not Found).
Using this endpoint, you can:
What is the difference between a manual playlist and a smart playlist?
A manual playlist is curated — you add each mediaId explicitly and control the order. A smart playlist auto-populates from metadata filters (such as a creation-date range) at the moment of creation. Both use the same POST /v1/on-demand/playlists endpoint, with the type field (manual or smart) determining the behavior.
Does a smart playlist update automatically when I upload new videos that match its filters?
No. FastPix evaluates smart playlist filters only at creation time. New media that matches the filter after creation is not added. To refresh the selection, create a new smart playlist with the same filters.
Can I add more videos while reordering media in a playlist?
No. The reorder endpoint (PUT /v1/on-demand/playlists/{playlistId}/media) only accepts mediaId values already present in the playlist, and the request must include every existing item. To add new videos, call the Add media to playlist endpoint separately.
How many videos can a single playlist contain?
A maximum of 1,000 videos per playlist, for both manual and smart playlists.
What happens to the videos when I delete a playlist?
Only the playlist reference is removed. The underlying media assets remain in your workspace and retain their mediaId and playbackId values. Any other playlists that reference those videos are unaffected.
How do I organize videos in a playlist?
Use a manual playlist to hand-pick each mediaId and arrange them in your preferred order. Use a smart playlist to auto-populate from date-range filters. Both types support up to 1,000 videos and can be reordered after creation using the PUT /v1/on-demand/playlists/{playlistId}/media endpoint.
How do I rearrange videos in a playlist?
Send a PUT request to /v1/on-demand/playlists/{playlistId}/media with the full list of mediaId values in the new order. Every existing media item must be included — partial reordering is not supported. The playlist order updates immediately.