Create a new playlist | FastPix Developer Documentation

curl -X POST https://api.fastpix.com/v1/on-demand/playlists \
     -H "Content-Type: application/json" \
     -u "<username>:<password>" \
     -d '{
  "name": "playlist name",
  "referenceId": "a1",
  "type": "smart",
  "description": "This is a playlist",
  "playOrder": "createdDate ASC",
  "limit": 20,
  "metadata": {
    "createdDate": {
      "startDate": "2024-11-11",
      "endDate": "2024-12-12"
    },
    "updatedDate": {
      "startDate": "2024-11-11",
      "endDate": "2024-12-12"
    }
  }
}'

{
  "success": true,
  "data": {
    "id": "e3dfdf15-16bb-4835-98b9-484c1e4320cc",
    "name": "playist",
    "referenceId": "a1",
    "type": "smart",
    "description": "This is a playlist",
    "playOrder": "createdDate ASC",
    "metadata": {
      "createdDate": {
        "startDate": "2024-11-11",
        "endDate": "2024-12-12"
      },
      "updatedDate": {
        "startDate": "2024-11-11",
        "endDate": "2024-12-12"
      }
    },
    "mediaList": [
      {
        "createdAt": "2024-11-12T05:58:38.000708Z",
        "creatorId": "FastPix@14612",
        "duration": "00:00:10",
        "id": "942e0ced-146b-487e-988f-6de578de1000",
        "sourceResolution": "1080p",
        "status": "Ready",
        "thumbnail": "https://venus-images.fastpix.dev/ff31b32e-4979-4d2b-ad2a-685af43c9902/thumbnail.png",
        "title": "Media 1"
      },
      {
        "createdAt": "2024-12-05T07:23:18.000108Z",
        "creatorId": "FastPix@14612",
        "duration": "00:00:10",
        "id": "6d12262b-0686-4131-9de2-bb515f7c0f38",
        "sourceResolution": "1080p",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png",
        "title": "Media 2"
      },
      {
        "createdAt": "2024-12-05T07:21:15.000508Z",
        "creatorId": "FastPix@14612",
        "duration": "00:00:10",
        "id": "a1cd180e-f9b5-4e99-9d44-b9c9baabad89",
        "sourceResolution": "1080p",
        "status": "Ready",
        "thumbnail": "https://mercury-images.fastpix.dev/e49a0d7b-6f2c-4743-84d1-45522cc20ded/thumbnail.png",
        "title": "Media 3"
      }
    ],
    "workspaceId": "d760b903-86ef-44d6-9b73-334130e0cf2d",
    "createdAt": "2025-06-04T13:29:39.409886Z",
    "updatedAt": "2025-06-04T13:29:39.409886Z",
    "mediaCount": 3
  }
}

This endpoint creates a new playlist within a specified workspace. A playlist acts as a container for organizing media items either manually or based on filters and metadata.

Playlists can be created in two modes

Manual: Creates an empty playlist without any initial media items. Use this mode for manual curation, where you add items later in a user-defined sequence.
Smart: Auto-populates the playlist at creation time based on the filter criteria (for example, a video creation date range) that you provide in the request.

For more details, see Create and manage playlist.

How it works

When you send a POST request to this endpoint, FastPix creates a playlist and returns a playlist ID, using which items can be added later in a user-defined sequence.
You can create a smart playlist that is auto-populated based on the metadata in the request body.

Example

An e-learning platform creates a new playlist titled Beginner Python Series through the API. The response returns a unique playlist ID. The platform uses this ID to add a series of video tutorials to the playlist in a defined order. The playlist appears on the frontend as a structured learning path for learners.

This endpoint creates a new playlist within a specified workspace. A playlist acts as a container for organizing media items either manually or based on filters and metadata. ### Playlists can be created in two modes - **Manual:** Creates an empty playlist without any initial media items. Use this mode for manual curation, where you add items later in a user-defined sequence. - **Smart:** Auto-populates the playlist at creation time based on the filter criteria (for example, a video creation date range) that you provide in the request. For more details, see <a href="https://docs.fastpix.io/docs/create-and-manage-playlist">Create and manage playlist</a>. #### How it works - When you send a `POST` request to this endpoint, FastPix creates a playlist and returns a playlist ID, using which items can be added later in a user-defined sequence. - You can create a smart playlist that is auto-populated based on the metadata in the request body. #### Example An e-learning platform creates a new playlist titled Beginner Python Series through the API. The response returns a unique playlist ID. The platform uses this ID to add a series of video tutorials to the playlist in a defined order. The playlist appears on the frontend as a structured learning path for learners.

Authentication

AuthorizationBasic

FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request.

Username: Access Token ID
Password: Secret Key

Activate your FastPix account to generate your API credentials. See the guide here

FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request. - Username: Access Token ID - Password: Secret Key Activate your FastPix account to generate your API credentials. <a href="https://docs.fastpix.io/docs/activate-account" target="_blank">See the guide here</a>

Request

This endpoint expects an object.

namestringRequiredDefaults to Playlist name

Name of the playlist.

referenceIdstringRequiredDefaults to a1

Unique string value assigned by user to the playlist.

typeenumRequiredDefaults to smart

For a smart playlist metadata is required.

descriptionstringOptionalDefaults to This is a playlist

Description for a playlist (Optional).

playOrderenumOptionalDefaults to createdDate DESC

Determines the insertion order of media into playlist.

limitintegerOptionalDefaults to 1000

Optional parameter to limit no. of media in a playlist.

metadataobjectOptional

Required when the playlist type is smart. Media created between startDate and endDate of createdDate is added. Optionally, you can include media based on updatedDate.

Response

Playlist created successfully

successboolean

Shows the request status. Returns true for success and false for failure.

dataobject

Displays the result of the request.

This endpoint creates a new playlist within a specified workspace. A playlist acts as a container for organizing media items either manually or based on filters and metadata.

Playlists can be created in two modes

Manual: Creates an empty playlist without any initial media items. Use this mode for manual curation, where you add items later in a user-defined sequence.
Smart: Auto-populates the playlist at creation time based on the filter criteria (for example, a video creation date range) that you provide in the request.

For more details, see Create and manage playlist.

How it works

When you send a POST request to this endpoint, FastPix creates a playlist and returns a playlist ID, using which items can be added later in a user-defined sequence.
You can create a smart playlist that is auto-populated based on the metadata in the request body.