API Reference - Vimeo OTT Developers

Introduction

API Endpoint

https://api.vhx.tv

The Vimeo OTT API (previously referenced as “VHX API”) provides a simple and secure REST interface to Vimeo OTT. Registered applications can manage products, customers, videos, collections, authorizations, and analytics.

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! Please submit any questions here.

Authentication

API Key

API Key

Example Request

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

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 keys can be created on the Platforms page of your Vimeo OTT CMS.

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.

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 Vimeo OTT 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.

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
422	Unprocessable Entity
429	Too Many Requests (rate limit violation)
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

Definition

GET /products/:id

Example Request

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

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

Definition

GET /products

Example Request

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

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.
active boolean optional	Set to `true` to only returns products that are actively available to customers.
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.

List Prices for a Product

List prices for a product

Definition

GET /products/:id/prices

Example Request

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

Example Response

{
  "USD": {
    "monthly": {
      "price": 2999,
      "formatted": "$29.99"
    },
    "yearly": {
      "price": 20000,
      "formatted": "$200"
    }
  },
  "SEK": {
    "monthly": {
      "id": 205697,
      "price": 25103,
      "formatted": "251.03 kr"
    },
    "yearly": {
      "id": 46604,
      "price": 957764,
      "formatted": "9,577.64 kr"
    }
  }
}

Lists the prices for a product in all accepted currencies.

Prices for subscription products will include yearly and monthly attributes for each currency. Prices for non-subscription products will have purchase and rental attributes instead.

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

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:

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.

This endpoint enforces a rate limit of 5 requests per second.

Arguments	Description
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.
expires_in string optional	This parameter is used for letting our system know when a user should lose access. This can not be updated so we do not recommend using this for managing renewals as it could lead to service interruptions for your customers. Valid formats are a number followed by a unit of time. For example, `3-months`, `1-years`, `5-weeks`, `7-days`.
is_rental integer optional	Set this to `1` to indicate this customer only has rental access to this product. Pass in an `expires_in` param to set an expiration time as well.
name string optional	The customer’s full name (first and last).
password string optional	This must be at least eight characters long. Omitting this field will prompt the customer to set their password the next time they sign in.
plan string optional, default is “standard”	The customer’s plan determines content accessibility. Values can be one of the following strings: `free`, `standard`. This should be set depending on your product type. Use `free` if you are using subscription that is free with registration. In any other case, you should use `standard`.
send_email integer optional	Set this to `1` if you would like our system to send the customer an email notifying them that they now have access to the product.

Retrieve a Customer

Retrieve a customer

Definition

GET /customers/:id

Example Request

$ curl -X GET "https://api.vhx.tv/customers/1" \
  -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": {},
  "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",
  "platform": "web"
}

the _embedded object contains a browse_url that can be used to authenticate a customer session.

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.

List all Customers

List all customers

Definition

GET /customers

Example Request

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

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. By default filters for customers with status of `enabled` (subscribed). The status query param should be explicitly set in order to include customers that are not `enabled`. See status below.
sort string optional	The sort to order the results. Options are `newest`, `oldest`, or `latest`.
status string optional	The status indicates the subscription status of the customer. Options are `enabled`, `disabled`, `cancelled`, `refunded`, `expired`, `paused`, or `all` (includes all statuses).
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

Example Request

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

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).
password string optional	This must be at least eight characters long.

Add a Product

Add a product

Definition

PUT /customers/:id/products

Example Request

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

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.
plan string optional, default is “standard”	The customer’s plan determines content accessibility. Values can be one of the following strings: `free`, `standard`. This should be set depending on your product type. Use `free` if you are using subscription that is free with registration. In any other case, you should use `standard`.
is_rental integer optional	Set this to `1` to indicate this customer only has rental access to this product.

Remove a Product

Remove a product

Definition

DELETE /customers/:id/products

Example Request

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

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.
plan string optional, default is “standard”	This is only needed if a customer has both `standard` and `free` access. Pass in whichever you would like to remove first. If you want to remove both, do one before the other.

Retrieve Watching Items

Retrieve Watching Items

Definition

GET /customers/:id/watching

Example Request

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

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.

Arguments	Description
href string REQUIRED	The `href` of the customer being retrieved must be passed in via the `VHX-Customer` header.

Retrieve Watchlist Items

Retrieve Watchlist Items

Definition

GET /customers/:id/watchlist

Example Request

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

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.

Arguments	Description
customer string REQUIRED	The `href` of the customer.
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.
show_all string optional	Set to `true` if you want collections returned in the results.
source_id integer optional	The ID of any collection or video if you want to return only that item specifically.

Add Item to Watchlist

Add Item to Watchlist

Definition

PUT /customers/:id/watchlist

Example Request

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

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

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

Example Request

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

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

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.

Create a Video

Create a Video

Definition

POST /videos

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":"https://s3.amazonaws.com/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:

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.
thumbnail_url optional string, default is null	A publicly accessible image URL. If you prefer, you can upload images directly to a video in the Vimeo OTT Publisher Admin.
description optional string, default is null	A description for the video.
short_description optional string, default is null	A shorter description for the video.
url optional string, default is video title	The final part of the url of the video, ie the `video_title` in https://yoursite.com/video_title.
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.
canonical_collection optional id, default is null	The canonical collection is the one collection that a video should be associated with above others even if it has been added to multiple collections. The best example of this is an episode of a TV show that perhaps gets added to a smaller selection of videos as a playlist. To add a canonical collection, pass in a pair with a key of `id` and a value of the collection ID of the collection that should be this to the video.
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`
geo_available optional string, default is null	Comma seperated list of country codes for the countries this collection should be available in.
geo_unavailable optional string, default is null	Comma seperated list of country codes for the countries this collection should not be available in.
is_commenting_enabled optional boolean	Determines if comments are allowed on the video. This value will be ignored if comments are disabled at the site level.
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, prefixed with the text `image_url:`.

Retrieve a Video

Retrieve a Video

Definition

GET /videos/:id

Example Request

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

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

Definition

GET /videos

Example Request

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

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

Definition

GET /videos/:id/files

Example Request

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

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

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:

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. While you can use this endpoint to provide a source_url for a video that does not have one yet, updating an existing one is not supported at this time.

Arguments	Description
title string optional	A title for the video.
description string optional	A description for the video.
short_description optional string, default is null	A shorter description for the video.
thumbnail_url optional string, default is null	A publicly accessible image URL. If you prefer, you can upload images directly to a video in the Vimeo OTT Publisher Admin.
url optional string, default is video title	The final part of the url of the video, ie the `video_title` in https://yoursite.com/video_title.
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.
canonical_collection optional id, default is null	The canonical collection is the one collection that a video should be associated with above others even if it has been added to multiple collections. The best example of this is an episode of a TV show that perhaps gets added to a smaller selection of videos as a playlist. To add a canonical collection, pass in a pair with a key of `id` and a value of the collection ID of the collection that should be this to the video.
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`
geo_available optional string, default is null	Comma seperated list of country codes for the countries this collection should be available in.
geo_unavailable optional string, default is null	Comma seperated list of country codes for the countries this collection should not be available in.
is_commenting_enabled optional boolean	Determines if comments are allowed on the video. This value will be ignored if comments are disabled at the site level.
tags optional string	Tags that you want associated in the system with the video. Use comma’s to separate multiple tags you would like associated with the video.
genres optional string	The genres that should be associated with this video. Use comma’s to separate multiple genres you would like associated with the video. Accepted values include: `action`, `adventure`, `animation`, `anime`, `biography`, `bollywood`, `classics`, `comedy`, `crime`, `documentary`, `drama`, `educational`, `fantasy`, `game_show`, `history`, `holiday`, `horror`, `independent`, `kids_and_family`, `lgbt`, `music`, `musical`, `mystery`, `news`, `novelas`, `reality`, `romance`, `sci_fi`, `short_films`, `special_interest`, `sports`, `talk_show`, `teens`, `thriller`, `travel`, `war`, `western.`
casts array of key value pairs	Use this to store information about the cast of the video. Each element of the array requires two keys: `actor` and `character` with a cooresponding value for each.
crew array of key value pairs	Use this to store information about the crew of the video. Each element of the array requires two keys: `name` and `role`. Accepted role values include: `actor`, `director`, `writer`, `producer`, `creator`, `voice`, `narrator`, `guest`, `host`, `anchor`, `music`, `executive_producer`, `executive_in_charge`, `head_writer`, `editor`, `other`.
release_dates array of key value pairs	Use this to store information about the release dates of the video. Each element of the array requires two keys: `date` and `location`. The date value must be formatted as `YYYY-MM-DD`. The location value should be a two letter country code. If a location value is not provided, the date will be considered the release date everywhere.
ratings array of key value pairs	Use this to store information about the ratings of the video. Each element of the array requires two keys: `rating` and `location`. Accepted rating values include: `G`, `PG`, `PG-13`, `R`, `NC-17`, `U`, `UR`, `12A`, `12`, `15`, `18`, `R18`, `TV-Y`, `TV-Y7`, `TV-G`, `TV-PG`, `TV-14`, `TV-MA`. The location value should be a two letter country code. If a location value is not provided, the rating will be considered the rating everywhere.
advisories array of key value pairs	Use this to store information about the advisories of the video. Each element of the array requires two keys: `advisory` and `location`. Accepted advisory values include: `D` for suggestive dialogue, `L` for coarse language, `S` for sexual content, `V` for violence, or `FV` for fantasy violence. The location value should be a two letter country code. If a location value is not provided, the advisory will be considered the advisory everywhere.
license optional string	Used to exprese whether the video is `licensed` or `original` content.
media_id optional string	An internal identifier for the video in our system.
media_type optional string	Classify the type of content for the video. Accepted values include: `movie`, `episode`, `live_sporting_event`, or `other`.
movie_type optional string	Classify the type of movie for a video that has a `media_type` of `movie`. Accepted values include: `feature`, `short_film`, or `tv_movie`.
movie_version optional string	Classify the version of movie for a video that has a `media_type` of `movie`. Accepted values include: `standard`, `unrated`, `rated`, `uncut`, `directors_cut`, `extended`, `remastered`, `special_edition`, `alternate_ending`, `alternate_cut`, `editing_for_tv`.
production_studios array of key value pairs	Use this to store information about the production studio that produced the video. Each element of the array requires two keys: `name` and `country`. The country value should be a two letter country code. If a country value is not provided, the production studio used everywhere.
sports_type optional string	Adds the sport associated with a video that has a `media_type` of `live_sporting_event`. Accepted values include: `afl`, `australian_football_leage`, `bundesliga`, `cfl`, `epl`, `formula_1`, `ipl`, `la_liga`, `mll`, `minor_league_baseball`, `mlb`, `mls`, `nascar`, `nll`, `national_league`, `national_womens_soccer_league`, `nba`, `ncaa`, `nhl`, `nrl`, `premiere_league`, `super_league`, `uefa`, `wnba`.
episode_number optional integer	The number episode for a video with a `media_type` of `episode`.
production_id optional string	The identifier for the production of a video with a `media_type` of `episode`.
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, prefixed with the text `image_url:`.

Delete a Video

Delete a Video

Definition

DELETE /videos/:id

Example Request

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

Example Response

HEAD 204

This endpoint sends a request to delete a video. This process happens asynchronously in our system so you may not see the video be removed from your account right away. In the event that there is a problem deleting the video, the Vimeo OTT account owner will be notified.

Please note that this is a destructive action and once the request is sent there will be no way to recover the deleted video.

Arguments	Description
href string REQUIRED	The `href` of the video being deleted.

Comments

Create a Comment

Create a Comment

Definition

POST /comments

Example Request

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

Example Response

{
  "_links": {
    "self": { "href": "https://api.vhx.tv/comments/1" },
    "video": { "href": "https://api.vhx.tv/videos/1" }
    },
  "_embedded": {
    "customer": {},
    "comments": [],
    "video": {},
  },
  "id": 1,
  "video_id": 1,
  "content": "Great video!",
  "comments_count": 1,
  "created_at": "2020-04-02T19:40:26Z",
  "updated_at": "2020-04-02T19:40:26Z"
}

A comment can be created and added to a video.

Arguments	Description
video REQUIRED href	The `href` for the video the comment should be added to.
customer REQUIRED href	The `href` of the customer who is creating the comment.
content REQUIRED string	The actual content of the comment being created.
comment optional href	The `href` of a comment that is being replied to. This is optional and can only be done to comments that are not replies themselves.

Retrieve a Comment

Retrieve a Comment

Definition

GET /comments/:id

Example Request

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

Example Response

{
  "_links": {
    "self": { "href": "https://api.vhx.tv/comments/1" },
    "video": { "href": "https://api.vhx.tv/videos/1" }
    },
  "_embedded": {
    "customer": {},
    "comments": [],
    "video": {},
  },
  "id": 1,
  "video_id": 1,
  "content": "Great video!",
  "comments_count": 1,
  "created_at": "2020-04-02T19:40:26Z",
  "updated_at": "2020-04-02T19:40:26Z"
}

Retrieves a single comment

Arguments	Description
comment REQUIRED href	The `href` of the comment being retrieved.

List all Comments

List all Comments

Definition

GET /comments

Example Request

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

Example Response

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

Retrieves all comments for a given video.

Arguments	Description
video REQUIRED href	The `href` of a video.

Report a Comment

Report a Comment

Definition

POST /comments/:id/report

Example Request

$ curl -X POST "https://api.vhx.tv/comments/1/report" \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Example Response

{ 
  "message": "Comment reported! Thank you"
}

By offering commenting on your videos, there is a realistic chance that you will get some spam or unpleasant comments. In that situation, we offer this endpoint to report that comment. You can manage these flagged comments in your Vimeo OTT Publisher Admin.

Arguments	Description
comment REQUIRED href	The `href` of the comment being reported.

Collections

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

Type	Definition
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

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:

Example Response

{
  "_links": {
    "self": {
      "href": "https://api.vhx.tv/collections/1"
    },
    "items": {
      "href": "https://api.vhx.tv/collections/1/items"
    },
    "collection_page": {
      "href": "https://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,
  "is_featured": false,
  "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: `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 Vimeo OTT Publisher Admin.
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.
short_description string optional	The collections short description.
collection_ids array of hrefs optional	Providing an array of collection hrefs to this endpoint will associate those collections with the newly created collection. This is most useful for adding other collections to a `category` being created in the call.
series_id string optional	When creating a `season` type collection, you can include this to indicate the `series` this should be associated with in our system.
season_number integer optional	For `season` type collections only. You can use this to tell our system what season number this should be for the associated `series`.
video_ids array of hrefs optional	Pass in an array that includes any video href that you would like associated with the collection you create.
file_ids array of hrefs optional	Pass in an array that includes any extra href that you would like associated with the collection you create.
is_featured string optional	Set to `true` to make this the featured category for your site. This is only available for `category` type collections.
is_automatic string optional	Set to `true` along with `is_featured` to make your featured carousel auto-scroll through the associated content. This is only available for `category` type collections.
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 be a url of an image, prefixed with the text `image_url:`.

Retrieve a Collection

Retrieve a Collection

Definition

GET /collections/:id

Example Request

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

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,
  "is_featured": false,
  "position": 2,
  "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

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:

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`.
active string optional	Set this to `true` to only return active collections. An active collection is a collection with a plan value that has been set. Set to `false` to only return inactive collections or those without a plan.
plan string optional	Filter to only show collections that are in the plan type specified. Options include `public`, `free`, or `standard`.
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

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:

Example Response

{
  "_links": {
    "self": {
      "href": "https://api.vhx.tv/collections/1"
    },
    "items": {
      "href": "https://api.vhx.tv/collections/1/items"
    },
    "collection_page": {
      "href": "https://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,
  "is_featured": false,
  "position": 2,
  "created_at": "2015-11-25T01:30:33Z",
  "updated_at": "2015-11-25T01:30:33Z"
}

No fields are required when updating a collection. Please note a collection’s type cannot be updated once it has already been created.

Arguments	Description
name string optional	The name of the collection.
description optional	The collection description.
slug string optional	The final part of the url of the collection, ie the `/collection_name` where you want the collection found on your Vimeo OTT site, ie the `collection_name` in https://yoursite.com/collection_name.
thumbnail_url optional	A publicly accessible image URL. If you prefer you can upload images directly to a collection in the Vimeo OTT Publisher Admin.
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.
short_description string optional	The collections short description.
geo_available string optional	Comma seperated list of country codes for the countries this collection should be available in.
geo_unavailable string optional	Comma seperated list of country codes for the countries this collection should not be available in.
tags array of strings optional	Tags that you want associated in the system with the collection. Use comma’s to separate multiple tags you would like associated with the collection.
media_id string optional	An internal identifier for the collection in the system.
season_number integer optional	For `season` type collections only. You can use this to tell our system what season number this should be for the associated `series`.
is_featured string optional	Set to `true` to make this the featured category for your site. This is only available for `category` type collections.
is_automatic string optional	Set to `true` along with `is_featured` to make your featured carousel auto-scroll through the associated content. This is only available for `category` type collections.
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, prefixed with the text `image_url:`.

Update a Collection’s Position

Update a Collection’s Position

Definition

PUT /collections/:id/update_position

Example Request

$ curl -X PUT "https://api.vhx.tv/collections/1/update_position" \
  -H "Content-Type: application/json" \
  -d '{"position": 3}' \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

Example Response

{}

The order of the categories returned from the Browse endpoint is determined by the position value of each category. The position of any collection, including categories, can be changed using this endpoint.

On success, the API will respond with a 200 status code and an empty JSON object.

Arguments	Description
position integer optional	The desired position of the collection. If it is not a valid position value, the API will return a 400 status code.

List all Items

List all Items

Definition

GET /collections/:id/items

Example Request

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

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.
query string optional	The query to search and filter the paginated results based on item name or title.
type string optional	Filter to results to only include items of a certain type. Options include `videos`, `extras`, or `seasons`.
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

Example Request

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

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.
file_id integer Optional	The id of an extra being added.

Update the Position of an Item

Update the Position of an Item

Definition

PUT /collections/:collection_id/items/:item_id

Example Request

$ curl -X PUT "https://api.vhx.tv/collections/1/items/32" \
  -d '{"position": 3}' \
  -u o3g_4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

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,
  "finishes_count": 1204,
  "created_at": "2014-02-25T20:19:30Z",
  "updated_at": "2014-02-25T20:19:30Z",
  "item_id": 32,
  "position": 3
}

Updates the position of an item in a collection. The :item_id refers to the item_id value present in the response from the List all Items endpoint.

The structure of response depends on the type of the item. The example response demonstrates with a video.

Arguments	Description
position integer optional	The desired position of the item in the collection.

Delete an Item

Delete an Item

Definition

DELETE /collections/:id/items

Example Request

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

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.
file_id integer Optional	The id of an extra being added.

Browse

List all Browse items

List all Browse items

Definition

GET /browse

Example Request

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

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",
        },
        "is_featured": false
      }
    ]
  }
}

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 embeddable iframe with an expiring token that is used to authenticate the Vimeo OTT player on the customers behalf. This enables a customer-to-video playback session which feeds into video analytics and can be controlled with the Player API.

Create an Authorization

Create an Authorization

Definition

POST /authorizations

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:

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 Vimeo OTT API.

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

Example Report Request

Example Response

Type	Definition
traffic Aggregate report	Web traffic to your Vimeo OTT 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 Aggregate report	Income statements are a summary of your revenue and expenses for payout periods. Income statements are generated in monthly intervals for your account.
units Both report types	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 Both report types	Subscribers are the number of customers that are subscribed to your SVOD (subscription on demand) product per given period of time.
churn Both report types	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 Both report types	Video reports give you insights on how many plays and finishes can be attributed to customers. The data can be filtered by using the below sub-reports.
video.platforms Aggregate report	Video platform returns play data segmented by platform.
video.geography Both report types	Video geography returns play data segmented by country.
video.subtitles Both report types	Video subtitles returns play data segmented by 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.