PUT a Playlist

Overview

---

The following table contains important information about the PUT method in regards to updating a playlist.

This version of the endpoint replaces the flat folders array of integers used in API V1 with a structured playlistFolders array. Each entry carries an includeFutureSubfolders flag, which marks the folder as a lock-root: when it is true, every current and future subfolder of that folder is automatically included in the playlist, so the playlist does not have to be edited again when new subfolders are created.

note

The includeFutureSubfolders flag exists only on the API V2 contract. Updating a playlist through the API V1 endpoint leaves the flag untouched, so a V1 edit can never reset a folder that was saved as a lock-root.

PUT Playlist
Method	PUT
URL or Endpoint	/api/v2/projects/projectId/playlists
Headers	Authorization
Parameters	projectId
Body	Check the request body below.

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Description
projectId	Yes	string	Unique ID of the project.

Request Body

{
  "publicId": "{publicId}",
  "title": "{title}",
  "description": "{description}",
  "playListPagePermalink": "{playListPagePermalink}",
  "playListTypeId": 0,
  "playlistDisplayTypeId": 0,
  "playlistSortOptionId": 0,
  "includeTags": [
    "{includeTag}"
  ],
  "excludeTags": [
    "{excludeTag}"
  ],
  "includeTagsState": false,
  "excludeTagsState": false,
  "excludeFlags": [
    0
  ],
  "includeFlags": [
    0
  ],
  "includeAllProjects": false,
  "includeProjects": [
    "{projectId}"
  ],
  "excludeFlagsState": false,
  "includeFlagsState": false,
  "includeTagModeId": 0,
  "excludeTagModeId": 0,
  "includeFlagModeId": 0,
  "excludeFlagModeId": 0,
  "maxVideos": 0,
  "dateFrom": "2026-08-10T15:02:46.586Z",
  "dateTo": "2026-08-10T15:02:46.586Z",
  "playlistBackupState": false,
  "playlistBackupId": "{playlistBackupId}",
  "excludeWatchedVideosState": false,
  "excludeKeywords": [
    "{excludeKeyword}"
  ],
  "aspectRatios": [
    0
  ],
  "playlistFolders": [
    {
      "folderId": 0,
      "includeFutureSubfolders": false
    }
  ]
}

Information about the fields that appear when you type in the request body are displayed in the table below.

Field Name	Type	Description
publicId	string	The ID of the playlist that is being updated.
title	string	The title of the playlist.
description	string	Information about the playlist.
playListPagePermalink	string	The permalink of the playlist page. When it is set, it must be a valid URL.
playListTypeId	integer	The ID of the playlist type.
playlistDisplayTypeId	integer or null	The ID of the playlist display type.
playlistSortOptionId	integer or null	The ID of the playlist sorting option.
includeTags	array[string]	An array that contains the tags you want to include in the playlist.
excludeTags	array[string]	An array that contains the tags you want to exclude from the playlist.
includeTagsState	boolean	Indicates whether the tags state is included.
excludeTagsState	boolean	Indicates whether the tags state is excluded.
excludeFlags	array[integer]	An array that contains the flags you want to exclude from the playlist. It must be empty for manual playlists.
includeFlags	array[integer]	An array that contains the flags you want to include in the playlist. It must be empty for manual playlists, and the PR_VIDEO flag is not allowed.
includeAllProjects	boolean	Indicates whether videos from all projects of the organization should be included. For recommended, dynamic and contextual playlists, includeProjects must be empty when it is true.
includeProjects	array[string]	An array of project IDs whose videos should be included in the playlist. It is required for recommended, dynamic and contextual playlists when includeAllProjects is false.
excludeFlagsState	boolean	Indicates whether the flags state is excluded.
includeFlagsState	boolean	Indicates whether the flags state is included.
includeTagModeId	integer or null	The ID of the includeTag mode.
excludeTagModeId	integer or null	The ID of the excludeTag mode.
includeFlagModeId	integer or null	The ID of the includeFlag mode.
excludeFlagModeId	integer or null	The ID of the excludeFlag mode.
maxVideos	integer or null	The maximum number of videos in the playlist. It must be between 1 and 100.
dateFrom	string($date-time) or null	Include videos uploaded on or after this date and time.
dateTo	string($date-time) or null	Include videos uploaded on or before this date and time.
playlistBackupState	boolean or null	Indicates whether the playlist has a backup playlist or not.
playlistBackupId	string	The unique identifier of the backup playlist.
excludeWatchedVideosState	boolean	Indicates whether the videos previously watched by the user should be excluded from the playlist.
excludeKeywords	array[string]	An array of keywords; videos containing any of these keywords are excluded from the playlist.
aspectRatios	array[integer]	An array of aspect ratios; only videos that match the specified aspect ratios are included in the playlist. It must be empty for manual playlists.
playlistFolders	array[object]	The folder selection of the playlist. It replaces the whole selection on every update, so send the complete list of folders you want the playlist to keep.

playlistFolders Properties

Field Name	Type	Description
folderId	integer	The ID of the folder whose videos should be included in the playlist. It must be greater than 0, it must be the ID of an existing folder, and it cannot be repeated within the same request. The folder must belong to the project of the playlist or to one of the included projects; when includeAllProjects is true, it can belong to any project of the organization.
includeFutureSubfolders	boolean	When true, all current and future subfolders of this folder are included in the playlist automatically, without any further update. When false, only the videos of this folder are included.

Response

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "publicId": "{publicId}",
    "title": "{title}",
    "description": "{description}",
    "playListPagePermalink": "{playListPagePermalink}",
    "playListTypeId": 0,
    "playlistDisplayTypeId": 0,
    "playlistSortOptionId": 0,
    "includeTags": [
      "{includeTag}"
    ],
    "excludeTags": [
      "{excludeTag}"
    ],
    "includeTagsState": false,
    "excludeTagsState": false,
    "excludeFlags": [
      0
    ],
    "includeFlags": [
      0
    ],
    "includeAllProjects": false,
    "includeProjects": [
      "{projectId}"
    ],
    "excludeFlagsState": false,
    "includeFlagsState": false,
    "includeTagModeId": 0,
    "excludeTagModeId": 0,
    "includeFlagModeId": 0,
    "excludeFlagModeId": 0,
    "maxVideos": 0,
    "dateFrom": "2026-08-10T15:02:46.586Z",
    "dateTo": "2026-08-10T15:02:46.586Z",
    "canEmbed": true,
    "playlistBackupState": false,
    "playlistBackupId": "{playlistBackupId}",
    "excludeWatchedVideosState": false,
    "excludeKeywords": [
      "{excludeKeyword}"
    ],
    "aspectRatios": [
      0
    ],
    "includeTagMode": {
      "id": 0,
      "name": "{name}"
    },
    "excludeTagMode": {
      "id": 0,
      "name": "{name}"
    },
    "playlistType": {
      "id": 0,
      "name": "{name}",
      "value": "{value}",
      "description": "{description}"
    },
    "playlistSortOption": {
      "id": 0,
      "name": "{name}"
    },
    "playlistDisplayType": {
      "id": "{id}",
      "name": "{name}",
      "value": "{value}"
    },
    "playlistFolders": [
      {
        "folderId": 0,
        "includeFutureSubfolders": false
      }
    ]
  },
  "resultInfo": null,
  "statusCode": 200
}

Information about the fields that appear when you receive the response are displayed in the table below.

Top-Level Properties

Field Name	Type	Description
success	boolean	If the response is successful it will return true. Otherwise will return false.
errors	array[string]	Indicates if there was an error.
messages	array[string]	Returns the response message from back-end.
result	object	Returns the response object.
publicId	string	The ID of the playlist.
title	string	The title of the playlist.
description	string	Returns information about the playlist.
playListPagePermalink	string	The permalink of the playlist page.
playListTypeId	integer	The ID of the playlist type.
playlistDisplayTypeId	integer or null	The ID of the playlist display type.
playlistSortOptionId	integer or null	The ID of the playlist sorting option.
includeTags	array[string]	An array that contains the tags included in the playlist.
excludeTags	array[string]	An array that contains the tags excluded from the playlist.
includeTagsState	boolean	Indicates whether the tags state is included.
excludeTagsState	boolean	Indicates whether the tags state is excluded.
excludeFlags	array[integer]	An array that contains the flags excluded from the playlist.
includeFlags	array[integer]	An array that contains the flags included in the playlist.
includeAllProjects	boolean	Indicates whether videos from all projects of the organization should be included.
includeProjects	array[string]	An array of project IDs whose videos are included in the playlist.
excludeFlagsState	boolean	Indicates whether the flags state is excluded.
includeFlagsState	boolean	Indicates whether the flags state is included.
includeTagModeId	integer or null	The ID of the includeTag mode.
excludeTagModeId	integer or null	The ID of the excludeTag mode.
includeFlagModeId	integer or null	The ID of the includeFlag mode.
excludeFlagModeId	integer or null	The ID of the excludeFlag mode.
maxVideos	integer or null	The maximum number of videos in the playlist.
dateFrom	string($date-time) or null	Include videos uploaded on or after this date and time.
dateTo	string($date-time) or null	Include videos uploaded on or before this date and time.
canEmbed	boolean	Indicates whether the playlist can be embedded or not.
playlistBackupState	boolean or null	Indicates whether the playlist has a backup playlist or not.
playlistBackupId	string	The unique identifier of the backup playlist.
excludeWatchedVideosState	boolean	Indicates whether the videos previously watched by the user are excluded from the playlist.
excludeKeywords	array[string]	An array of keywords; videos containing any of these keywords are excluded from the playlist.
aspectRatios	array[integer]	An array of aspect ratios; only videos that match the specified aspect ratios are included in the playlist.
includeTagMode	object	Returns the includeTag mode object.
excludeTagMode	object	Returns the excludeTag mode object.
playlistType	object	Returns the playlist type object.
playlistSortOption	object	Returns the playlist sort option object.
playlistDisplayType	object	Returns the playlist display type object.
playlistFolders	array[object]	The folder selection of the playlist as it was saved. Only the selected folders are returned, not the subfolders that are resolved from a folder marked with includeFutureSubfolders.
resultInfo	string	Returns extra information about the result.
statusCode	integer	Returns the HTTP Status Code.

includeTagMode Properties

Field Name	Type	Description
id	integer	The ID of the tag mode.
name	string	The name of the tag mode.

excludeTagMode Properties

Field Name	Type	Description
id	integer	The ID of the tag mode.
name	string	The name of the tag mode.

playlistType Properties

Field Name	Type	Description
id	integer	The ID of the playlist type.
name	string	The name of the playlist type.
value	string	The value of the playlist type.
description	string	The description of the playlist type.

playlistSortOption Properties

Field Name	Type	Description
id	integer	The ID of the playlist sort option.
name	string	The name of the playlist sort option.

playlistDisplayType Properties

Field Name	Type	Description
id	string	The ID of the playlist display type.
name	string	The name of the playlist display type.
value	string	The value of the playlist display type.

playlistFolders Properties

Field Name	Type	Description
folderId	integer	The ID of the folder whose videos are included in the playlist.
includeFutureSubfolders	boolean	When true, all current and future subfolders of this folder are included in the playlist automatically. When false, only the videos of this folder are included.

If the action is successful, the service sends back an HTTP 200 or 201 response.

Errors

For information about the errors that are common to all actions, see Common Errors:

• HTTP Status Code 400: Bad Request

• HTTP Status Code 401: Unauthorized

• HTTP Status Code 403: Forbidden

• HTTP Status Code 404: Result Not Found

• HTTP Status Code 500: Internal Server Error

• HTTP Status Code 503: Backend Fetch Failed