Playlists


List Playlists

GET https://api.zype.com/playlists

Parameters

Parameter Function Type
active Filter by active, inactive, or all records (Example: true) String
category Filter records by category value (Example: category[color]=blue) Hash
category! Exclude records by category value (Example: category![color]=blue) Hash
id Filter records by ID String
id! Exclude records by ID String
order Sort records in ascending or descending order (Example: asc/desc) String
page The page number of records to return (Example: 1) Integer
per_page The number of records to return (Example: 10) Integer
q Filter records by keyword String
sort Sort records on the specified field String
title Filter records by title String

Create a Playlist

POST https://api.zype.com/playlists

Parameters

Parameter Function Type
playlist[title] The title of the playlist String
playlist[description] The description of the playlist String
playlist[active] Choose if the playlist should be active Boolean
playlist[priority] Order priority relative to other playlists Integer
playlist[purchase_required] Enable purchase for the playlist edge feature Boolean
playlist[purchase_price] Purchase price for the playlist bundle, sent as a string, ie “4.99” edge feature String
playlist[rental_required] Enable rental for the playlist edge feature Boolean
playlist[rental_price] Rental price for the playlist bundle, sent as a string, ie “4.99” edge feature String
playlist[rental_duration] Rental duration for the playlist, in days edge feature Integer
playlist[auto_update_consumer_videos] Keep consumer video purchases and/or rentals in sync with playlist items. When videos are added to the playlist, also add them to a consumer’s video purchase/rental list. edge feature Boolean
playlist[thumbnail_layout] Preferred thumbnail layout for videos related to playlist. Options are ‘landscape’, ‘poster’, and ‘square’. If left blank will default to ‘landscape’. String
playlist[custom_thumbnail] Image as a file attachment  

Retrieve a Playlist

GET https://api.zype.com/playlists/[id]

Parameters

Parameter Function Type
id ID of the record to retrieve (Example: 5389352e69702d401b000000) String

List Playlist Videos

GET https://api.zype.com/playlists/[id]/videos

Parameters

Parameter Function Type
id ID of the record to retrieve (Example: 5389352e69702d401b000000) String
active Filter by active, inactive, or all records (Example: active=true, active=false, active=all) String
category Filter records by category value (Example: category[color]=blue) Hash
category! Exclude records by category value (Example: category![color]=blue) Hash
created_at Filter records by created date using times in ISO8601 format (Example: 2017-01-01T00:00:00-00:00) or Unix timestamps (Example: 1483228800).

Note: Range filters can be applied by adding a suffix: .gt, .gte, .lt, .lte (Example: created_at.gte=2017-01-01T00:00:00-00:00)
Date
crunchyroll_id Filter records by a Crunchyroll ID String
dpt Filter records by DPT conditions (Geo-location and device restrictions) Boolean
featured Filter records that are featured Boolean
friendly_title Find records by URL friendly title for SEO purposes String
hulu_id Filter records by a Hulu ID String
mature_content Filter records that are flagged as mature content Boolean
order Sort records in ascending or descending order (Example: order=asc, order=desc) String
on_air Filter records that are either on or off air Boolean
page The page number of records to return (Example: page=1) Integer
per_page The number of records to return (Example: per_page=10) Integer
published_at Filter records by published date using times in ISO8601 format (Example: 2017-01-01T00:00:00-00:00) or Unix timestamps (Example: 1483228800)

Note: Range filters can be applied by adding a suffix: .gt, .gte, .lt, .lte (Example: published_at.gte=2017-01-01T00:00:00-00:00)
Date
q Filter records by keyword String
sort Sort records on the specified field String
source_id Filter records by an optional source identifier String
type Filter records by type (Examples: zype, hulu, youtube, crunchyroll) String
updated_at Filter records by last updated date using times in ISO8601 format (Example: 2017-01-01T00:00:00-00:00) or Unix timestamps (Example: 1483228800).

Note: Range filters can be applied by adding a suffix: .gt, .gte, .lt, .lte (Example: updated_at.gte=2017-01-01T00:00:00-00:00)
Date
vimeo_id Filter records by a Vimeo ID String
youtube_id Filter records by a YouTube ID String
zobject_id Filter records by Zobject ID String
zobject_id! Exclude records by Zobject ID String

Update a Playlist

PUT https://api.zype.com/playlists/[id]

Note: When updating an array of objects (like categories and images_attributes] use 0 or whichever number corresponds to the resource you wish to update. It is index based and so will update the appropriate resource.

Parameters

Parameter Function Type
id ID of the record to update (Example: 540731274c616e047a000000) String
playlist[title] The title of the playlist String
playlist[description] The description of the playlist String
playlist[active] Choose if the playlist should be active Boolean
playlist[priority] Order priority relative to other playlists Integer
playlist[purchase_required] Enable purchase for the playlist edge feature Boolean
playlist[purchase_price] Purchase price for the playlist bundle, sent as a string, ie “4.99” edge feature String
playlist[rental_required] Enable rental for the playlist edge feature Boolean
playlist[rental_price] Rental price for the playlist bundle, sent as a string, ie “4.99” edge feature String
playlist[rental_duration] Rental duration for the playlist, in days edge feature Integer
playlist[auto_update_consumer_videos] Keep consumer video purchases and/or rentals in sync with playlist items. When videos are added to the playlist, also add them to a consumer’s video purchase/rental list. edge feature Boolean
playlist[thumbnail_layout] Update preferred thumbnail layout for videos related to playlist. Options are ‘landscape’, ‘poster’ and ‘square’. String
playlist[categories][0][id] ID of the category assigned to the playlist if you are updating its values. String
playlist[categories][0][category_id] ID of the main Category you wish to add to the video String
playlist[categories][0][title] Title of the category assigned to the playlist String
playlist[categories][0][value][] List of values you wish to add to the category Array
playlist[images_attributes][0][id] Pass the ID of the image you wish to update on a given playlist (optional). String
playlist[images_attributes][0][title] Title of the image String
playlist[images_attributes][0][caption] Caption of the image String
playlist[images_attributes][0][attachment] Image as a file attachment  
playlist[images_attributes][0][layout] Must be one of ‘poster’ or ‘square’. Default is ‘landscape’ String
playlist[images_attributes][0][_destroy] Pass in ‘true’ if you wish to remove an image String
playlist[custom_thumbnail] Image as a file attachment  
playlist[delete_custom_thumbnail] Pass in ‘1’ if you wish to remove the custom thumbnail String

Delete a Playlist

DELETE https://api.zype.com/playlists/[id]

Parameters

Parameter Function Type
id ID of the record to delete (Example: 5389352e69702d401b000000) String

Add Video(s) to a Playlist

PUT https://api.zype.com/playlists/[id]/add_videos

Parameters

Parameter Function Type
id ID of the record (Example: 5389352e69702d401b000000) String
video_id[] A comma separated list of video IDs to add to the playlist Array

Remove Video(s) from a Playlist

PUT https://api.zype.com/playlists/[id]/remove_videos

Parameters

Parameter Function Type
id ID of the record (Example: 5389352e69702d401b000000) String
video_id[] A comma separated list of video IDs to remove from the playlist String

Playlist Object

{
  "response": {
    "_id": "5628f9354d656c46285b0000",
    "_keywords": [
      "bundle",
      "featured",
      "videos"
    ],
    "active": true,
    "auto_update_consumer_videos": true,
    "created_at": "2015-10-22T10:56:53.896-04:00",
    "deleted_at": null,
    "description": "",
    "parent_id": "5628f99f4d656c46285c0000",
    "priority": 0,
    "purchase_price": "5.0",
    "purchase_required": true,
    "related_video_ids": [
      "570daad0f283474187000669",
      "570da6a0f28347ccfc002366"
    ],
    "rental_duration": 3,
    "rental_price": "5.0",
    "rental_required": true,
    "site_id": "5468fd6569702d17ee500000",
    "title": "Featured Videos Bundle",
    "updated_at": "2016-04-21T13:43:06.965-04:00",
    "images": [
      {
        "_id": "57191023f2834757dc000028",
        "caption": "My caption",
        "title": "Boxed Set",
        "updated_at": "2016-04-21T13:38:44.834-04:00",
        "url": "http://upload.dev.zype.com/5468fd6569702d17ee500000/video_image/57191023f2834757dc000028/1461260323/original.png?1461260323"
      }
    ],
    "playlist_item_count": 1176,
    "thumbnails": [
      {
        "aspect_ratio": 1.78,
        "height": 240,
        "name": null,
        "url": "http://image.dev.zype.com/5468fd6569702d17ee500000/playlist/5628f9354d656c46285b0000/custom_thumbnail/240.png?1461254280",
        "width": 426
      },
      {
        "aspect_ratio": 1.78,
        "height": 480,
        "name": null,
        "url": "http://image.dev.zype.com/5468fd6569702d17ee500000/playlist/5628f9354d656c46285b0000/custom_thumbnail/480.png?1461254280",
        "width": 854
      },
      {
        "aspect_ratio": 1.78,
        "height": 720,
        "name": null,
        "url": "http://image.dev.zype.com/5468fd6569702d17ee500000/playlist/5628f9354d656c46285b0000/custom_thumbnail/720.png?1461254280",
        "width": 1280
      },
      {
        "aspect_ratio": 1.78,
        "height": 1080,
        "name": null,
        "url": "http://image.dev.zype.com/5468fd6569702d17ee500000/playlist/5628f9354d656c46285b0000/custom_thumbnail/1080.png?1461254280",
        "width": 1920
      }
    ]
  }
}

Category Playlists


Create

Creating a Category Playlist, is the same as creating a Playlist but setting its playlist_type with a 'category' value. You should call the POST action:

POST https://api.zype.com/playlists

with the following parameters:

Parameter Function Type
playlist[playlist_type] The playlist type to create. Accepted values: manual, category String
playlist[match_type] Videos that should match with the categories selected. Accepted values: any, all. If match_type is any, videos to be added to the playlist should match ANY of the categories selected. If match_type is all, videos to be added to the playlist should match ALL of the categories selected. String
playlist[categories] Categories that will be used to selected the proper videos to add into the playlist Array

The playlist[categories] should contain an array of hashes. Every hash will represent a category to be added with the following parameters:

Parameter Function Type
categories[category_id] ID of the category that will be referenced Integer
categories[title] Title of the category to be added String
playlist[values] Values selected of the category referenced Array

Here is an JSON example to be set as the body to create a Category Playlist:

{
  "playlist": {
    "title": "Category Playlist",
    "playlist_type": "category",
    "match_type": "any",
    "categories": [
      {
        "category_id": "1234",
        "title": "Category Title",
        "value": [
          "Category Value"
        ]
      }
    ]
  }
}

Take into account that the category_id should be included into the site's categories. To get the list of categories, please go to the categories documentation. If a category with the selected category_id doesn't exists, you will get a 422 response with the following message:

{
  "message": "Could not save playlist: Categories is invalid"
}

Update

Updating a Category Playlist, is the same as updating a Playlist but changing its categories. You should call the PUT action:

PUT https://api.zype.com/playlists/[id]

Take into account that updating a playlist categories will overwrite the current categories. So, if you want to keep your current categories and values, adding new ones, you should add them to the json body parameters. If you want to delete categories or values, you have to set the categories array only with the categories that you want for your playlist, obviating the ones that you don't need anymore

Managing Playlist Relationships

Playlist Relationships allow you to create a parent / child relationship between two playlists. This is useful for nesting playlist content within OTT apps. For example, you could create a parent playlist called "Comedy" and nest child playlists underneath called "Romantic Comedies" and "Slapstick Comedies" to provide a better user experience for your audience. To manage Playlist Relationships, we use the parent_id and priority fields of a playlist.

Parameter Function Type
playlist[parent_id] The parent playlist id. If this value is null, the playlist is a root playlist and can be used as the primary playlist within an app where all your other playlists and videos are nested under String
playlist[priority] The priority of the playlist related with its siblings. Playlists are ordered ascending by priority value Integer

When creating or updating a Playlist:

To nest a playlist under a new parent, you need to change its parent_id field to the id of the playlist you want to nest it under. If you want it to be a root playlist, then you have to set the parent_id field as null or empty

Also, take into account that 0 (zero) is the highest priority.


Create

POST https://api.zype.com/playlists

Here is an JSON example to be set as the body to create a Playlist with a relationship:

{
  "playlist": {
    "parent_id": "abcd1234",
    "priority": 1
  }
}

Update

PUT https://api.zype.com/playlists/[id]

Here is an JSON example to be set as the body to create a Playlist with a relationship:

{
  "playlist": {
    "parent_id": "abcd1234",
    "priority": 1
  }
}

Relationships

GET https://api.zype.com/playlists/relationships

Returns the list of playlists and its relationships

Here is an JSON example to returned:

{
    "playlists": [
        {
            "id": "586124bfa54d7535cb001fc2",
            "title": "Playlist A",
            "priority": 0,
            "playlists": [
                {
                    "id": "5942dde0a54d750e3b000042",
                    "title": "Playlist A.1",
                    "priority": 0
                }
            ]
        },
        {
            "id": "58d1718aa54d750bf100002e",
            "title": "Playlist B",
            "priority": 1,
            "playlists": [
                {
                    "id": "5942defea54d750e3b000045",
                    "title": "Playlist B.1",
                    "priority": 0,
                    "playlists": [
                        {
                            "id": "586124bfa54d7535cb001fba",
                            "title": "Playlist B.1.1",
                            "priority": 0
                        }
                    ]
                },
                {
                    "id": "586124bea54d7535cb001fb1",
                    "title": "Playlist B.2",
                    "priority": 1
                }
            ]
        }
    ]
}

Smart Ordering

Playlist smart ordering allows you to change the order of its videos by sort options. The videos added or updated into a playlist with sort options are sorted automatically following that sort option

Parameter | Function | Type --------- | -------- | ---- playlist[sort_options] | An array of sort options. Only two levels of sorting are accepted, and videos are sorted first by first level, and second by second level | Array

Every sort_option has three fields:


### Create

POST https://api.zype.com/playlists

Here is an JSON example to be set as the body to create a Playlist with one level smart ordering:

{
  "playlist": {
    "playlist title": "Title",
    "sort_options": [
      {
        "direction": "desc",
        "sort_by": "published_at",
        "sort_by_type": "datetime"
      }
    ]
  }
}

And with two levels smart ordering:

{
  "playlist": {
    "playlist title": "Title",
    "sort_options": [
      {
        "direction": "desc",
        "sort_by": "published_at",
        "sort_by_type": "datetime"
      },
      {
        "direction": "asc",
        "sort_by": "title",
        "sort_by_type": "string"
      }
    ]
  }
}

### Update

PUT https://api.zype.com/playlists/[id]

Here is an JSON example to be set as the body to update a Playlist with one level smart ordering:

{
  "playlist": {
    "sort_options": [
      {
        "direction": "desc",
        "sort_by": "published_at",
        "sort_by_type": "datetime"
      }
    ]
  }
}

And with two levels smart ordering:

{
  "playlist": {
    "sort_options": [
      {
        "direction": "desc",
        "sort_by": "published_at",
        "sort_by_type": "datetime"
      },
      {
        "direction": "asc",
        "sort_by": "title",
        "sort_by_type": "string"
      }
    ]
  }
}