Create and manage playlist

Playlists in FastPix can be created in two modes: manual and smart.

Manual playlists allows to explicitly manage and add media.
Smart playlists automatically populate based on metadata filters such as media creation date.

Create manual playlist

In manual mode, the user defines the playlist metadata and creates an empty list. Media must be added explicitly after creation. This mode is suitable when curation is handled by a person or when external systems decide which media should be added.

Make a POST request to create a new playlist API:

https://api.fastpix.io/v1/on-demand/playlists

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

{ 
  "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.

{ 
    "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 smart playlist

Smart playlists automatically populate based on dynamic metadata filters. This is ideal for workflows where the inclusion logic is temporal or based on specific attributes. Users specify a date range for media creation, and optionally a limit and sort order.

Request: Make a POST request to create a new playlist API.

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

{
  "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

type (required): Must be set to "smart" for auto-generated playlists.
playOrder (optional): Determines the sort order of videos, e.g., "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 will be included. Media can be filtered by created date, updated date, or a combination of both.

Response:

{
  "success": true,
  "data": {
    "id": "f7968a6f-d1d8-4c1e-a554-fce4c417a9f7",
    "name": "my smart playlist",
    "referenceId": "JanuaryToJune",
    "type": "smart",
    "description": "This playlist contains videos created from January to june 2025",
    "playOrder": "createdDate ASC",
    "metadata": {
      "createdDate": {
        "endDate": "2025-06-06",
        "startDate": "2025-01-01"
      }
    },
    "mediaList": [
      {
        "createdAt": "2025-03-21T05:58:38.000708Z",
        "duration": "00:00:10",
        "id": "942e0ced-146b-487e-988f-6de578de1000",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/ff31b32e-4979-4d2b-ad2a-685af43c9902/thumbnail.png"
      },
      {
        "createdAt": "2025-03-21T12:01:42.885393Z",
        "duration": "00:00:10",
        "id": "6d12262b-0686-4131-9de2-bb515f7c0f38",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:12.455054Z",
        "duration": "00:00:10",
        "id": "7de3a62c-bdf9-4067-8a68-13b148847326",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/a4dc1b1f-4194-402c-af70-a027564e91f7/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:28.372777Z",
        "duration": "00:00:10",
        "id": "ee09603a-6c71-4e53-b9ab-5a0455c364fe",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e18fff99-86d4-45f0-80ef-38d931a6aedf/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:31.418989Z",
        "duration": "00:00:10",
        "id": "e2db81c5-1a0f-46d3-b4e8-5e5082dc6fc7",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/95058c47-b8d1-4072-9eee-5896ad9e8112/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:06.369780Z",
        "duration": "00:00:10",
        "id": "fa70f926-4599-488a-bb33-b972926b2442",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/4bfb9cc0-a535-4de0-8282-b50fd0c173f1/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:09.706669Z",
        "duration": "00:00:10",
        "id": "205ba8a4-d214-4fc4-a6e5-9a304ce6cfd9",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/0dcb0a5b-6796-4f2f-a14b-c2af8e4af4b5/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:12.552840Z",
        "duration": "00:00:10",
        "id": "41316aac-5396-4278-8f44-08d5f2495b12",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/8989d0d3-5c5b-41b2-89d5-df6094e6093f/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:23.507284Z",
        "duration": "00:00:10",
        "id": "245800c3-7b73-47d9-a201-e961260dcb30",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/3c6ceeea-d24b-487f-9dd0-5a16148b5d46/thumbnail.png"
      },
      {
        "createdAt": "2025-05-27T09:37:52.445936Z",
        "duration": "00:00:10",
        "id": "a1cd180e-f9b5-4e99-9d44-b9c9baabad89",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/bed25609-1887-4c49-91a5-5c6b1edeb1a2/thumbnail.png"
      }
    ],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-13T07:11:02.010349Z",
    "updatedAt": "2025-06-13T07:11:02.010349Z",
    "mediaCount": 10
  }
}

PLEASE NOTE

Both manual and smart playlists are created using the same endpoint. 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.

When using smart playlists, the 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 are ideal for scheduled publishing, analytics, or backend workflows where logic is deterministic based on metadata.

Update playlist name and description

You can update a playlist’s name and description by referencing its playlistId.
This feature is useful for making adjustments after a playlist has been created, for example:

Refining naming conventions
Improving clarity and context

PLEASE NOTE

Only the name and description fields can be modified; all other playlist details remain unchanged.

Request:

Make a POST request to update a playlist endpoint:

https://api.fastpix.io/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.

Also, 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.

{ 
    "name": "updated name", 
    "description": "updated description" 
}

Field descriptions

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

Response:

Upon successful update, the API returns the full playlist object with updated metadata. Other fields remain unchanged, including media list, type, and creation timestamp.

{
  "success": true,
  "data": {
    "id": "e3f4c4cf-b69c-42a7-99ec-cde12cb12e7a",
    "name": "updated name",
    "referenceId": "new20",
    "type": "manual",
    "description": "updated description",
    "mediaList": [],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-13T06:57:24.003125Z",
    "updatedAt": "2025-06-13T08:29:31.716709Z",
    "mediaCount": 0,
    "indexing": false
  }
}

IMPORTANT NOTES

The playlistId must belong to a valid playlist in the authenticated user's workspace; otherwise, a 404 error will be returned.

Both name and description must be non-empty strings.

Updating either value will refresh 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 endpoint to fetch a paginated list. This lets users browse through playlists in manageable chunks, especially when dealing with a large collection.

Pagination can be controlled using optional limit and offset parameters, making it easy to navigate through the data without overwhelming the system or the user interface.

Request:

https://api.fastpix.io/v1/on-demand/playlists/?limit={limit}&offset={offset}

Query Parameters

limit (integer, optional): Specifies the number of playlists to return per page. This helps control the size of the response for efficient frontend rendering and API consumption. Defaults to a 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 users to render paginated UIs and implement "Load More" feature.

{
  "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.
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 (starting from 0).
offsetCount (integer): Number of playlists returned in this response.

PLEASE NOTE

If limit and offset are not provided, the backend will return 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 will be returned.

Example use cases

Using this endpoint, you can:

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

View a specific playlist

To access the details of a particular playlist, provide its unique playlistId to the get a 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.

It's a helpful way to review how a playlist is set up and what content it includes.

Request:

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}

Response:

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

{
  "success": true,
  "data": {
    "id": "f7968a6f-d1d8-4c1e-a554-fce4c417a9f7",
    "name": "my smart playlist",
    "referenceId": "JanuaryToJune",
    "type": "smart",
    "description": "This playlist contains videos created from January to june 2025",
    "playOrder": "createdDate ASC",
    "metadata": {
      "createdDate": {
        "endDate": "2025-06-06",
        "startDate": "2025-01-01"
      }
    },
    "mediaList": [
      {
        "createdAt": "2025-03-21T05:58:38.000708Z",
        "duration": "00:00:10",
        "id": "942e0ced-146b-487e-988f-6de578de1000",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/ff31b32e-4979-4d2b-ad2a-685af43c9902/thumbnail.png"
      },
      {
        "createdAt": "2025-03-21T12:01:42.885393Z",
        "duration": "00:00:10",
        "id": "6d12262b-0686-4131-9de2-bb515f7c0f38",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:12.455054Z",
        "duration": "00:00:10",
        "id": "7de3a62c-bdf9-4067-8a68-13b148847326",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/a4dc1b1f-4194-402c-af70-a027564e91f7/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:28.372777Z",
        "duration": "00:00:10",
        "id": "ee09603a-6c71-4e53-b9ab-5a0455c364fe",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e18fff99-86d4-45f0-80ef-38d931a6aedf/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:31.418989Z",
        "duration": "00:00:10",
        "id": "e2db81c5-1a0f-46d3-b4e8-5e5082dc6fc7",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/95058c47-b8d1-4072-9eee-5896ad9e8112/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:06.369780Z",
        "duration": "00:00:10",
        "id": "fa70f926-4599-488a-bb33-b972926b2442",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/4bfb9cc0-a535-4de0-8282-b50fd0c173f1/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:09.706669Z",
        "duration": "00:00:10",
        "id": "205ba8a4-d214-4fc4-a6e5-9a304ce6cfd9",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/0dcb0a5b-6796-4f2f-a14b-c2af8e4af4b5/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:12.552840Z",
        "duration": "00:00:10",
        "id": "41316aac-5396-4278-8f44-08d5f2495b12",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/8989d0d3-5c5b-41b2-89d5-df6094e6093f/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:23.507284Z",
        "duration": "00:00:10",
        "id": "245800c3-7b73-47d9-a201-e961260dcb30",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/3c6ceeea-d24b-487f-9dd0-5a16148b5d46/thumbnail.png"
      },
      {
        "createdAt": "2025-05-27T09:37:52.445936Z",
        "duration": "00:00:10",
        "id": "a1cd180e-f9b5-4e99-9d44-b9c9baabad89",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/bed25609-1887-4c49-91a5-5c6b1edeb1a2/thumbnail.png"
      }
    ],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-13T07:11:02.010349Z",
    "updatedAt": "2025-06-13T07:11:02.010349Z",
    "mediaCount": 10,
    "indexing": false
  }
}

PLEASE NOTE

The API returns full playlist detail including metadata and media items.

Smart playlists will 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 is useful for building or updating playlists. Media can be added in bulk, making it efficient to organize large sets of content.

Once added, the media becomes part of the playlist and will appear wherever the playlist is used or displayed.

Request: Make a PATCH request to this endpoint:

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}/media

Here’s an example of the request body:

{ 
  "mediaIds": [ 
    "6d12262b-0686-4131-9de2-bb515f7c0f38", 
    "d2278a31-575e-4fa6-a55f-c0a13b8a74f4", 
    "942e0ced-146b-487e-988f-6de578de1000" 
  ] 
}

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 allows for precise control over playback or presentation sequence.

Response:

{
  "success": true,
  "data": {
    "id": "f7968a6f-d1d8-4c1e-a554-fce4c417a9f7",
    "name": "my smart playlist",
    "referenceId": "JanuaryToJune",
    "type": "smart",
    "description": "This playlist contains videos created from January to june 2025",
    "playOrder": "createdDate ASC",
    "metadata": {
      "createdDate": {
        "endDate": "2025-06-06",
        "startDate": "2025-01-01"
      }
    },
    "mediaList": [
      {
        "createdAt": "2025-03-21T05:58:38.000708Z",
        "duration": "00:00:10",
        "id": "942e0ced-146b-487e-988f-6de578de1000",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/ff31b32e-4979-4d2b-ad2a-685af43c9902/thumbnail.png"
      },
      {
        "createdAt": "2025-03-21T12:01:42.885393Z",
        "duration": "00:00:10",
        "id": "6d12262b-0686-4131-9de2-bb515f7c0f38",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:12.455054Z",
        "duration": "00:00:10",
        "id": "7de3a62c-bdf9-4067-8a68-13b148847326",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/a4dc1b1f-4194-402c-af70-a027564e91f7/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:28.372777Z",
        "duration": "00:00:10",
        "id": "ee09603a-6c71-4e53-b9ab-5a0455c364fe",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e18fff99-86d4-45f0-80ef-38d931a6aedf/thumbnail.png"
      },
      {
        "createdAt": "2025-04-01T11:12:31.418989Z",
        "duration": "00:00:10",
        "id": "e2db81c5-1a0f-46d3-b4e8-5e5082dc6fc7",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/95058c47-b8d1-4072-9eee-5896ad9e8112/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:06.369780Z",
        "duration": "00:00:10",
        "id": "fa70f926-4599-488a-bb33-b972926b2442",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/4bfb9cc0-a535-4de0-8282-b50fd0c173f1/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:09.706669Z",
        "duration": "00:00:10",
        "id": "205ba8a4-d214-4fc4-a6e5-9a304ce6cfd9",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/0dcb0a5b-6796-4f2f-a14b-c2af8e4af4b5/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:12.552840Z",
        "duration": "00:00:10",
        "id": "41316aac-5396-4278-8f44-08d5f2495b12",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/8989d0d3-5c5b-41b2-89d5-df6094e6093f/thumbnail.png"
      },
      {
        "createdAt": "2025-04-04T13:26:23.507284Z",
        "duration": "00:00:10",
        "id": "245800c3-7b73-47d9-a201-e961260dcb30",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/3c6ceeea-d24b-487f-9dd0-5a16148b5d46/thumbnail.png"
      },
      {
        "createdAt": "2025-05-27T09:37:52.445936Z",
        "duration": "00:00:10",
        "id": "a1cd180e-f9b5-4e99-9d44-b9c9baabad89",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/bed25609-1887-4c49-91a5-5c6b1edeb1a2/thumbnail.png"
      }
    ],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-13T07:11:02.010349Z",
    "updatedAt": "2025-06-13T07:11:02.010349Z",
    "mediaCount": 10,
    "indexing": false
  }
}

IMPORTANT NOTES

Duplicate media IDs will not be added multiple times.

If any of the mediaIds are already associated with the playlist, they will be 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 media IDs.

This action replaces the current order with the one specified in the request. It’s important to note that only media items already present in the playlist can be reordered - no new items can be added through this operation.

Use this feature to fine-tune the flow of content for presentations, storytelling, or playback experiences.

Request: Make a PUT request to change media order endpoint:

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}/media

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

{ 
  "mediaIds": [ 
    "942e0ced-146b-487e-988f-6de578de1000", 
    "6d12262b-0686-4131-9de2-bb515f7c0f38", 
    "d2278a31-575e-4fa6-a55f-c0a13b8a74f4" 
  ] 
}

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:

{
  "success": true,
  "data": {
    "id": "e3f4c4cf-b69c-42a7-99ec-cde12cb12e7a",
    "name": "updated name",
    "referenceId": "new20",
    "type": "manual",
    "description": "updated description",
    "mediaList": [
      {
        "createdAt": "2025-03-21T05:58:38.000708Z",
        "duration": "00:00:10",
        "id": "942e0ced-146b-487e-988f-6de578de1000",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/ff31b32e-4979-4d2b-ad2a-685af43c9902/thumbnail.png"
      },
      {
        "createdAt": "2025-03-21T12:01:42.885393Z",
        "duration": "00:00:10",
        "id": "6d12262b-0686-4131-9de2-bb515f7c0f38",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png"
      },
      {
        "createdAt": "2025-06-09T12:02:52.694573Z",
        "duration": "00:00:06",
        "id": "d2278a31-575e-4fa6-a55f-c0a13b8a74f4",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/22244ccf-07f8-4312-9eb3-ee863cc5051d/thumbnail.png"
      }
    ],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-13T06:57:24.003125Z",
    "updatedAt": "2025-06-13T11:49:27.004203Z",
    "mediaCount": 3,
    "indexing": false
  }
}

IMPORTANT NOTES

Only reordering is supported. New media cannot be added here - use the PATCH endpoint to add.

All existing media in the playlist must be included in the mediaIds array.

If any ID is missing or unknown, the request will be 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 media IDs. This operation updates the playlist to exclude only the selected items, leaving the rest of the media unchanged and in their existing order.

This feature is useful when refining a playlist’s content - such as removing outdated clips, trimming overly long collections, or adjusting the playlist to fit a new purpose. It offers flexibility in maintaining playlists without requiring a full re-creation or manual reordering of the remaining items.

Request: Make a DELETE request to this endpoint:

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}/media

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

{ 
  "mediaIds": [ 
    "942e0ced-146b-487e-988f-6de578de1000" 
  ] 
}

Field description:

mediaIds : List of media UUIDs to be removed from the playlist. These must be currently present in the playlist.

Response:

{
  "success": true,
  "data": {
    "id": "e3f4c4cf-b69c-42a7-99ec-cde12cb12e7a",
    "name": "updated name",
    "referenceId": "new20",
    "type": "manual",
    "description": "updated description",
    "mediaList": [
      {
        "createdAt": "2025-06-09T12:02:52.694573Z",
        "duration": "00:00:06",
        "id": "d2278a31-575e-4fa6-a55f-c0a13b8a74f4",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/22244ccf-07f8-4312-9eb3-ee863cc5051d/thumbnail.png"
      },
      {
        "createdAt": "2025-03-21T12:01:42.885393Z",
        "duration": "00:00:10",
        "id": "6d12262b-0686-4131-9de2-bb515f7c0f38",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png"
      }
    ],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-13T06:57:24.003125Z",
    "updatedAt": "2025-06-13T12:01:04.199542Z",
    "mediaCount": 2,
    "indexing": false
  }
}

PLEASE NOTE

If any Media ID is not found in the playlist , the request will be 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 ID. Once deleted, it will no longer appear in the workspace, and any media linked to it will be disassociated - but not removed from the library.

This action is permanent and cannot be undone, so it should be used carefully, especially for playlists that are shared or in active use.

Request: Make a DELETE request to this endpoint:

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}

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

Response:

{ 
  "success": true 
}

PLEASE NOTE

Once deleted, 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 (e.g., 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.