Vimeo OTT Developers

Menu
API

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="http://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="http://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": "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,
  "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": "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,
  "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.