---
title: "Create a search playlist"
method: POST
path: "/v2/sites/{site_id}/playlists/search_playlist/"
tags: ["playlists"]
---

# Create a search playlist

`POST /v2/sites/{site_id}/playlists/search_playlist/`

## Request

- Base URL: `https://api.jwplayer.com`
- URL: `https://api.jwplayer.com/v2/sites/{site_id}/playlists/search_playlist/`
- Auth: API key in header `Authorization`

## Path parameters

- `site_id` string, required: Unique identifier for a resource

## Request body

- object
  - `metadata` SearchPlaylistMetadata
    - `title` string: Title of the playlist. When using JWX's HTML5 player, the playlist title is displayed in the overlay. A maximum of 256 characters is permitted.
    - `description` string: Description of the playlist A maximum of 7500 characters is permitted.
    - `author` string: Author of the playlist A maximum of 256 characters is permitted.
    - `link` string: URL to be associated with the playlist A maximum of 2048 characters is permitted.
    - `custom_params` CustomParamSchema: User-generated key-value pairs When defining `custom_params`, include all custom parameters that should be associated with the target resource. When updating existing `custom_params`, include all `custom_params` keys with their updated values. Any `custom_params` key-value pair not included within the updated `custom_params` in the request body is [deleted](doc:stream-faq-how-can-i-delete-a-custom-parameter). **NOTE**: To assign a content type to a media item, set the `contentType` custom parameter to the name of a content type configured for the property. When updating an existing media item, do not send `contentType` alone. Include all existing `custom_params` key-value pairs in the PATCH request; any omitted pairs are deleted.
    - `tag_filter` PlaylistTagFilter: Playlist tags to apply filtering logic from. The filter logic will change based the `match` value in the `include` and `exclude` sections (the `match` value can be one of `any` or `all`). * If the `match` mode is set to `any`, a video with any of the specified tags will be included or excluded from the playlist. * If the `match` mode is set to `all` a video must have all the specified tags to be included or excluded from the playlist.
      - `include` PlaylistTagRules: Tags used to filter the media result set for the playlist. A maximum of 200 tags are allowed per playlist (inclusive of both include and exclude values).
        - `values` string[]
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
      - `exclude` PlaylistTagRules: Tags used to filter the media result set for the playlist. A maximum of 200 tags are allowed per playlist (inclusive of both include and exclude values).
        - `values` string[]
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
    - `custom_param_filter` PlaylistCustomParamFilter: Playlist custom parameters to apply filtering logic from. The filter logic will change based the `match` value in the `include` and `exclude` sections (the `match` value can be one of `any` or `all`). * If the `match` mode is set to `any`, a video with any of the specified custom paramaters will be included or excluded from the playlist. * If the `match` mode is set to `all` a video must have all the specified custom parameters to be included or excluded from the playlist.
      - `include` PlaylistParamRules: Media Custom Parameters used to filter the media result set for the playlist. A maximum of 100 custom parameter's are allowed per playlist (inclusive of both include and exclude values).
        - `values` object
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
      - `exclude` PlaylistParamRules: Media Custom Parameters used to filter the media result set for the playlist. A maximum of 100 custom parameter's are allowed per playlist (inclusive of both include and exclude values).
        - `values` object
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
    - `media_filter` object
      - `limit` integer: For manual playlists, the limit determines the maximum number of media that can be included in a given playlist.
    - `pinning` PlaylistPinning: Playlist IDs to be pinned in the first and/or second slot of a playlist
      - `slot1` string: Unique identifier for a resource
      - `slot2` string: Unique identifier for a resource
    - `recency` string: Recency logic to apply to playlist. Valid recency values begin with an integer and end with a unit of time, either days (D) or years (YR)

## Response `201`

Resource successfully created

- SearchPlaylistResourceRead: Resource for managing a search playlist
  - `schema` string
  - `id` string: Unique identifier for a resource
  - `created` string: Date and time at which the resource was created
  - `last_modified` string: Date and time at which the resource was most recently modified
  - `type` string: Name of the type of resource.
  - `relationships` object: Ancilliary resources associated to the primary resource being read
  - `metadata` SearchPlaylistMetadata
    - `title` string: Title of the playlist. When using JWX's HTML5 player, the playlist title is displayed in the overlay. A maximum of 256 characters is permitted.
    - `description` string: Description of the playlist A maximum of 7500 characters is permitted.
    - `author` string: Author of the playlist A maximum of 256 characters is permitted.
    - `link` string: URL to be associated with the playlist A maximum of 2048 characters is permitted.
    - `custom_params` CustomParamSchema: User-generated key-value pairs When defining `custom_params`, include all custom parameters that should be associated with the target resource. When updating existing `custom_params`, include all `custom_params` keys with their updated values. Any `custom_params` key-value pair not included within the updated `custom_params` in the request body is [deleted](doc:stream-faq-how-can-i-delete-a-custom-parameter). **NOTE**: To assign a content type to a media item, set the `contentType` custom parameter to the name of a content type configured for the property. When updating an existing media item, do not send `contentType` alone. Include all existing `custom_params` key-value pairs in the PATCH request; any omitted pairs are deleted.
    - `tag_filter` PlaylistTagFilter: Playlist tags to apply filtering logic from. The filter logic will change based the `match` value in the `include` and `exclude` sections (the `match` value can be one of `any` or `all`). * If the `match` mode is set to `any`, a video with any of the specified tags will be included or excluded from the playlist. * If the `match` mode is set to `all` a video must have all the specified tags to be included or excluded from the playlist.
      - `include` PlaylistTagRules: Tags used to filter the media result set for the playlist. A maximum of 200 tags are allowed per playlist (inclusive of both include and exclude values).
        - `values` string[]
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
      - `exclude` PlaylistTagRules: Tags used to filter the media result set for the playlist. A maximum of 200 tags are allowed per playlist (inclusive of both include and exclude values).
        - `values` string[]
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
    - `custom_param_filter` PlaylistCustomParamFilter: Playlist custom parameters to apply filtering logic from. The filter logic will change based the `match` value in the `include` and `exclude` sections (the `match` value can be one of `any` or `all`). * If the `match` mode is set to `any`, a video with any of the specified custom paramaters will be included or excluded from the playlist. * If the `match` mode is set to `all` a video must have all the specified custom parameters to be included or excluded from the playlist.
      - `include` PlaylistParamRules: Media Custom Parameters used to filter the media result set for the playlist. A maximum of 100 custom parameter's are allowed per playlist (inclusive of both include and exclude values).
        - `values` object
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
      - `exclude` PlaylistParamRules: Media Custom Parameters used to filter the media result set for the playlist. A maximum of 100 custom parameter's are allowed per playlist (inclusive of both include and exclude values).
        - `values` object
        - `match` 'any' | 'all': Whether to apply any or all logic to provided values
    - `media_filter` object
      - `limit` integer: For manual playlists, the limit determines the maximum number of media that can be included in a given playlist.
    - `pinning` PlaylistPinning: Playlist IDs to be pinned in the first and/or second slot of a playlist
      - `slot1` string: Unique identifier for a resource
      - `slot2` string: Unique identifier for a resource
    - `recency` string: Recency logic to apply to playlist. Valid recency values begin with an integer and end with a unit of time, either days (D) or years (YR)

## Other responses

- `400`: Invalid JSON request body

## Changes

- **2026-11-03** `9fad6bd5872e`: 1 info
  - added the media type `application/json` for the response with the status `400`

[Operation history](https://skmtc.dev/jwplayer/apis/management-api-v2/changes/v2/sites/:site_id/playlists/search_playlist/post.md)

---

[API](https://skmtc.dev/jwplayer/apis/management-api-v2.md) - [All operations](https://skmtc.dev/jwplayer/apis/management-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/jwplayer/apis/management-api-v2/revisions/9fad6bd5872e?raw)