Welcome to the Zype API Documentation
Zype API documentation provides information to web developers who wish to use Zype’s Application Programming Interfaces (APIs). The Zype API includes modules for managing videos and associated metadata. In addition, this reference describes a number of related objects. The Zype API is a RESTful API service.
Our API is designed around standard REST CRUD (Create-Read-Update-Delete) semantics:
POST - Create a resource within a given collection
GET - Get a resource or collection of resources
PUT - Update a resource
DELETE - Delete a resource
Our default is to support JSON formatting, however if you prefer XML use the
Content-Type header with value text/xml.
Authentication
There are multiple ways to authenticate to the Zype API. Your Zype channels are
automatically set up with API keys that you can integrate with, but you can also use app keys and consumer access tokens to authenticate as well.
API Keys
Your Zype channel is automatically set up with the following API keys:
- Admin Key: Admin keys have full access to your account and should not be distributed in video applications.
- Read Only Key: Read only keys have limited access to your account and are not allowed to create or modify existing resources. Read only keys should be used when distributing a video application.
- Player Key: Player keys have limited access to your account and are only
allowed to issue player requests. Player keys should be used in embed codes for web applications.
Example
GET https://api.zype.com/videos?api_key=[api_key]
App Keys
App keys are automatically created when you set up new apps. App keys provide per app authentication so that each bundled app has separate credentials. App keys are automatically bundled using Zype app builders. App keys can be retrieved from your app's detail page.
Example:
GET https://api.zype.com/videos?app_key=[app_key]
Access Tokens
Access tokens provide per user authentication for API requests. Access tokens are time based tokens that are created using OAuth. Click here for more information about using OAuth.
Example:
GET https://api.zype.com/videos?access_token=[access_token]
Errors
Zype uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required r was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Zype's servers.
200 (OK)
The request was processed successfully.
401 (Unauthorized)
The request could not be processed because no API key was provided, or the API key provided is invalid.
404 (Not Found)
The request could not be processed because the resource you are operating on could not be found.
422 (Unprocessable Entity)
The request could not be processed due to a validation rule.
500 (Server Error)
The request could not be processed due to a error on Zype's servers.
Attributes:
message - A human-readable message giving more details about the error.
Pagination
Pagination is required for all 'list' requests. The default setting for any list request is to return 10 records.
Parameters
page (optional) The page number of records to return (zero indexed).
per_page (optional) The number of records to return (Default: 10, Maximum: 100).
Attributes
Paging data is returned in the 'pagination' element on list requests. The following data is made available.
current - The current page requested
previous - The page before the page requested.
next - The page after the page requested.
per_page - The maximum number of records returned.
pages - The total number of pages available.
Example:
{
response: { },
pagination: {
current: 1,
previous: null,
next: 2,
per_page: 10,
pages: 5
}
}Video Formats
Videos published through the Zype platform support the following resolution and aspect ratios.
HLS (HTTP Live Streaming):
Resolution | Aspect | Width | Height
240p
16x9
426px
240px
360p
16x9
640px
360px
480p
16x9
854px
480px
720p
16x9
1280px
720px
1080p
16x9
1920px
1080px
WebM/MP4 Streaming:
To ensure compatibility with devices that do not support HLS, Zype provides WebM and MP4 streams.
WebM
360p
16x9
640px
360px
MP4
360p
16x9
640px
360px
Video formats are optional and are configurable in the Zype Publisher dashboard.
List Ad Timings on single Data Source
List Ad Timings for single Ad-Timeable Data Source
Create Playlist
Create a Category Playlist
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 with the following parameters:
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:
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"
}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
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:
direction: The direction to sort the results. It accepts two values:asc(ascending - lowest to highest) anddesc(descending - highest to lowest) order.sort_by: The field name which will be taken into account to sort the results. It accepts the following values:created_at,published_at, andtitle.sort_by_type: The type of the field which will be taken into account to sort the results. It accepts the following values:date,datetime,string,integer,array, andboolean. The difference betweendateanddatetimeis thatdatewill only take the date part of the field, whiledatetimewill take the date and time part of the field; so for example, for a date "01/01/2001 01:01:01",datewill take only "01/01/2001" into account, whiledatetimewill take the complete date "01/01/2001 01:01:01" into account.
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 Playlist
Update Category Playlist
Updating a Category Playlist, is the same as updating a Playlist but changing its categories.
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
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
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:
direction: The direction to sort the results. It accepts two values:asc(ascending - lowest to highest) anddesc(descending - highest to lowest) order.sort_by: The field name which will be taken into account to sort the results. It accepts the following values:created_at,published_at, andtitle.sort_by_type: The type of the field which will be taken into account to sort the results. It accepts the following values:date,datetime,string,integer,array, andboolean. The difference betweendateanddatetimeis thatdatewill only take the date part of the field, whiledatetimewill take the date and time part of the field; so for example, for a date "01/01/2001 01:01:01",datewill take only "01/01/2001" into account, whiledatetimewill take the complete date "01/01/2001 01:01:01" into account.
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": {
"playlist title": "Title",
"sort_options": [
{
"direction": "desc",
"sort_by": "published_at",
"sort_by_type": "datetime"
},
{
"direction": "asc",
"sort_by": "title",
"sort_by_type": "string"
}
]
}
}View Relationsips
Returns a list of playlists and its relationships
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.
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:
- If the
parent_idandpriorityare not set, the playlist will be set as a root playlist with the highestpriorityvalue set. - If the
parent_idis not set, but thepriorityis, then, the playlist will be set as arootplaylist, and will be ordered by the priority value set. If there is another root playlist with the same priority, then it will be added after this playlist. - If the
parent_idandpriorityare set, the playlist will be added as a child of the playlist with idparent_id, and will be ordered by thepriorityvalue set. If there is another sibling playlist with the same priority, then it will be added after the sibling.
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.
Apps
Overview
The Zype platform contains push-button app builders which allow OTT and mobile apps to be customized and built with just a few clicks. Zype app builders contain user-customizable settings specific to the app’s respective platform and SDK features. The app settings specified in the Zype platform are saved and returned by the App endpoint.
The App endpoint is used to retrieve the custom settings and content associated with an app in the Zype platform.
View App
Use Case
If customizing an existing Zype app SDK, customizing a third-party SDK for compatibility with the Zype platform, or creating a custom app from scratch, the app’s dynamic settings and content stored in the Zype platform may be retrieved using the App endpoint. In this way, an app’s settings may be updated dynamically without, in most cases, requiring a resubmission or deploying updated files.
Subtitle Playlists
Overview
The Subtitle Playlists API allows users to integrate subtitles with HLS manifests from a Zype video source. It’s a simple way to add subtitles which will be supported in all platforms that implement the Apple HLS specification.
Each Video can have many subtitles but they are limited to have only one subtitle of each language.
Retrieve manifest URL for live videos
Returns an object containing the ID and the masked URL for the manifest.