VHX Developers

Menu
cURL Ruby Node PHP Javascript
API

Introduction

API Endpoint
https://api.vhx.tv

The VHX API provides a simple and secure REST interface to VHX. Registered applications can manage products, customers, videos, collections, authorizations, and analytics.

We provide light-weight client libraries to easily interface with our resources. These are currently availble in Node.js, Ruby, and PHP. Python and Go client libraries will be added soon.

All API access is over HTTPS and all data is sent and received as JSON. Blank fields are included as null and timestamps are in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. Only the UTF-8 character encoding is supported for both requests and responses.

We support JSONP (use ?callback=) and Cross Origin Resource Sharing (CORS) for AJAX requests.

We’re always happy to help out with code or answer any questions you might have. Get in touch on our Slack Channel or email us at api@vhx.tv.

VHX Support on Slack

Authentication

API Key

API Key

Example Request

$ curl -X GET "https://api.vhx.tv/customers" \
-u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

require 'vhx-ruby'

Vhx.setup({
  api_key: 'YOUR_API_KEY'
})

var vhx = require('vhx')('YOUR_API_KEY');

var vhxjs = new vhx('YOUR_API_KEY');

<?php\VHX\API::setKey('your VHX API key');

cURL uses the -u flag to pass basic auth credentials.
Adding a colon after your API key will prevent it from asking you for a password.

API applications can be created in the VHX admin or by emailing api@vhx.tv.

Once your application is created, you will receive an API Key. All resources require authentication with this API Key over HTTP Basic Auth. Your API Key acts as the basic auth username. You do not need to provide a password (but do notice the trailing :).

When making API calls on behalf of a customer, there are two (manually set) request headers that you should be aware of:

  • VHX-Customer: should be set with the logged in customer href on all requests. This let’s the API respond with relevant information for that particular customer (things like continue watching, analytics, etc). Without this, requests will be tied to the API Key creator which can lead to unintentional behavior (rate limiting, inaccurate analytics, etc).
  • VHX-Client-IP: should be set with the IP address of your end-user when making a back-end API request on behalf of a customer. Our API will respect this IP address over the request/server IP address for the purposes of geo-blocking content, analytics, etc.

OAuth

OAuth

Example Access Token Request

curl -X POST "https://api.vhx.tv/oauth/token"
  -d client_id={client_id} \
  -d client_secret={client_secret} \
  -d grant_type="client_credentials" \
  -d scope="read"

Example Response

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 7200,
  "scope": "read"
}

Example API Request with Access Token

$ curl -X GET "https://api.vhx.tv/collections/:id" \
 -H "Authorization: Bearer ACCESS_TOKEN"

For registered applications an alternative way to access the VHX API is via OAuth access tokens. You can email api@vhx.tv to register an application.

Once your application is created, you will receive your client credentials, which includes your client_id and client_secret which can be used to make API requests.

OAuth with Pairing Codes

OAuth with Pairing Codes

Example Fetch Code Request

curl -X POST "https://api.vhx.tv/oauth/codes"
     -d client_id={client_id}
     -d client_secret={client_secret}

Example Response

{
  "code": "DDCD",
  "expires_in": 1800
}

Example Polling Request

curl -G "https://api.vhx.tv/oauth/codes/{code}" \
     -d client_id={your_client_id} \
     -d client_secret={your_client_secret}

Example Response

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "read"
}

Example Refresh Token Request

$ curl -X POST "https://api.vhx.tv/oauth/token" \
  -d grant_type=refresh_token \
  -d refresh_token={your_refresh_token}

Example Response

{
  "access_token": "YOUR_NEW_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "YOUR_NEW_REFRESH_TOKEN",
  "scope": "public"
}

To make requests on behalf of a customer for accessing content available to them, you will need to authorize the customer via application Pairing Codes.

1. Fetch the code

Applications should request a code from our API, display it on the screen for the customer, and then direct them to https://{subdomain}.vhx.tv/activate to enter the code.

2. Poll for customer activation

Upon displaying the code to the customer, you should begin polling /oauth/codes/{code} for the code at a ~2.5 second interval with a max of 500 retries.

This will return a 404 until the customer correctly pairs it with their account. At that point a 200 will be returned with an access_token, refresh_token, and expiry information. This information should be saved in your device’s registry and is what deems the device as being connected/linked to a logged in customer.

You can than make requests on behalf of the customer using the Authorization Bearer header.

3. Refresh Tokens

Access tokens for a customer expire after 2 hours. To continue making API requests you can refresh your access token by requesting a new one (from the /oauth/token endpoint) using the provided refresh_token in the previous response.

HTTP Verbs

Verb Description
HEAD Used for retrieving HTTP header information.
GET Used for retrieving and listing resources.
POST Used for creating resources or performing custom action.
PUT Used for replacing or updating resources. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE Used for deleting resources.

Hypermedia

Hypermedia

Example HAL response properties

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/videos/1" },
    "files": { "href": "https://api.vhx.tv/videos/1/files" }
  },
  "_embedded": {
    "files": []
  }
}

The VHX API implements the HAL (Hypertext Application Lanaguge) protocol. All resources have _links and _embedded properties.

The _links object includes explicit and permanent URI’s (or href’s) that API clients should use for navigational purposes. The _links.self.href propery, in particular, should be utilized as the resource unique identifier.

The _embedded object may contain other resources (objects or associations) that may be included with the current resource, saving you API requests to additionally fetch that data.

Errors

All responses use standard HTTP status codes. This status code should solely be used to determine the success or failure of a request. If a failure, there additionally will be a message key in the JSON response with a detailed error message. Below is an outline of all HTTP status codes. 
# For example, rescuing a Unauthorized Error

begin
  Vhx::Customer.retrieve("https://api.vhx.tv/customers/1")
rescue Vhx::UnauthorizedError
  # Handle Exception
end

# Mapping of error codes and the ruby exception that is thrown
{
  400 => Vhx::BadRequestError,
  401 => Vhx::UnauthorizedError,
  402 => Vhx::PaymentRequiredError,
  404 => Vhx::NotFoundError,
  406 => Vhx::NotAcceptableError,
  500...505 => Vhx::ServerError
}

/*
The Node Client Library does not throw exceptions, and instead uses
an asynchronous style of error handling.

An error from the VHX API will be available as the first argument
of any method's callback:
*/

vhx.customers.create({
  // params
}, function(err, result) {
  // if err is null, no errors occurred
});


/*
When there's an error, the first argument (err) will
be an object, with the following properties:
*/

err.message
err.documentation_url
err.status
err.type

// See the error codes to your left for error status/type reference


/*
The Javascript Client Library does not throw exceptions, and instead uses
an asynchronous style of error handling.

An error from the VHX API will be available as the first argument
of any method's callback:
*/

vhxjs.collections.all({
  // params
}, function(err, result) {
  // if err is null, no errors occurred
});


/*
When there's an error, the first argument (err) will
be an object, with the following properties:
*/

err.message
err.documentation_url
err.status
err.type

// See the error codes to your left for error status/type reference


<?phptry {
  // Use VHX library to make requests...
}
catch (\VHX\Error\InvalidRequest $e) {
  // invalid parameters were supplied

  // each error you can get the following
  echo $e->getHttpStatus();
  echo $e->getErrorResponse()['message'];
  echo $e->getErrorJSONResponse();
}
catch (\VHX\Error\ResourceNotFound $e) {
  // particular resource was not found
}
catch (\VHX\Error\Api $e) {
  // network communication with VHX API failed
}
catch (\VHX\Error\Authentication $e) {
  // authentication with VHX API failed
}
catch (Exception $e) {
  // Something else happened, unrelated to VHX
}
Status Code Description
200 OK
201 Created
304 Not Modified
400 Bad Request (Client error)
401 Unauthorized (Invalid authentication)
402 Payment Required (Premium video content)
404 Not Found
406 Not Acceptable
500…505 Internal Server Error or Unavailable

Products

A product is what represents the premium (subscription or transactional) access to your video content. Access to a product can be given to a customer on a recurring basis (a subscription), expiring (a rental), or indefinite (full purchase).

Retrieve a Product

Retrieve a product

Definiton

GET /products/:id

Vhx::Product.retrieve()

vhx.products.retrieve();

vhxjs.products.retrieve();

<?php$product = \VHX\Product::retrieve();

Example Request

$ curl -X GET "https://api.vhx.tv/products/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

product = Vhx::Product.retrieve("https://api.vhx.tv/products/1")

vhx.products.retrieve("https://api.vhx.tv/products/1", function(err, product) {
  // asynchronously called
});

vhxjs.products.retrieve("https://api.vhx.tv/products/1", function(err, product) {
  // asynchronously called
});

<?php$product = \VHX\Products::retrieve("https://api.vhx.tv/products/1");

Example Response

{
  "_links": {
    "self":        { "href": "https://api.vhx.tv/products/1" },
    "collections": { "href": "https://api.vhx.tv/collections?product=:href" },
    "customers":   { "href": "https://api.vhx.tv/customers?product=:href" }
  },
  "_embedded": {},
  "id": 1,
  "name": "Subscription NOW",
  "description": "Subscribe to Subscription NOW today!",
  "thumbnail": {},
  "price": {
    "monthly": {
      "cents": 800,
      "currency": "USD",
      "formatted": "$8"
    },
    "yearly": {
      "cents": 6500,
      "currency": "USD",
      "formatted": "$65"
    }
  },
  "is_active": true,
  "series_count": 100,
  "movies_count": 100,
  "playlists_count": 100,
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

Retrieves an existing product.

Arguments Description
href string REQUIRED The href of the product being retrieved.

List all Products

List all products

Definiton

GET /products

Vhx::Product.all()

vhx.products.all();

vhxjs.products.all();

<?php$product = \VHX\Products::all();

Example Request

$ curl -X GET -G "https://api.vhx.tv/products" \
  -d query="term" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Vhx::Product.all({
  query: 'term'
})

vhx.products.all({
  query: 'term'
}, function(err, products) {
   // asynchronously called
});

vhxjs.products.all({
  query: 'term'
}, function(err, products) {
   // asynchronously called
});

<?php$products = \VHX\Products::all({
  'query' => 'term'
});

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/products?page=1&query=term" },
    "first": { "href": "https://api.vhx.tv/products?query=term" },
    "prev":  { "href": null },
    "next":  { "href": "https://api.vhx.tv/products?page=2&query=term" },
    "last":  { "href": "https://api.vhx.tv/products?page=5&query=term" }
  },
  "count": 100,
  "total": 500,
  "_embedded": {
    "products": []
  }
}

Products can be listed for your account. A paginated result is returned.

Arguments Description
query string optional The query to search and filter the results.
sort string optional The sort to order the results. Options are alphabetical, newest, oldest, or position.
page integer optional, default is 1 The page number of the paginated result.
per_page integer optional, default is 50 The page size of the paginated result.

Customers

A customer is a person who has been granted access to a product. By having access to the product, they inherently have access to all of its content (videos / collections).

Create a Customer

Create a customer

Definition

POST /customers

Vhx::Customer.create()

vhx.customers.create();

// Not available for client-side requests.

<?php$customer = \VHX\Customers::create();

Example Request

$ curl -X POST "https://api.vhx.tv/customers" \
  -d name="First Last" \
  -d email="customer@email.com" \
  -d product="https://api.vhx.tv/products/1" \
  -d plan="standard" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

customer = Vhx::Customer.create({
  name: 'First Last',
  email: 'customer@email.com',
  product: 'https://api.vhx.tv/products/1',
  plan: 'standard'
})

vhx.customers.create({
  name: 'First Last',
  email: 'customer@email.com',
  product: 'https://api.vhx.tv/products/1',
  plan: 'standard'
}, function(err, customer) {
  // asynchronously called
});

// Not available for client-side requests.

<?php$customer = \VHX\Customers::create(array(
  'name' => 'First Last',
  'email' => 'customer@email.com',
  'product' => 'https://api.vhx.tv/products/1',
  'plan' => 'standard'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers/1" }
  },
  "_embedded": {},
  "id": 1,
  "name": "First Last",
  "email": "customer@email.com",
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z",
  "plan": "standard"
}
A customer can be created (or added) for a given product. For a subscription customer, you are billed per customer / per month. Please see our pricing for more details.
Arguments Description
name string optional The customer’s full name (first and last).
email string REQUIRED The customer’s email address.
product string REQUIRED The href of the product you’d like to give the customer access to.
billing object optional Billing parameters for In-App Purchases for the Apple, Google, and Roku platforms.
plan string optional, default is “standard” The customer’s plan determines content accessibility. Values can be one of the following strings: free, standard. See Update Video for more detail on the types of plans

Retrieve a Customer

Retrieve a customer

Definition

GET /customers/:id

Vhx::Customer.retrieve()

vhx.customers.retrieve();

vhxjs.customers.retrieve();

<?php$customer = \VHX\Customers::retrieve();

Example Request

$ curl -X GET "https://api.vhx.tv/customers/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

customer = Vhx::Customer.retrieve("https://api.vhx.tv/customers/1")

vhx.customers.retrieve("https://api.vhx.tv/customers/1", function(err, customer) {
  // asynchronously called
});

vhxjs.customers.retrieve("https://api.vhx.tv/customers/1", function(err, customer) {
  // asynchronously called
});

<?php$customer = \VHX\Customers::retrieve("https://api.vhx.tv/customers/1");

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers/1" },
    "watchlist": { "href": "https://api.vhx.tv/customers/1/watchlist" },
    "watching": { "href": "https://api.vhx.tv/customers/1/watching" }
  },
  "_embedded": {},
  "id": 1,
  "name": "First Last",
  "email": "customer@email.com",
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z",
  "plan": "standard"
}

Retrieves an existing customer. You can optionally specify a product parameter to scope the customer retrieval to it (ie. “Is this customer subscribed to this product?”).

Arguments Description
href string REQUIRED The href of the customer being retrieved.
product string optional The href of a product.

Retrieve with In-App Purchase billing data

Retrieve with In-App Purchase billing data

Definition

POST /customers/find_by_billing

Example Request

$ curl -X POST "https://api.vhx.tv/customers/find_by_billing" \
  -d billing[provider]="apple" \
  -d billing[receipt]="MIIcVgYJKoZIhv..." \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers/1" },
    "watchlist": { "href": "https://api.vhx.tv/customers/1/watchlist" },
    "watching": { "href": "https://api.vhx.tv/customers/1/watching" }
  },
  "_embedded": {
      "oauth": {
        "access_token": "3e0b2925500c3cc87b3c8ab47c93041f16e167ee5b949855e41fef7a3eb87ee3",
        "token_type": "bearer",
        "expires_in": 7200
      }
  },
  "id": 1,
  "name": "First Last",
  "email": "customer@email.com",
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

Retrieves an existing customer with In-App Purchase billing data.

Arguments Description
billing object REQUIRED The billing provider and receipt for the In-App Purchase.
product string REQUIRED The href of a product.

List all Customers

List all customers

Definition

GET /customers

Vhx::Customer.all()

vhx.customers.all();

vhxjs.customers.all();

<?php$customer = \VHX\Customers::all();

Example Request

$ curl -X GET -G "https://api.vhx.tv/customers" \
  -d query="term" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Vhx::Customer.all({
  query: 'term'
})

vhx.customers.all({
  query: 'term'
}, function(err, collections) {
   // asynchronously called
});

vhxjs.customers.all({
  query: 'term'
}, function(err, collections) {
   // asynchronously called
});

<?php$customers = \VHX\Customers::all(array(
  'query' => 'term'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers?page=1&query=term" },
    "first": { "href": "https://api.vhx.tv/customers?query=term" },
    "prev":  { "href": null },
    "next":  { "href": "https://api.vhx.tv/customers?page=2&query=term" },
    "last":  { "href": "https://api.vhx.tv/customers?page=5&query=term" }
  },
  "count": 100,
  "total": 500,
  "_embedded": {
    "customers": [
      { customer object }
      { ... }
    ]
  }
}

Customers can be listed for your account or for a given product. A paginated result is returned.

Arguments Description
product string optional The href of a product.
email string optional The email address to find in the paginated results.
query string optional The query to search and filter the paginated results.
sort string optional The sort to order the results. Options are newest, oldest, or latest.
page integer optional, default is 1 The page number of the paginated result.
per_page integer optional, default is 50 The page size of the paginated result.

Update a Customer

Update a customer

Definition

PUT /customers/:id

Vhx::Customer.update()

vhx.customers.update();

// Not available for client-side requests.

<?php$customer = \VHX\Customers::update();

Example Request

$ curl -X PUT "https://api.vhx.tv/customers/1" \
  -d name="First Last" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Vhx::Customer.update("https://api.vhx.tv/customers/1", {
  name: 'First Last'
})

vhx.customers.update("https://api.vhx.tv/customers/1", {
  name: 'First Last'
}, function(err, customer) {
   // asynchronously called
});

// Not available for client-side requests.

<?php$customers = \VHX\Customers::update("https://api.vhx.tv/customers/1", array(
  'name' => 'First Last'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers/1" }
  },
  "_embedded": {},
  "id": 1,
  "name": "First Last",
  "email": "customer@email.com",
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

Updates an existing customer.

Arguments Description
name string optional The customer’s full name (first and last).
email string optional The customer’s email address.

Add a Product

Add a product

Definition

PUT /customers/:id/products

Vhx::Customer.addProduct()

vhx.customers.addProduct();

// Not available for client-side requests.

<?php\VHX\Customers::addProduct();

Example Request

$ curl -X PUT "https://api.vhx.tv/customers/1/products" \
  -d product=https://api.vhx.tv/products/1 \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Vhx::Customer.addProduct('https://api.vhx.tv/customers/1', {
  product: 'https://api.vhx.tv/products/1'
})

vhx.customers.addProduct('https://api.vhx.tv/customers/1', {
  product: 'https://api.vhx.tv/products/1'
}, function(err, customer) {
   // asynchronously called
});

// Not available for client-side requests.

<?php$customer = \VHX\Customers::addProduct("https://api.vhx.tv/customers/1",
 array(
  'product' => 'https://api.vhx.tv/products/1'
));

Adds a product to an existing customer. By adding a product, he or she now has access to all of its contents.

Arguments Description
href string REQUIRED The href of the customer.
product string REQUIRED The href of the product.

Remove a Product

Remove a product

Definition

DELETE /customers/:id/products

Vhx::Customer.removeProduct()

vhx.customers.removeProduct();

// Not available for client-side requests.

<?php$customer = \VHX\Customers::removeProduct();

Example Request

$ curl -X DELETE "https://api.vhx.tv/customers/1/products" \
  -d product=https://api.vhx.tv/products/1 \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Vhx::Customer.removeProduct('https://api.vhx.tv/customers/1', {
  product: 'https://api.vhx.tv/products/1'
})

vhx.customers.removeProduct('https://api.vhx.tv/customers/1', {
  product: 'https://api.vhx.tv/products/1'
}, function(err, customer) {
   // asynchronously called
});

// Not available for client-side requests.

<?php$customer = \VHX\Customers::removeProduct("https://api.vhx.tv/customers/1",
 array(
  'product' => 'https://api.vhx.tv/products/1'
));

Removes a product from an existing customer. By removing a product, the customer will no longer have access to its contents.

Arguments Description
href string REQUIRED The href of the customer.
product string REQUIRED The href of the product.

Retrieve Watching Items

Retrieve Watching Items

Definition

GET /customers/:id/watching

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not yet available for the Javascript client.

<?php$customer = \VHX\Watching::items();

Example Request

$ curl -X GET "https://api.vhx.tv/customers/1/watching" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not yet available for the Javascript client.

<?php$watching = \VHX\Watching::items("https://api.vhx.tv/customers/1");

Example Response

{
  "_links": {
    "self": {
      "href": "https://api.vhx.tv/customers/1/watching?page=1&per_page=50"
    },
    "first": {
      "href": "https://api.vhx.tv/customers/1/watching"
    },
    "prev": {
      "href": null
    },
    "next": {
      "href": null
    },
    "last": {
      "href": "https://api.vhx.tv/customers/1/watching"
    }
  },
  "count": 0,
  "total": 0,
  "_embedded": {
    "items": {
      { video object }
      { ... }
    }
  }
}

Retrieves the videos currently in progress for a customer.

For applications that are integrated via OAuth2 access tokens with our user authentication system can use the alias https://api.vhx.tv/me/watching when making cURL requests.

Arguments Description
href string REQUIRED The href of the customer being retrieved.

Retrieve Watchlist Items

Retrieve Watchlist Items

Definition

GET /customers/:id/watchlist

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

<?php$watchlist = \VHX\Watchlist::items();

Example Request

$ curl -X GET "https://api.vhx.tv/customers/1/watchlist" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

<?php\VHX\Watchlist::items(array(
  "customer" => "https://api.vhx.tv/customers/1"
));

Example Response

{
  "_links": {
    "self": {
      "href": "https://api.vhx.tv/customers/1/watchlist?page=1&per_page=50"
    },
    "first": {
      "href": "https://api.vhx.tv/customers/1/watchlist"
    },
    "prev": {
      "href": null
    },
    "next": {
      "href": null
    },
    "last": {
      "href": "https://api.vhx.tv/customers/1/watchlist"
    }
  },
  "count": 0,
  "total": 0,
  "_embedded": {
    "items": [
      { video object }
      { ... }
    ]
  }
}

Retrieves watchlist items for a given customer.

For applications that are integrated via OAuth2 access tokens with our user authentication system can use the alias https://api.vhx.tv/me/watchlist when making cURL requests.

Arguments Description
customer string REQUIRED The href of the customer.

Add Item to Watchlist

Add Item to Watchlist

Definition

PUT /customers/:id/watchlist

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

<?php\VHX\Watchlist::addItem();

Example Request

$ curl -X PUT "https://api.vhx.tv/customers/1/watchlist" \
  -d video="http://api.vhx.tv/videos/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

<?php\VHX\Watchlist::addItem(array(
  "customer" => "https://api.vhx.tv/customers/1",
  "video" => "https://api.vhx.tv/videos/1"
));

Adds an item (a video) to a customer’s watchlist.

For applications that are integrated via OAuth2 access tokens with our user authentication system can use the alias https://api.vhx.tv/me/watchlist when making cURL requests.

Arguments Description
customer string REQUIRED The href of the customer.
video string REQUIRED The href of the video to be added.

Remove Item from Watchlist

Remove Item from Watchlist

Definition

DELETE /customers/:id/watchlist

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

<?php\VHX\Watchlist::removeItem();

Example Request

$ curl -X DELETE "https://api.vhx.tv/customers/1/watchlist" \
  -d video="http://api.vhx.tv/videos/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

<?php\VHX\Watchlist::removeItem(array(
  "customer" => "https://api.vhx.tv/customers/1",
  "video" => "https://api.vhx.tv/videos/1"
));

Removes an item (a video) from a customer’s watchlist.

For applications that are integrated via OAuth2 access tokens with our user authentication system can use the alias https://api.vhx.tv/me/watchlist when making cURL requests.

Arguments Description
customer string REQUIRED The href of the customer.
video string REQUIRED The href of the video to be removed.

Videos

A video represents a playable resource. In addition to it’s core properties, a video has a set of files (each with multiple renditions) available to stream. A particular file has a specific quality, format, method, and mime type:

Property Available values
quality 1080p, 720p, 540p, 480p, 360p, adaptive
format m3u8, mpd, mp4, webm, ogg
method hls, dash, progressive
mime_type application/x-mpegURL, application/dash+xml, video/mp4

A video object has a tracks property. This includes subtitles. A subtitle track is a sidecar WebVTT or SRT file.

DRM (Digital Rights Management) is available, per request, for an additional cost. We support Google Widevine, Adobe Access, and OMA.

Create a Video

Create a Video

Definiton

POST /videos

Vhx::Video.create()

vhx.videos.create();

// Not available for client-side requests.

<?php\VHX\Videos::create();

Example Request

$ curl -X POST "https://api.vhx.tv/videos" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Video","description":"My video description.",
"source_url":"s3:://YOUR_BUCKET_NAME/FILE.mp4", "metadata": {"director": "Brad Pitt", "writers":
["Foo Bar", "Bar Foo"], "release_year": 2017, "custom_icon":
"image_url:https://vhx.imgix.net/site/assets/1231.jpg"}, "plans": ["public", "free", "standard"],
"time_available": "2014-03-01T00:00:00Z", "time_unavailable": "2014-04-01T00:00:00Z"}' \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

video = Vhx::Video.create({
  title: 'My Video',
  description: 'My video description.',
  source_url: 's3:://YOUR_BUCKET_NAME/FILE.mp4',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017,
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg",
  },
  plans: ['public', 'free', 'standard'],
  time_available: '2014-03-01T00:00:00Z',
  time_unavailable: '2014-04-01T00:00:00Z'
})

vhx.videos.create({
  title: 'My Video',
  description: 'My video description.',
  source_url: 's3:://YOUR_BUCKET_NAME/FILE.mp4',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017,
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg"
  },
  plans: ['public', 'free', 'standard'],
  time_available: '2014-03-01T00:00:00Z',
  time_unavailable: '2014-04-01T00:00:00Z',
}, function(err, video) {
   // asynchronously called
});

// Not available for client-side requests.

<?php$video = \VHX\Videos::create(array(
  'title' => 'My Video',
  'description' => 'My video description.',
  'source_url' => 's3:://YOUR_BUCKET_NAME/FILE.mp4',
  'metadata' => array(
    'director' => 'Brad Pitt',
    'writers' => ['Foo Bar', 'Bar Foo'],
    'release_year' => 2017,
    'custom_icon' => 'image_url:https://vhx.imgix.net/site/assets/1231.jpg'
  ),
  'plans' => ['public', 'free', 'standard'],
  'time_available' => '2014-03-01T00:00:00Z',
  'time_unavailable' => '2014-03-01T00:00:00Z'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/videos/1" },
    "files": { "href": "https://api.vhx.tv/videos/1/files" }
  },
  "_embedded": {
    "files": []
  },
  "id": 1,
  "title": "My Video",
  "description": "My video description.",
  "status": "processing",
  "duration": {
    "seconds": 7200,
    "formatted": "02:00:00"
  },
  "thumbnail": {
    "small": "https://cdn.vhx.tv/assets/thumbnails/default-small.png",
    "medium": "https://cdn.vhx.tv/assets/thumbnails/default-medium.png",
    "large": "https://cdn.vhx.tv/assets/thumbnails/default-large.png",
    "source": "https://cdn.vhx.tv/assets/thumbnails/original.jpg"
  },
  "tracks": {
    "subtitles": []
  },
  "advertising": {},
  "metadata": {
    "director": "Brad Pitt",
    "writers": ["Foo Bar", "Bar Foo"],
    "release_year": 2017,
    "custom_icon": {
      "small": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=135&w=240",
      "medium": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=360&w=640",
      "large": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=720&w=1280",
      "source": "https://vhx.imgix.net/site/assets/1231.jpg"
    },
    "advertising_keywords": []
  },
  "plans": ["public", "free", "standard"],
  "time_available": "2014-03-01T00:00:00Z",
  "time_unavailable": "2014-04-01T00:00:00Z",
  "plays_count": 1340,
  "finishes_count": 1204,
  "files_count": 0,
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

A video can be created via the API and subsequently organized by adding it to a collection (see below).

Arguments Description
title REQUIRED string A title for the video.
source_url optional string, default is null An accessible master video file per our compression settings. To grant us permission to download the video source_url from your S3 bucket, see our S3 policy.
description optional string, default is null A description for the video.
metadata object of key value pairs A set of key/value pairs that you can attach to a video object. It can be useful for storing additional information about the video in a structured format.

Metadata keys must be strings. There are a few reserved keys that are auto-generated, which cannot be updated. These reserved keys are: advertising_keywords, series_name, season_name, season_number, episode_number, and movie_name

Metadata values can be strings, integers, arrays, or images. An image metadata value must must be a url of an image, hosted on vhx, prefixed with the text image_url:.
plans array of strings An array of plan types that you can use to set video availability. Values can be one or more of the following strings: public, free, standard.

The public plan makes the video object available without email registration or paid subscription.

The free plan makes the video object available for free, but requires user email registration

The standard plan makes the video object available to paying subscribers.
time_available optional string, default is null ISO8601 timestamp for scheduling the video to be available in the future.
YYYY-MM-DDTHH:MM:SSZ
time_unavailable optional string, default is null ISO8601 timestamp for scheduling the video to be unavailable in the future.
YYYY-MM-DDTHH:MM:SSZ

Retrieve a Video

Retrieve a Video

Definiton

GET /videos/:id

Vhx::Videos.retrieve()

vhx.videos.retrieve();

vhxjs.videos.retrieve();

<?php\VHX\Videos::retrieve();

Example Request

$ curl -X GET "https://api.vhx.tv/videos/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

video = Vhx::Video.retrieve("https://api.vhx.tv/videos/1")

vhx.videos.retrieve("https://api.vhx.tv/videos/1", function(err, video) {
  // asynchronously called
});

vhxjs.videos.retrieve("https://api.vhx.tv/videos/1", function(err, video) {
  // asynchronously called
});

<?php$video = \VHX\Videos::retrieve("https://api.vhx.tv/videos/1");

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/videos/1" },
    "files": { "href": "https://api.vhx.tv/videos/1/files" }
  },
  "_embedded": {
    "files": [
      {
        "_links": {
          "self":  { "href": "https://api.vhx.tv/videos/1/files?quality=adaptive&format=m3u8" }
        },
        "quality": "adaptive",
        "format": "m3u8",
        "method": "hls",
        "size": {
          "bytes": 1073741824,
          "formatted": "1 GB"
        },
        "mime_type": "application/x-mpegURL"
      }
    ]
  },
  "id": 1,
  "title": "My Video",
  "description": "My video description.",
  "status": "uploaded",
  "duration": {
    "seconds": 7200,
    "formatted": "02:00:00"
  },
  "thumbnail": {
    "small": "https://cdn.vhx.tv/assets/thumbnails/default-small.png",
    "medium": "https://cdn.vhx.tv/assets/thumbnails/default-medium.png",
    "large": "https://cdn.vhx.tv/assets/thumbnails/default-large.png",
    "source": "https://cdn.vhx.tv/assets/thumbnails/original.jpg"
  },
  "tracks": {
    "subtitles": [
      {
        "_links": {
            "srt": { "href": "https://cdn.vhx.tv/file.srt" },
            "vtt": { "href": "https://cdn.vhx.tv/file.vtt" }
        },
        "label": "English",
        "srclang": "en",
        "kind": "subtitles"
      }
    ]
  },
  "advertising": {
    "_links": {
      "tag": { "href": "https://static.vhx.tv/vmap.xml" }
    },
    "client": "vmap",
    "provider": "dfp",
    "custom_params": {
      "foo": ["some", "value"],
      "bar": ["other", "thing"]
    }
  },
  "metadata": {
    "director": "Brad Pitt",
    "writers": ["Foo Bar", "Bar Foo"],
    "release_year": 2017,
    "series_name": "Series Name",
    "season_name": "Season 1",
    "season_number": 1,
    "episode_number": 5,
    "custom_icon": {
      "small": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=135&w=240",
      "medium": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=360&w=640",
      "large": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=720&w=1280",
      "source": "https://vhx.imgix.net/site/assets/1231.jpg"
    },
    "advertising_keywords": []
  },
  "plans": ["public", "free", "standard"],
  "time_available": "2014-03-01T00:00:00Z",
  "time_unavailable": "2014-04-01T00:00:00Z",
  "files_count": 5,
  "plays_count": 1340,
  "finishes_count": 1204,
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

Retrieves an existing video.

Arguments Description
href string REQUIRED The href of the video being retrieved.
Response

Videos that are associated with a collection will have relevant metadata automatically applied in the metadata property. This includes the following fields: series_name, season_name, season_number, episode_number, and movie_name

Videos that are associated with a product that have advertising enabled will include an advertising property in the response. The advertising object contains relevant data for the Ad provider and tag url. In addition, if advertising keywords have been setup they will be returned in the metadata property.

List all Videos

List all Videos

Definiton

GET /videos

Vhx::Video.all()

vhx.videos.all();

vhxjs.videos.all();

<?php\VHX\Videos::all();

Example Request

$ curl -X GET -G "https://api.vhx.tv/videos" \
  -d query="term" \
  -d plan="standard" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

video = Vhx::Video.all({
  query: 'term',
  plan: 'standard'
})

vhx.videos.all({
  query: 'term',
  plan: 'standard'
}, function(err, videos) {
   // asynchronously called
});

vhxjs.videos.all({
  query: 'term',
  plan: 'standard'
}, function(err, videos) {
   // asynchronously called
});

<?php$videos = \VHX\Videos::all(array(
  'query' => 'term',
  'plan' => 'standard'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/videos?page=1&query=term&plan=standard" },
    "first": { "href": "https://api.vhx.tv/videos?query=term&plan=standard" },
    "prev":  { "href": null },
    "next":  { "href": "https://api.vhx.tv/videos?page=2&query=term&plan=standard" },
    "last":  { "href": "https://api.vhx.tv/videos?page=5&query=term&plan=standard" }
  },
  "count": 100,
  "total": 500,
  "_embedded": {
    "videos": []
  }
}

Videos can be listed. A paginated result is returned.

Arguments Description
query string optional The query to search and filter the paginated results.
plan string optional The plan(s) to filter the paginated results. The value can be an array or comma separated string.
sort string optional The sort to order the results. Options are alphabetical, newest, oldest, plays, finishes, or duration.
page integer optional, default is 1 The page number of the paginated result.
per_page integer optional, default is 50 The page size of the paginated result.

List all Files

List all Files

Definiton

GET /videos/:id/files

Vhx::Video.files()

vhx.videos.files();

// Not available for client-side requests.

<?php\VHX\Videos::files();

Example Request

$ curl -X GET "https://api.vhx.tv/videos/1/files?quality=adaptive&format=m3u8" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

video = Vhx::Video.retrieve("https://api.vhx.tv/videos/1")
video.files({ quality: 'adaptive', format: 'm3u8' })

vhx.videos.files({
  video: 'https://api.vhx.tv/video/1'
  quality: 'adaptive',
  format: 'm3u8'
}, function(err, files) {
   // asynchronously called
});

// Not available for client-side requests.

<?php$files = \VHX\Videos::files(array(
  'video' => 'https://api.vhx.tv/videos/1'
  'quality' => 'adaptive',
  'format' => 'm3u8'
));

Example Response

[{
  "_links": {
    "self":   { "href": "https://api.vhx.tv/videos/1/files?quality=adaptive&format=m3u8" },
    "source": { "href": "https://video.vhx.tv/mymovie/adaptive.m3u8?token=f4v3v3i4c2o209_3" }
  },
  "quality": "adaptive",
  "format": "m3u8",
  "method": "hls",
  "size": {
    "bytes": 1073741824,
    "formatted": "1 GB"
  },
  "mime_type": "application/x-mpegURL",
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}]

Video files are private and protected by default. They can only be accessed by the account owner or an authorized customer.

If building a customer-based application, Authorizations must be used so our player can properly authenticate and record analytics for the viewing customer.

The returned source href has a TTL / expiration, so it is advised that the files API call happens just prior to a stream action.

Update a Video

Update a Video

Definition

PUT /videos/:id

Vhx::Video.update()

vhx.videos.update();

// Not available for client-side requests.

<?php\VHX\Videos::update();

Example Request

$ curl -X PUT "https://api.vhx.tv/videos/1" \
  -H "Content-Type: application/json" \
  -d '{"description":"My video description.", "metadata": {"producer": "Christoper Nolan",
"director": "Brad Pitt", "writers": ["Foo Bar", "Bar Foo"], "release_year": 2017, "custom_icon":
"image_url:https://vhx.imgix.net/site/assets/1231.jpg"}, "plans": ["public", "free", "standard"],
"time_available": "2014-03-01T00:00:00Z", "time_unavailable": "2014-04-01T00:00:00Z"}' \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

video = Vhx::Video.retrieve("https://api.vhx.tv/videos/1").update({
  description: 'A new description',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017,
    producer: 'Christoper Nolan',
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg",
  },
  plans: ["public", "free", "standard"],
  time_available: '2014-03-01T00:00:00Z',
  time_unavailable: '2014-04-01T00:00:00Z',
})

vhx.videos.update("https://api.vhx.tv/videos/1", {
  description: 'A new description',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017,
    producer: 'Christoper Nolan',
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg"
  },
  plans: ["public", "free", "standard"],
  time_available: '2014-03-01T00:00:00Z',
  time_unavailable: '2014-04-01T00:00:00Z',
}, function(err, video) {
  // asynchronously called
});

// Not available for client-side requests.

<?php$video = \VHX\Videos::update("https://api.vhx.tv/videos/1", array(
  'name' => 'A new description',
  'metadata' => array(
    'director' => 'Brad Pitt',
    'writers' => ['Foo Bar', 'Bar Foo'],
    'release_year' => 2017,
    'producer' => 'Christoper Nolan'
  ),
  'plans' => ['public', 'free', 'standard'],
  'time_available' => '2014-03-01T00:00:00Z',
  'time_unavailable' => '2014-03-01T00:00:00Z'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/videos/1" },
    "files": { "href": "https://api.vhx.tv/videos/1/files" }
  },
  "_embedded": {
    "files": []
  },
  "id": 1,
  "title": "My Video",
  "description": "My video description.",
  "status": "processing",
  "duration": {
    "seconds": 7200,
    "formatted": "02:00:00"
  },
  "thumbnail": {
    "small": "https://cdn.vhx.tv/assets/thumbnails/default-small.png",
    "medium": "https://cdn.vhx.tv/assets/thumbnails/default-medium.png",
    "large": "https://cdn.vhx.tv/assets/thumbnails/default-large.png",
    "source": "https://cdn.vhx.tv/assets/thumbnails/original.jpg"
  },
  "tracks": {
    "subtitles": []
  },
  "advertising": {},
  "metadata": {
    "director": "Brad Pitt",
    "producer": "Christoper Nolan",
    "writers": ["Foo Bar", "Bar Foo"],
    "release_year": 2017,
    "custom_icon": {
      "small": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=135&w=240",
      "medium": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=360&w=640",
      "large": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=720&w=1280",
      "source": "https://vhx.imgix.net/site/assets/1231.jpg"
    },
    "advertising_keywords": []
  },
  "plans": ["public", "free", "standard"],
  "files_count": 0,
  "plays_count": 1340,
  "finishes_count": 1204,
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

No fields are required when updating a video.

Arguments Description
title string optional A title for the video.
description string optional A description for the video.
metadata object of key value pairs A set of key/value pairs that you can attach to a video object. It can be useful for storing additional information about the video in a structured format.

Metadata keys must be strings. There are a few reserved keys that are auto-generated, which cannot be updated. These reserved keys are: advertising_keywords, series_name, season_name, season_number, episode_number, and movie_name

Metadata values can be strings, integers, arrays, or images. An image metadata value must must be a url of an image, hosted on vhx, prefixed with the text image_url:.
plans array of strings An array of plan types that you can use to set video availability. Values can be one or more of the following strings: public, free, standard.

The public plan makes the video object available without email registration or paid subscription.

The free plan makes the video object available for free, but requires user email registration

The standard plan makes the video object available to paying subscribers.
time_available string optional ISO8601 timestamp for scheduling the video to be available in the future.
YYYY-MM-DDTHH:MM:SSZ
time_unavailable string optional ISO8601 timestamp for scheduling the video to be unavailable in the future.
YYYY-MM-DDTHH:MM:SSZ

Collections

A collection is the way to organize and add metadata around your videos. There are 6 types of collections:

Type Definition
section A high level grouping of categories. “Genres” is an example.
category A way to group other primary collections (series, movies, and playlists). An example of this is “Drama” or “Comedy”.
series A representation of a show with one or many seasons as its items.
season A representation of a season within a series. A season has one or many episodes.
movie A collection that gives emphasis to a featured video with support for additional extras.
playlist A loose grouping of related videos that can be manually positioned for display.

Create a Collection

Create a Collection

Definition

POST /collections

Vhx::Collection.create()

vhx.collections.create();

// Not available for client-side requests.

<?php\VHX\Collections::create();

Example Request

$ curl -X POST "https://api.vhx.tv/collections" \
  -H "Content-Type: application/json" \
  -d '{"name": "Collection Name", "type": "series", "metadata": {"director": "Brad Pitt", "writers":
["Foo Bar", "Bar Foo"], "release_year": 2017, "custom_icon":
"image_url:https://vhx.imgix.net/site/assets/1231.jpg"}, "plans": ["public", "free", "standard"]}' \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

collection = Vhx::Collection.create({
  name: 'Collection Name',
  type: 'series',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017,
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg",
  },
  plans: ["public", "free", "standard"]
})

vhx.collections.create({
  name: 'Collection Name',
  type: 'series',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017,
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg"
  },
  plans: ["public", "free", "standard"]
}, function(err, collection) {
  // asynchronously called
});

// Not available for client-side requests.

<?php$collection = \VHX\Collections::create(array(
  'name' => 'Collection Name',
  'type' => 'series',
  'metadata' => array(
    'director' => 'Brad Pitt',
    'writers' => ['Foo Bar', 'Bar Foo'],
    'release_year' => 2017,
    'custom_icon' => 'image_url:https://vhx.imgix.net/site/assets/1231.jpg'
  ),
  'plans' => ['public', 'free', 'standard']
));

Example Response

{
  "_links": {
    "self": {
      "href": "http://api.vhx.tv/collections/1"
    },
    "items": {
      "href": "http://api.vhx.tv/collections/1/items"
    },
    "collection_page": {
      "href": "http://mynetwork.com/collection-name-1"
    }
  },
  "_embedded": {
    "trailer": null
  },
  "id": 1,
  "name": "Collection Name",
  "description": null,
  "slug": "collection-name",
  "thumbnail": {
    "small": "https://cdn.vhx.tv/assets/thumbnails/default-small.png",
    "medium": "https://cdn.vhx.tv/assets/thumbnails/default-medium.png",
    "large": "https://cdn.vhx.tv/assets/thumbnails/default-large.png",
    "source": "https://cdn.vhx.tv/assets/thumbnails/original.jpg"
  },
  "metadata": {
    "director": "Brad Pitt",
    "writers": ["Foo Bar", "Bar Foo"],
    "release_year": 2017,
    "custom_icon": {
      "small": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=135&w=240",
      "medium": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=360&w=640",
      "large": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=720&w=1280",
      "source": "https://vhx.imgix.net/site/assets/1231.jpg"
    },
  },
  "plans": ["public", "free", "standard"],
  "type": "series",
  "seasons_count": 0,
  "items_count": 0,
  "files_count": 0,
  "created_at": "2015-11-25T01:30:33Z",
  "updated_at": "2015-11-25T01:30:33Z"
}

When creating a collection, you need to provide a collection type and name. See below for the required and optional arguments:

Arguments Description
type string REQUIRED The type of collection: section, category, series, season, movie, or playlist.
name string REQUIRED The name of the collection.
description optional The collection description.
thumbnail_url optional A publicly accessible image URL. If you prefer you can upload images directly to a collection in the VHX Publisher Admin.
metadata optional object A set of key/value pairs that you can attach to a collection object. It can be useful for storing additional information about the collection in a structured format.

Metadata keys must be strings. There are a few reserved keys that are auto-generated, which cannot be updated. For collections, the following key is reserved: season_number

Metadata values can be strings, integers, arrays, or images. An image metadata value must must be a url of an image, hosted on vhx, prefixed with the text image_url:.
plans array of strings An array of plan types that you can use to set collection availability. Values can be one or more of the following strings: public, free, standard.

The public plan makes the collection object available without email registration or paid subscription.

The free plan makes the collection object available for free, but requires user email registration

The standard plan makes the collection object available to paying subscribers.

Retrieve a Collection

Retrieve a Collection

Definition

GET /collections/:id

Vhx::Collection.retrieve()

vhx.collections.retrieve();

vhxjs.collections.retrieve();

<?php\VHX\Collections::retrieve();

Example Request

$ curl -X GET "https://api.vhx.tv/collections/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

collection = Vhx::Collection.retrieve("https://api.vhx.tv/collections/1")

vhx.collections.retrieve("https://api.vhx.tv/collections/1",
 function(err, collection) {
  // asynchronously called
 });

vhxjs.collections.retrieve("https://api.vhx.tv/collections/1", function(err, collection) {
  // asynchronously called
});

<?php$collection = \VHX\Collections::retrieve("https://api.vhx.tv/collections/1");

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/collections/1" },
    "items": { "href": "https://api.vhx.tv/collections/1/items" }
  },
  "id": 1,
  "name": "Comedy",
  "description": "Comedy series and movies.",
  "slug": "comedy",
  "thumbnail": {
    "small": "https://cdn.vhx.tv/assets/thumbnails/default-small.png",
    "medium": "https://cdn.vhx.tv/assets/thumbnails/default-medium.png",
    "large": "https://cdn.vhx.tv/assets/thumbnails/default-large.png",
    "source": "https://cdn.vhx.tv/assets/thumbnails/original.jpg"
  },
  "metadata": {
    "director": "Brad Pitt",
    "writers": ["Foo Bar", "Bar Foo"],
    "release_year": 2017,
    "custom_icon": {
      "small": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=135&w=240",
      "medium": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=360&w=640",
      "large": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=720&w=1280",
      "source": "https://vhx.imgix.net/site/assets/1231.jpg"
    },
  },
  "plans": ["public", "free", "standard"],
  "type": "category",
  "items_count": 10,
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z"
}

Retrieves an existing collection. You can optionally specify a product parameter to scope the collection retrieval to it.

Arguments Description
id integer REQUIRED The id of collection being retrieved.
product string optional The href of a product.

List all Collections

List all Collections

Definition

GET /collections

Vhx::Collection.all()

vhx.collections.all();

vhxjs.collections.all();

<?php\VHX\Collections::all();

Example Request

$ curl -X GET -G "https://api.vhx.tv/collections" \
  -d product=https://api.vhx.tv/products/1 \
  -d plan=standard
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

collections = Vhx::Collection.all({
  product: 'https://api.vhx.tv/products/1',
  plan: 'standard'
})

vhx.collections.all({
  product: 'https://api.vhx.tv/products/1',
  plan: 'standard'
}, function(err, collections) {
  // asynchronously called
});

vhxjs.collections.all({
  product: 'https://api.vhx.tv/products/1',
  plan: 'standard'
}, function(err, collections) {
  // asynchronously called
});

<?php$collections = \VHX\Collections::all(array(
  'product' => 'https://api.vhx.tv/products/1',
  'plan' => 'standard'
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/collections?page=1&product=:href&plan=standard" },
    "first": { "href": "https://api.vhx.tv/collections?product=:href&plan=standard" },
    "prev":  { "href": null },
    "next":  { "href": "https://api.vhx.tv/collections?page=2&product=:href&plan=standard" },
    "last":  { "href": "https://api.vhx.tv/collections?page=5&product=:href&plan=standard" }
  },
  "count": 100,
  "total": 500,
  "_embedded": {
    "collections": []
  }
}

Collections can be listed for your account or for a given product. A paginated result is returned.

Arguments Description
type string optional A comma separated list of types to filter the results to. To list all collections that are of the series or movie type: ?type=series,movie. HTTP-based arrays are also supported.
product string optional The href of a product.
query string optional The query to search and filter the paginated results.
plan string optional The plan(s) to filter the paginated results. The value can be an array or comma separated string.
sort string optional The sort to order the results. Options are alphabetical, newest, oldest, or latest.
page integer optional, default is 1 The page number of the paginated result.
per_page integer optional, default is 50 The page size of the paginated result.

Update a Collection

Update a Collection

Definition

PUT /collections/:id

Vhx::Collection.update()

vhx.collections.update();

// Not available for client-side requests.

<?php\VHX\Collections::update();

Example Request

$ curl -X PUT "https://api.vhx.tv/collections/1" \
  -H "Content-Type: application/json" \
  -d '{"description": "A new description", "metadata": {"producer": "Christoper Nolan", "director":
"Brad Pitt", "writers": ["Foo Bar", "Bar Foo"], "release_year": 2017, "custom_icon":
"image_url:https://vhx.imgix.net/site/assets/1231.jpg"}, "plans": ["public", "free", "standard"] }' \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

collection = Vhx::Collection.retrieve("https://api.vhx.tv/collections/1").update({
  description: 'A new description',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017
    producer: 'Christoper Nolan',
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg",
  },
  plans: ["public", "free", "standard"]
})

vhx.collections.update("https://api.vhx.tv/collections/1", {
  description: 'A new description',
  metadata: {
    director: 'Brad Pitt',
    writers: ['Foo Bar', 'Bar Foo'],
    release_year: 2017
    producer: 'Christoper Nolan',
    custom_icon: "image_url:https://vhx.imgix.net/site/assets/1231.jpg"
  },
  plans: ["public", "free", "standard"]
}, function(err, collection) {
  // asynchronously called
});

// Not available for client-side requests.

<?php$collection = \VHX\Collections::update("https://api.vhx.tv/collections/1", array(
  'name' => 'A new description',
  'metadata' => array(
    'director' => 'Brad Pitt',
    'writers' => ['Foo Bar', 'Bar Foo'],
    'release_year' => 2017,
    'producer' => 'Christoper Nolan',
    'custom_icon' => 'image_url:https://vhx.imgix.net/site/assets/1231.jpg'
  )
  'plans' => ['public', 'free', 'standard'],
));

Example Response

{
  "_links": {
    "self": {
      "href": "http://api.vhx.tv/collections/1"
    },
    "items": {
      "href": "http://api.vhx.tv/collections/1/items"
    },
    "collection_page": {
      "href": "http://mynetwork.com/collection-name-1"
    }
  },
  "_embedded": {
    "trailer": null
  },
  "id": 1,
  "name": "Collection Name",
  "description": "A new description",
  "slug": "collection-name",
  "thumbnail": {
    "small": "https://cdn.vhx.tv/assets/thumbnails/default-small.png",
    "medium": "https://cdn.vhx.tv/assets/thumbnails/default-medium.png",
    "large": "https://cdn.vhx.tv/assets/thumbnails/default-large.png",
    "source": "https://cdn.vhx.tv/assets/thumbnails/original.jpg"
  },
  "metadata": {
    "director": "Brad Pitt",
    "producer": "Christoper Nolan",
    "writers": ["Foo Bar", "Bar Foo"],
    "release_year": 2017,
    "custom_icon": {
      "small": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=135&w=240",
      "medium": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=360&w=640",
      "large": "https://vhx.imgix.net/site/assets/1231.jpg?fit=clip&h=720&w=1280",
      "source": "https://vhx.imgix.net/site/assets/1231.jpg"
    },
  },
  "plans": ["public", "free", "standard"],
  "type": "series",
  "seasons_count": 0,
  "items_count": 0,
  "files_count": 0,
  "created_at": "2015-11-25T01:30:33Z",
  "updated_at": "2015-11-25T01:30:33Z"
}

No fields are required when updating a collection, however; you cannot update a collection’s type once it has already been created.

Arguments Description
name string optional The name of the collection.
description optional The collection description.
thumbnail_url optional A publicly accessible image URL. If you prefer you can upload images directly to a collection in the VHX Publisher Admin.
metadata optional object A set of key/value pairs that you can attach to a collection object. It can be useful for storing additional information about the collection in a structured format.

Metadata keys must be strings. There are a few reserved keys that are auto-generated, which cannot be updated. For collections, the following key is reserved: season_number

Metadata values can be strings, integers, arrays, or images. An image metadata value must must be a url of an image, hosted on vhx, prefixed with the text image_url:.
plans array of strings An array of plan types that you can use to set collection availability. Values can be one or more of the following strings: public, free, standard.

The public plan makes the collection object available without email registration or paid subscription.

The free plan makes the collection object available for free, but requires user email registration

The standard plan makes the collection object available to paying subscribers.

List all Items

List all Items

Definition

GET /collections/:id/items

Vhx::Collection.items()

vhx.collections.items();

vhxjs.collections.items();

<?php \VHX\Collections::items();

Example Request

$ curl -X GET -G "https://api.vhx.tv/collections/1/items?page=1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

collection = Vhx::Collection.retrieve("https://api.vhx.tv/collections/1")
collection.items({ page: 1 })

vhx.collections.items({
  collection: 'https://api.vhx.tv/collections/1',
  page: 1
}, function(err, items) {
  // asynchronously called
});

vhxjs.collections.items({
  collection: 'https://api.vhx.tv/collections/1',
  page: 1
}, function(err, items) {
  // asynchronously called
});

<?php$collections = \VHX\Collections::items(array(
  'collection' => 'https://api.vhx.tv/collections/1'
  'page' => 1
));

Example Response

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/collections/1/items?page=1" },
    "first": { "href": "https://api.vhx.tv/collections/1/items" },
    "prev":  { "href": null },
    "next":  { "href": "https://api.vhx.tv/collections/1/items?page=2" },
    "last":  { "href": "https://api.vhx.tv/collections/1/items?page=5" }
  },
  "count": 100,
  "total": 500,
  "_embedded": {
    "items": []
  }
}

Each collection has many items which can be a video or another collection. A paginated result is returned.

Arguments Description
id integer REQUIRED The id of collection being retrieved.
sort string optional The sort to order the results. Options are newest, oldest, or position.
page integer optional, default is 1 The page number of the paginated result.
per_page integer optional, default is 50 The page size of the paginated result.

Add an Item

Add an Item

Definition

PUT /collections/:id/items

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

/* Not yet available for the PHP client */

Example Request

$ curl -X PUT "https://api.vhx.tv/collections/1/items" \
  -d video_id=2 \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

/* Not yet available for the PHP client */

Example Response

HEAD 204

Adds an item to an existing collection.

Arguments Description
video_id integer Optional The id of a video being added.
collection_id integer Optional The id of a collection being added.

Delete an Item

Delete an Item

Definition

DELETE /collections/:id/items

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

/* Not yet available for the PHP client */

Example Request

$ curl -X DELETE "https://api.vhx.tv/collections/1/items" \
  -d video_id=2 \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

// Not available for client-side requests.

/* Not yet available for the PHP client */

Example Response

HEAD 204

Deletes an item from an existing Collection.

Arguments Description
video_id integer Optional The id of a video being removed.
collection_id integer Optional The id of a collection being removed.

Browse

List all Browse items

List all Browse items

Definition

GET /browse

# Not yet available for the Ruby client.

// Not yet available for the Node client.

vhxjs.browse.all();

<?php\VHX\Browse::all();

Example Request

$ curl -X GET -G "https://api.vhx.tv/browse" \
  -d product="https://api.vhx.tv/products/1" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

# Not yet available for the Ruby client.

// Not yet available for the Node client.

vhxjs.browse.all({
  product: 'https://api.vhx.tv/products/1'
}, function(err, products) {
   // asynchronously called
});

<?php\VHX\Browse::all(array(
  'product' => 'https://api.vhx.tv/products/1'
));

Example Response

{
  "_links": {
    "self": {
      "href": "https://api.vhx.tv/browse?product=https%3A%2F%2Fapi.vhx.tv%2Fproducts%2F1"
    },
    "first": {
      "href": "https://api.vhx.tv/browse?product=https%3A%2F%2Fapi.vhx.tv%2Fproducts%2F1"
    },
    "prev": {
      "href": null
    },
    "next": {
      "href": null
    },
    "last": {
      "href": "https://api.vhx.tv/browse?product=https%3A%2F%2Fapi.vhx.tv%2Fproducts%2F1"
    }
  },
  "count": 3,
  "total": 3,
  "_embedded": {
    "items": [
      {
        "_links": {
          "items": {
            "href": "https://api.vhx.tv/collections/1/items?product=https%3A%2F%2Fapi.vhx.tv%2Fproducts%2F1"
          },
          "self": {
            "href": "https://api.vhx.tv/collections/1?product=https%3A%2F%2Fapi.vhx.tv%2Fproducts%2F1"
          },
          "collection_page": {
            "href": "https://subdomain.vhx.tv/collection"
          }
        },
        "name": "Item Name",
        "slug": "Item Slug",
        "items_count": 4,
        "thumbnail": {
          "small": "https://dr56wvhu2c8zo.cloudfront.net/image-small.jpg",
          "medium": "https://dr56wvhu2c8zo.cloudfront.net/image-medium.jpg",
          "large": "https://dr56wvhu2c8zo.cloudfront.net/image-large.jpg",
          "source": "https://dr56wvhu2c8zo.cloudfront.net/image-source.jpg",
          "blurred": "https://dr56wvhu2c8zo.cloudfront.net/image-blurred.jpg",
        }
      }
    ]
  }
}

Retrieves a paginated list of browse items (rows). Each row contains metadata and links to further fetch the items to be displayed. This is meant to be done in an asynchronous manner. A subscription product parameter is required to scope the retrieval.

Arguments Description
product href REQUIRED The query to search and filter the results.
page integer optional, default is 1 The page number of the paginated result.
per_page integer optional, default is 50 The page size of the paginated result.

Authorizations

An authorization grants playback access for a given customer and video.

The response includes an expiring token that is used to authenticate the VHX player on the customers behalf. This enables a customer-to-video playback session which feeds into video analytics.

Create an Authorization

Create an Authorization

Definition

POST /authorizations

Vhx::Authorizaton.create()

vhx.authorizations.create();

// Not available for client-side requests.

<?php\VHX\Authorizations::create();

Example Request

$ curl -X POST "https://api.vhx.tv/authorizations" \
  -d customer=https://api.vhx.tv/customers/1 \
  -d video=https://api.vhx.tv/videos/1 \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

authorization = Vhx::Authorization.create({
  customer: 'https://api.vhx.tv/customers/1',
  video: 'https://api.vhx.tv/videos/1'
})

vhx.authorizations.create({
  customer: 'https://api.vhx.tv/customers/1',
  video: 'https://api.vhx.tv/videos/1'
}, function(err, authorization) {
  // asynchronously called
});

// Not available for client-side requests.

<?php$authorization = \VHX\Authorizations::create(array(
  'customer' => 'https://api.vhx.tv/customers/1',
  'video' => 'https://api.vhx.tv/videos/1'
));

Example Response

{
  "_links": {
    "customer": {
      "href": "https://api.vhx.tv/customers/1"
    },
    "video": {
      "href": "https://api.vhx.tv/videos/1"
    }
  },
  "token": "QVJ-cavyvwSX6JpafMCX7zsd1wKg2XfDuZnN",
  "expires_at": "2015-11-10T23:46:46Z",
  "player": {
    "host": "https://embed.vhx.tv",
    "path": "/videos/1",
    "html": "<iframe src=\"https://embed.vhx.tv/videos/1?authorization=QVJ-cavyvwSX6JpafMCX7zsd1wKg2XfDuZnN\" width=\"640\" height=\"360\" frameborder=\"0\" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>"
  },
  "created_at": "2015-11-10T22:46:46Z",
  "updated_at": "2015-11-10T22:46:46Z"
}

Creates an Authorization for authenticating video playback.

Arguments Description
customer string REQUIRED The href of the customer.
video string REQUIRED The href of the video.

Analytics

Analytics give you access to data around your videos, customers, traffic, and platform income. You can gain insights on what your customers are watching, how many people are visiting your channel, the number of units you are selling, how many customers are subscribing and unsubscribing, and more via reports that can be easily retrieved from the VHX API.

Event Tracking

Event Tracking

Endpoint

https://collector.vhx.tv/events.gif

Javascript Example

  var trackEvent = function() {
    var image  = new Image();
    image.src = 'https://collector.vhx.tv/events.gif?type=video&name=play&property=value';  
  }

  // fire when the event happens
  trackEvent();

  // in the URL property=value will be replaced by all the properties
  // for the particular event (see to your left)
Analytics usage and engagement data stems from specific events that are tracked based on customer activity. These events can be tracked by making a GET request with a series of query parameters (for events properties) to our collector endpoint, shown to the right. The endpoint is a publicly accessible events.gif to work around cross domain issues of making post requests.
Video Playback Events Players across all platforms (web, iOS, Android, Android TV, Roku, Amazon Fire TV, XBox, and Apple TV) should fire and send the below events to the collector. These are based on the HTML5 media events. The event type should be type=video and the event name should be passed in via the name query paramter (e.g. ?type=video&name=firstplay, ?type=video&name=play, ?type=video&name=pause, etc.).
Event Description
firstplay Initial playback has begun. Fired after a manually-triggered play or autoplay. Subsequent pause/play’s should not trigger this. Used to determine total # of streams.
play Playback has started.
pause Playback has been paused.
timeupdate Fired at 10 second intervals of of continuous playback progression. Used to determine total minutes/hours streamed + resume points across devices.
seeked Seek ahead or back has finished.
error Fired after any exception in the player is caught.
waiting Playback has stopped to begin buffering next frames. Helps us understand playback quality / sessions.
ended Playback has stopped due to end of video.
See below for the full list of properties that should be sent as query parameters for triggered video playback events.
Property Description
type string Constant, always set to video for video playback events.
name string Name of event, as outlined in the above table.
seconds integer Value of timeupdate interval. Sent with timeupdate events to determine total time viewed per customer / video. Otherwise 0.
video_id integer ID of current playing video.
user_id integer ID of current viewing user. This property should be pulled from the X-User-Id response header. user_id IS NOT customer_id.
device_id string Unique ID of client device. It should be generated once and persisted as long as possible. Signing out, etc should not regenerate this. Only generate if it doesn’t exist.
session_id string Unique ID of client session. Should be generated every 30 mins of inactivity. “Inactivity” is when no events have been sent in the past 30 minutes.
user_agent string Full, qualified user agent of client.
url string If a web client, current URL where video is being played.
referrer string If a web client, referring URL.
platform string Can be one of the following: iphone, ipad, appletv, roku, android, android_tv, amazon_fire_tv, web, xbox_one
platform_id string Current platform ID. Ties back to a particular channel.
platform_version string Build version of particular platform.
device string iphone, ipad, appletv, roku, android, android_tv, amazon_fire_tv, html5, flash, xbox_one
current_src string Full source URL of current playing video file.
current_type string MIME type of current playing video file. Likely: video/mp4, application/x-mpegURL, or application/dash+xml.
current_subtitle string Label of current selected subtitle. “English” or “Spanish, for example. If no current subtitle, this can be null or omitted.
timecode integer Current video playback time (in seconds). Used for resuming.
duration integer Full duration (in seconds) of current playing video.
is_drm boolean Playback has DRM enabled.
is_fullscreen boolean Playback is currently in fullscreen mode.
is_trailer boolean Playback is a video that is a trailer.
is_chromecast boolean Playback is currently casting via Google Chromecast.
is_airplay boolean Playback is currently casting via Apple Airplay.
Platform Events Platforms (web, iOS, Android, Android TV, Roku, Amazon Fire TV, XBox, and Apple TV) should fire events around usage and key engagement events. The event name should be passed in via the name query paramter (e.g. ?type=platform&name=install, ?type=platform&name=view, ?type=platform&name=conversion, etc.).
Event Description
install A platform (app) has been installed. Triggered once, if possible to capture this event.
view Any load of a page, screen, or deferred partial.
conversion Captures the change of a non-paying -> paying customer.
authentication Captures the change of a logged out -> logged in customer.
See below for the full list of properties that should be sent as query parameters for triggered platform usage events.
Property Description
type string Constant, always set to platform for platform usage events.
name string Name of event, as outlined in the above table.
user_id integer ID of current logged in user. This property should be pulled from the X-User-Id response header. user_id IS NOT customer_id.
device_id string Unique ID of client device. It should be generated once and persisted as long as possible. Signing out, etc should not regenerate this. Only generate if it doesn’t exist.
session_id string Unique ID of client session. Should be generated every 30 mins of inactivity. "Inactivity” is when no events have been sent in the past 30 minutes.
user_agent string Full, qualified user agent of client.
url string If a web client, current URL where event is being sent from.
referrer string Referring web URL or mobile deep link.
campaign string String to represent a campaign, targeted effort, or push notification. Opening the app via a push notification, use this property and set it to notification.
platform string iphone, ipad, appletv, roku, android, android_tv, amazon_fire_tv, web, xbox_one
platform_id string Current platform ID. Ties back to a particular channel.
platform_version string Build version of particular platform. Should use the following format: v1.0.0
view string Name of currently active view: home, login, checkout, settings, browse, search, collection, video, embed, comments, advertisement.
product_id integer Current product context, if present.
collection_id integer Current collection context, if present.
video_id integer Current video context, if present.

Retrieve a Report

There are several different types of analytics reports that you can request. These types are outlined below.

Retrieve a Report

Definition

GET /analytics

# Currently not available in the Ruby client.

vhx.analytics.report();

// Not available for client-side requests.

\VHX\Analytics::report();

Example Report Request 

# Currently not available in the Ruby client.


// Not available for client-side requests.

Example Response

Type Definition
traffic Web traffic to your VHX site across various devices and browsers. This report is for web traffic only. It includes mobile browsers but does not include Branded App activity.
income_statement Income statements are a summary of your revenue and expenses for payout periods. Income statements are generated in monthly intervals for your account.
units Units are the amount of TVOD (transactional video on demand) products you have sold or have been redeemed (gifts or coupons) per given period of time. Units represent products that have been bought or rented.
subscribers Subscribers are the number of customers that are subscribed to your SVOD (subscription on demand) product per given period of time.
churn Churn gives you data around how many customers have unsubscribed (either pausing or cancelling their subscription) per given time period and their reasons (if provided) for doing so.
video Video reports give you insights on how many plays and finishes can be attributed to customers. Sub-reports include retrieving data by platform (video.platforms), country (video.geography) or by subtitles (video.subtitles).
Arguments See below for required and optional arguments to pass to your report requests.
Arguments Description
type string REQUIRED Can be any of the report types described in the above table. This includes: traffic, income_statement, units, subscribers, churn, video, video.platforms, video.geography or video.subtitles.
by string optional, defaults is null Presence of the by parameter implies a request for a Time Series report. If no by parameter is supplied an Aggregate Report will be returned. Acceptable values include hour, day, week, month or year.
from string optional, default is your
account’s creation date (EST) 		The start date or time of the dataset. See below for date formats.
to string optional, default is
the current time (EST) 		The end date or time of the dataset. See below for date formats.
video_id integer optional, unless report is video The video ID is required for any video report type. For other report types it should be omitted.
per_page integer optional, default is 50 The page size of the paginated result.
Date Formatting See below for acceptable date formats for use with the to and from parameters.
Format Definition
YYYY-MM-DD e.g. 2015-12-31, where the time defaults to midnight EST on that date.
YYYY-MM-DDTHH:MM:SSZ e.g. 2016-09-29T18:46:19Z, where the timezone defaults to EST.
[number]-[interval]-ago number can be any number between 1 and 10. interval can be any of the following: day, week, month, year. Examples include 1-day-ago, 3-weeks-ago, 2-months-ago, etc.
cURL Ruby Node PHP Javascript