> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Create and manage playlists

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.

\


## Prerequisites

* A FastPix account with an active workspace ([Activate your account](/getting-started/activate-your-account))
* Your **Access Token ID** and **Secret Key** from the FastPix dashboard
* At least one On-Demand video already uploaded so you have a `mediaId` to add to manual playlists ([Upload videos from URL](/upload-videos/upload-videos-from-a-url))
* Familiarity with the FastPix on-demand API base URL: `https://api.fastpix.com/v1/`

\


## Key terms

* **`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.

\


## Manual playlists and Smart playlists

|                      | Manual playlist                               | Smart playlist                                              |
| -------------------- | --------------------------------------------- | ----------------------------------------------------------- |
| Who picks the videos | You add each `mediaId` explicitly             | FastPix auto-selects based on metadata filters              |
| Order                | You control the order; reorderable            | Sorted by `playOrder` (`createdDate ASC` or `DESC`)         |
| Evaluation           | Static - only changes when you edit it        | Evaluated at creation time; not re-evaluated automatically  |
| Best for             | Featured reels, highlights, brand collections | "Videos from last week", dated uploads, scheduled workflows |
| Maximum videos       | 1,000                                         | 1,000                                                       |

Both types use the same `POST /v1/on-demand/playlists` endpoint. The `type` field in the request body (`manual` or `smart`) controls the behavior.

\


## Create playlists from the Dashboard

You can create both manual and smart playlists directly from the FastPix Dashboard.

### Add videos to a manual playlist

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:

1. [Create a manual playlist](#create-a-manual-playlist).
2. [Open the Add Media panel](#open-the-add-media-panel).
3. [Add media to the playlist](#add-media-to-the-playlist).
4. [Verify the playlist](#verify-the-playlist).

\


#### Create a manual playlist

1. In the left navigation, go to **Video > Playlists**.
2. On the **Playlists** page, configure the following fields:
   * **Playlist type**: Select **Manual** from the dropdown.
   * **Playlist name**: Enter a name for your playlist.
   * **Description**: (Optional) Enter a short description.
   * **Reference ID**: (Optional) Enter a reference ID to link the playlist to an external system.
3. Click **Create playlist**.

\


#### Open the Add Media panel

1. The Playlists page lists your newly created playlist.
2. Click **Add Media** next to the playlist to open the **Add media** panel.

\


#### Add media to the playlist

1. In the **Add media** panel, choose one of the following methods:
   * **Add by search**: Enter a media ID in the search field to locate a specific video.
   * **Add by media ID**: Paste one or more media IDs directly into the text area, with each ID on a separate line.
2. Click **Add Media** to add the videos to the playlist.

\


#### Verify the playlist

1. Open the playlist details page.
2. Review the added videos in order, along with each video's media ID, duration, and creation date.
3. Confirm that all expected videos appear in the list.

\


### Add videos to a smart playlist

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:

1. [Create a smart playlist](#create-a-smart-playlist).
2. [Verify playlist creation](#verify-playlist-creation).
3. [Review playlist details](#review-playlist-details).

\


#### Create a smart playlist

1. In the left navigation, go to **Video > Playlists**.
2. On the **Playlists** page, configure the following fields:
   * **Playlist type**: Select **Smart** from the dropdown.
   * **Playlist name**: Enter a name for your playlist.
   * **Description**: Enter a short description.
   * **Play order**: Select the order in which videos play, such as **Oldest First**.
   * **Limit no. of videos**: Enter the maximum number of videos the playlist can contain.
   * **Reference ID**: Enter a reference ID to link the playlist to an external system.
   * **Metadata**: Add one or more metadata filters to define which videos are included. For each filter, select a metadata field such as **Created Date** or **Updated Date**, and set a start and end date range. Click **Add metadata** to add more filters.
3. Click **Create playlist**.

\


#### Verify playlist creation

1. Open the **Playlists** page.
2. Confirm that your newly created smart playlist appears in the list along with its type, reference ID, creation date, and media count.

\


#### Review playlist details

1. Click the playlist name to open the playlist details page.
2. Confirm the playlist name, description, playlist ID, type, reference ID, and media count.
3. Review the list of videos populated based on your metadata filters.

\


> **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.

* **Manual playlists**: You select and arrange specific videos
* **Smart playlists**: Videos are automatically included based on metadata filters

\


## Create a manual playlist using the API

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](/video-on-demand-api/playlist/create-a-playlist) API:

**`Request`**

```Text Request
https://api.fastpix.com/v1/on-demand/playlists 
```

\


Here's an example of the request body for creating a manual playlist:

```json
{ 
  "name": "my playlist", 
  "referenceId": "new20", 
  "type": "manual", 
  "description": "This is a manual playlist" 
} 
```

\


**Field descriptions**

* **name** (required): A title for the playlist.
* **referenceId** (required): A unique identifier from the client side. This must be unique within the workspace and is used for idempotency and future referencing.
* **type** (required): Must be set to `"manual"` for manually managed playlists.
* **description** (optional): Optional text description to annotate the purpose or content of the playlist.

\


**`Response`**

```json Response
{ 
    "success": true, 
    "data": { 
        "id": "e3f4c4cf-b69c-42a7-99ec-cde12cb12e7a", 
        "name": "my playlist", 
        "referenceId": "new20", 
        "type": "manual", 
        "description": "This is a manual playlist", 
        "mediaList": [], 
        "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d", 
        "createdAt": "2025-06-13T06:57:24.003125Z", 
        "updatedAt": "2025-06-13T06:57:24.003125Z", 
        "mediaCount": 0, 
    } 
} 
```

\
\


## Create a smart playlist using the API

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](/video-on-demand-api/playlist/create-a-playlist) API.

Here's an example of the request body for creating a smart playlist:

**`Request`**

```json Request
{
  "name": "my smart playlist",
  "referenceId": "JanuaryToJune",
  "type": "smart",
  "description": "This playlist contains videos created from January to june 2025",
  "playOrder": "createdDate ASC",
  "limit": 20,
  "metadata": {
    "createdDate": {
      "startDate": "2025-01-01",
      "endDate": "2025-06-06"
    }
  }
}
```

\


**Field descriptions**

* **name** (required): A title for the playlist.
* **referenceId** (required): A unique identifier from the client side. This must be unique within the workspace and is used for idempotency and future referencing.
* **type** (required): Must be set to `"smart"` for auto-generated playlists.
* **playOrder** (optional): Determines the sort order of videos, for example, `"createdDate ASC"` or `"createdDate DESC"`.
* **limit** (optional): Restricts the number of media items in the playlist. Useful to cap playlist length in dynamic conditions.
* **metadata** (required): Specifies the rules for auto-selection. In the example above, all media items created between `startDate` and `endDate` are included. Media can be filtered by created date, updated date, or a combination of both.

\


**Response:**

**`Response example`**

```json Response example
{
    "success": true,
    "data": {
        "id": "adad6a6d-6985-4ce9-ba9b-8ac0e08cdeb7",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune2",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-17",
                "startDate": "2025-10-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            },
            {
                "createdAt": "2025-10-01T07:20:48.857019Z",
                "duration": "00:27:52",
                "id": "3a4c6ced-baa8-4ef9-a15e-a0370fe8ef2d",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/f19268f5-9719-403f-87c9-b604fb3bdce3/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:00:08.808521Z",
        "updatedAt": "2025-10-17T10:00:08.808521Z",
        "mediaCount": 2
    }
}
```

\


> **NOTE**
>
> Both manual and smart playlists are created using the [same endpoint](/video-on-demand-api/playlist/create-a-playlist). The behavior of the endpoint is determined by the `type` field in the payload. The `referenceId` must be globally unique per workspace.
>
> In manual playlists, `mediaList` is empty on creation. In smart playlists, the initial `mediaList` is 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.

\


#### Example use cases

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.

\


## Play a playlist

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 player to your page

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.

```html
<fastpix-player id="player" aspect-ratio="16/9"></fastpix-player>
<script>
  const playlist = [
    { playbackId: 'playbackId_1' },
    { playbackId: 'playbackId_2' }
  ];

  const player = document.getElementById('player');
  player.addPlaylist(playlist);

  player.addEventListener('playbackidchange', (e) => {
    const { playbackId, currentIndex, totalItems } = e.detail || {};
    console.log('Now playing', playbackId, currentIndex, '/', totalItems);
  });
```

\


## Enable loop-next for playlists

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:

```html
<fastpix-player 
  id="player" 
  aspect-ratio="16/9"
  loop-next>
</fastpix-player>
```

\


**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.

\


## Update playlist name and description

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:

* Refining naming conventions
* Improving clarity and context

\


> **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](/video-on-demand-api/playlist/update-a-playlist) endpoint:

**`PUT request`**

```text PUT request
https://api.fastpix.com/v1/on-demand/playlists/{playlistId} 
```

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.

**`Sample request body`**

```json Sample request body
{ 
    "name": "updated name", 
    "description": "updated description" 
} 
```

\


**Field descriptions**

* **name** (required): New display name for the playlist. This overwrites the previous value.
* **description** (required): Updated description that explains the playlist's purpose, content, or structure.

\


**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.

\


**`Response example`**

```json Response example
{
    "success": true,
    "data": {
        "id": "b3a0d94a-3233-4024-b127-76070ffe5431",
        "name": "updated name",
        "referenceId": "Set01",
        "type": "manual",
        "description": "updated description",
        "mediaList": [],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T09:40:50.147851Z",
        "updatedAt": "2025-10-17T10:18:11.086429Z",
        "mediaCount": 0
    }
}
```

\


> **IMPORTANT NOTES**
>
> * The `playlistId` must belong to a valid playlist in the authenticated user's workspace; otherwise, a 404 error is returned.
> * Both `name` and `description` must be non-empty strings.
> * Updating either value refreshes the `updatedAt` timestamp of the playlist.
> * The update does not affect the media list or type (`manual` or `smart`).

\


#### Example use cases

* Correcting a typo in the playlist name.
* Rewriting the description to match a campaign's updated messaging.
* Updating playlist labels to reflect a new categorization scheme after launch.

\
\


## View all playlists

To see all playlists in a workspace, use the [Get all playlists](/video-on-demand-api/playlist/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**:

**`GET`**

```text GET
https://api.fastpix.com/v1/on-demand/playlists/?limit={limit}&offset={offset} 
```

\


> **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.

\


```json
{
  "success": true,
  "data": [
    {
      "id": "db6e860f-cb57-43dd-8acf-39c9effd5608",
      "name": "playist",
      "type": "smart",
      "referenceId": "1n2",
      "createdAt": "2025-06-04T13:29:04.253244Z",
      "mediaCount": 0
    },
    {
      "id": "5c18559f-c1b1-4697-9282-77211d4396bb",
      "name": "playist",
      "type": "smart",
      "referenceId": "1n1",
      "createdAt": "2025-06-04T13:01:05.073809Z",
      "mediaCount": 0
    },
    {
      "id": "a4735902-b5e6-431f-8875-7a1a2cbc7a7b",
      "name": "okkokk",
      "type": "manual",
      "referenceId": "121q",
      "createdAt": "2025-06-04T12:17:38.917664Z",
      "mediaCount": 0
    }
  ],
  "pagination": {
    "totalRecords": 20,
    "currentOffset": 1,
    "offsetCount": 7
  }
}
```

\


Here are the response field descriptions:

#### Playlist object

* **id** (UUID): Unique identifier of the playlist (`playlistId`).
* **name** (string): Display name of the playlist.
* **type** (string): Indicates whether the playlist is manual or smart.
* **referenceId** (string): Reference string for internal or external linking.
* **createdAt** (timestamp): Date and time when the playlist was created.
* **mediaCount** (integer): Number of media items currently in the playlist.

\


#### Pagination object

* **totalRecords** (integer): Total number of playlists available in the workspace.
* **currentOffset** (integer): Current page number.
* **offsetCount** (integer): Number of playlists returned in this response.

\


> **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.

\


#### Example use cases

Using this endpoint, you can:

* Display a paginated list of playlists in a dashboard.
* Implement page-based navigation in the UI.
* Refresh the playlist view after a creation, update, or deletion action.

\
\


## View a specific playlist

To access the details of a particular playlist, provide its unique `playlistId` to the [Get playlist by ID](/video-on-demand-api/playlist/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:**

**`GET request`**

```json GET request
https://api.fastpix.com/v1/on-demand/playlists/{playlistId} 
```

\


**Response**:

Returns the complete details of the playlist, including metadata and associated media.

**`Response example`**

```json Response example
{
    "success": true,
    "data": {
        "id": "3bf8f24b-ca89-40a1-a3e9-170faf3de956",
        "name": "Test 1",
        "referenceId": "Set1",
        "type": "smart",
        "description": "Online Gaming Videos",
        "playOrder": "createdDate DESC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-15",
                "startDate": "2025-09-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T07:20:48.857019Z",
                "duration": "00:27:52",
                "id": "3a4c6ced-baa8-4ef9-a15e-a0370fe8ef2d",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/f19268f5-9719-403f-87c9-b604fb3bdce3/thumbnail.png"
            },
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            },
            {
                "createdAt": "2025-09-30T10:24:14.621213Z",
                "duration": "00:00:10",
                "id": "0c26cc32-a7eb-4f6c-a890-3670bbe10146",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/379f0e3a-c3f5-4060-b701-43763c7d05a4/thumbnail.png"
            },
            {
                "createdAt": "2025-09-30T10:24:04.032662Z",
                "duration": "00:00:10",
                "id": "7e6cee8d-d89a-4f0c-9c2a-03ec5cf7612f",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/a84fbc2f-1678-4f53-8ee2-bc1e778945f5/thumbnail.png"
            },
            {
                "createdAt": "2025-09-30T06:35:43.903460Z",
                "duration": "00:00:10",
                "id": "f3871af2-6942-4c59-8a5e-dd880829e412",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/45fd0881-5117-4b2c-b726-ac415399c2b1/thumbnail.png"
            },
            {
                "createdAt": "2025-09-24T10:50:55.594589Z",
                "duration": "00:03:17",
                "id": "82afefa8-b238-4ec5-8e39-1a6f5ea101de",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/597d8cc4-b387-4126-8f32-476a6e6fbe7b/thumbnail.png"
            },
            {
                "createdAt": "2025-09-23T06:10:17.589509Z",
                "duration": "00:00:10",
                "id": "65e83be9-0821-4bab-875f-7fc311c092c5",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/821041cc-9893-4856-9c8b-4388c26423ee/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T09:44:30.111270Z",
        "updatedAt": "2025-10-17T10:42:20.353178Z",
        "mediaCount": 7
    }
}
```

\


> **NOTE**
>
> * The API returns full playlist detail including metadata and media items.
> * Smart playlists contain `metadata` and `playOrder` fields.
> * Thumbnail links are pre-rendered images; safe for direct rendering in UI.
> * The playlist is returned only if it belongs to a valid workspace.

\
\


## Add media to a playlist

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](/video-on-demand-api/playlist/add-media-to-playlist):

**`PATCH request`**

```text PATCH request
https://api.fastpix.com/v1/on-demand/playlists/{playlistId}/media
```

\


Here's an example of the request body:

**`Request`**

```json Request
{ 
  "mediaIds": [ 
    "Media_ID1", 
    "Media_ID2"  
  ] 
} 
```

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**:

**`Response example`**

```json Response example
{
    "success": true,
    "data": {
        "id": "59d7960a-bab6-4c02-88ef-83b9ba992196",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune3",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-02-17",
                "startDate": "2025-01-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-09-30T10:24:14.621213Z",
                "duration": "00:00:10",
                "id": "0c26cc32-a7eb-4f6c-a890-3670bbe10146",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/379f0e3a-c3f5-4060-b701-43763c7d05a4/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:02:48.986053Z",
        "updatedAt": "2025-10-17T11:44:30.011848Z",
        "mediaCount": 1
    }
}
```

\
\


> **IMPORTANT NOTES**
>
> * Duplicate media IDs are not added multiple times.
> * If any of the `mediaIds` are already associated with the playlist, they are ignored silently.
> * The order in which media is added follows the order in the request body.
> * The `mediaCount` reflects the total number of unique media items in the playlist after the update.

\


#### Example use cases

Using this endpoint you can:

* Add a new set of featured videos to a manually curated "Highlights of the Month" playlist.
* Update a brand showcase playlist when new product videos are available.

\
\


## Change the order of media in a playlist

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](/video-on-demand-api/playlist/change-media-order-in-playlist) endpoint:

**`PUT request`**

```text PUT request
https://api.fastpix.com/v1/on-demand/playlists/{playlistId}/media
```

Here `playlistId` is the unique identifier of the playlist whose media order is to be updated.

\


**`Request body`**

```json Request body
{ 
  "mediaIds": [ 
    "Media_ID1", 
    "Media_ID2" 
  ] 
} 
```

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**:

**`Response example`**

```json Response example
{
    "success": true,
    "data": {
        "id": "adad6a6d-6985-4ce9-ba9b-8ac0e08cdeb7",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune2",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-17",
                "startDate": "2025-10-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T07:20:48.857019Z",
                "duration": "00:27:52",
                "id": "3a4c6ced-baa8-4ef9-a15e-a0370fe8ef2d",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/f19268f5-9719-403f-87c9-b604fb3bdce3/thumbnail.png"
            },
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:00:08.808521Z",
        "updatedAt": "2025-10-17T11:59:46.214536Z",
        "mediaCount": 2
    }
}
```

\


> **IMPORTANT NOTES**
>
> * Only reordering is supported. New media cannot be added here — use [Add media to playlist](/video-on-demand-api/playlist/add-media-to-playlist) to add.
> * All existing media in the playlist must be included in the `mediaIds` array.
> * If any ID is missing or unknown, the request is rejected with a validation error.

\


#### Example use cases

Using this endpoint, you can:

* Reorder the media to ensure the most relevant or recent content appears first.
* Align media order to match a scripted playback sequence for scheduled presentations.
* Organize product or demo videos based on updated priority or messaging.

\
\


## Remove media from a playlist

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](/video-on-demand-api/playlist/delete-media-from-playlist):

**`DELETE`**

```text DELETE
https://api.fastpix.com/v1/on-demand/playlists/{playlistId}/media
```

Here `playlistId` is the unique identifier of the playlist to delete media from.

\


**`Request body`**

```json Request body
{ 
  "mediaIds": [ 
    "Media_ID" 
  ] 
} 
```

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**:

**`Response example`**

```json Response example
{
    "success": true,
    "data": {
        "id": "adad6a6d-6985-4ce9-ba9b-8ac0e08cdeb7",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune2",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-17",
                "startDate": "2025-10-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.com/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:00:08.808521Z",
        "updatedAt": "2025-10-17T12:06:12.797825Z",
        "mediaCount": 1
    }
}
```

\


> **NOTE**
>
> * If any `mediaId` is 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.

\


#### Example use cases

Using this endpoint, you can:

* Remove outdated or irrelevant media items from a playlist.
* Clean up playlists by trimming down unused content.
* Manage dynamic content sets for better control of playback or publication order.

\
\


## Delete a playlist

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](/video-on-demand-api/playlist/delete-a-playlist):

**`DELETE`**

```Text DELETE
https://api.fastpix.com/v1/on-demand/playlists/{playlistId}
```

Here `playlistId` is the unique identifier of the playlist to be deleted.

\


**Response**:

**`Response example`**

```json Response example
{ 
  "success": true 
} 
```

\


> **NOTE**
>
> * After deletion, the playlist cannot be recovered.
> * Associated media is not deleted from the system — only the playlist reference is removed.
> * If the `playlistId` is invalid or the playlist does not exist, an appropriate error is returned (for example, 404 Not Found).

\


#### Example use cases

Using this endpoint, you can:

* Remove obsolete or test playlists.
* Clear up workspace resources.
* Replace a playlist with a newer version.

\


#### Frequently asked questions

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.

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.

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](/video-on-demand-api/playlist/add-media-to-playlist) endpoint separately.

A maximum of 1,000 videos per playlist, for both manual and smart playlists.

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.

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.

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.

## What's next?

* [On-Demand Video overview](/video-on-demand/overview)
* [Upload videos from URL](/upload-videos/upload-videos-from-a-url)
* [API Reference: Create a playlist](/video-on-demand-api/playlist/create-a-playlist)
* [API Reference: Get all playlists](/video-on-demand-api/playlist/get-all-playlists)

\