Subscribers, their product access, watchlists, and in-progress viewing.
openapi: 3.0.3
info:
title: Vimeo OTT Analytics Customers API
description: 'The Vimeo OTT API (formerly the VHX API) is a REST interface for managing a branded subscription video / over-the-top (OTT) service. It lets media companies manage customers (subscribers), products (subscription, rental, and purchase access agreements), videos, and collections (categories, series, seasons, movies, playlists), plus watchlists, embeddable-player authorizations, comments, live events, and analytics. All access is over HTTPS; requests and responses are JSON using the HAL hypermedia convention (_links, _embedded). Authentication is HTTP Basic Auth with a Vimeo OTT API key supplied as the username and a blank password; keys are generated on the Platforms page of the Vimeo OTT CMS.
Scope note - HTTP methods and paths are confirmed from the public reference at dev.vhx.tv. Request and response field-level schemas below are modeled from the documented examples and generalized where the reference documents fields by example rather than as a formal schema.'
version: '1.0'
contact:
name: Vimeo OTT Developers
url: https://dev.vhx.tv/docs/api/
servers:
- url: https://api.vhx.tv
description: Vimeo OTT (VHX) API
security:
- basicAuth: []
tags:
- name: Customers
description: Subscribers, their product access, watchlists, and in-progress viewing.
paths:
/customers:
get:
operationId: listCustomers
tags:
- Customers
summary: List customers
description: Lists all customers (subscribers). Paginated, 50 per page by default.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
- name: email
in: query
description: Filter customers by email address.
required: false
schema:
type: string
responses:
'200':
description: A paginated list of customers.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCustomer
tags:
- Customers
summary: Create a customer
description: Creates a new customer. Name, email, and a product reference are required. Rate limited to roughly 5 requests per second.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreate'
responses:
'201':
description: The created customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/customers/{id}:
parameters:
- $ref: '#/components/parameters/id'
get:
operationId: getCustomer
tags:
- Customers
summary: Retrieve a customer
description: Retrieves a single customer by ID.
responses:
'200':
description: The requested customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCustomer
tags:
- Customers
summary: Update a customer
description: Updates a customer's information.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerUpdate'
responses:
'200':
description: The updated customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/customers/{id}/products:
parameters:
- $ref: '#/components/parameters/id'
put:
operationId: addCustomerProduct
tags:
- Customers
summary: Grant product access
description: Grants the customer access to a product.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
product:
type: string
description: The product ID or href to grant access to.
required:
- product
responses:
'200':
description: Product access granted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: removeCustomerProduct
tags:
- Customers
summary: Revoke product access
description: Revokes the customer's access to a product.
parameters:
- name: product
in: query
required: true
description: The product ID or href to revoke.
schema:
type: string
responses:
'204':
description: Product access revoked.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/customers/{id}/watchlist:
parameters:
- $ref: '#/components/parameters/id'
get:
operationId: getCustomerWatchlist
tags:
- Customers
summary: Retrieve a customer's watchlist
description: Retrieves the items a customer has saved to their watchlist.
responses:
'200':
description: The customer's watchlist.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoList'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: addToWatchlist
tags:
- Customers
summary: Add to watchlist
description: Adds a video or collection to the customer's watchlist.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
item:
type: string
description: The video or collection ID or href to add.
required:
- item
responses:
'200':
description: Item added to watchlist.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: removeFromWatchlist
tags:
- Customers
summary: Remove from watchlist
description: Removes an item from the customer's watchlist.
parameters:
- name: item
in: query
required: true
description: The video or collection ID or href to remove.
schema:
type: string
responses:
'204':
description: Item removed from watchlist.
'401':
$ref: '#/components/responses/Unauthorized'
/customers/{id}/watching:
parameters:
- $ref: '#/components/parameters/id'
get:
operationId: getCustomerWatching
tags:
- Customers
summary: Retrieve in-progress videos
description: Retrieves the videos a customer has started but not finished, with playback position.
responses:
'200':
description: The customer's in-progress videos.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoList'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
VideoList:
type: object
properties:
_embedded:
type: object
properties:
videos:
type: array
items:
$ref: '#/components/schemas/Video'
count:
type: integer
total:
type: integer
_links:
$ref: '#/components/schemas/Links'
CustomerUpdate:
type: object
properties:
name:
type: string
email:
type: string
format: email
Customer:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
thumbnail:
type: string
platform:
type: string
location:
type: string
subscription_status:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
_links:
$ref: '#/components/schemas/Links'
Links:
type: object
description: HAL hypermedia links.
additionalProperties: true
Video:
type: object
properties:
id:
type: integer
title:
type: string
description:
type: string
duration:
type: integer
status:
type: string
thumbnail:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
_links:
$ref: '#/components/schemas/Links'
CustomerCreate:
type: object
properties:
name:
type: string
email:
type: string
format: email
product:
type: string
description: The product ID or href the customer is being created against.
password:
type: string
required:
- name
- email
- product
Error:
type: object
properties:
message:
type: string
error:
type: string
CustomerList:
type: object
properties:
_embedded:
type: object
properties:
customers:
type: array
items:
$ref: '#/components/schemas/Customer'
count:
type: integer
total:
type: integer
_links:
$ref: '#/components/schemas/Links'
parameters:
perPage:
name: per_page
in: query
required: false
description: The number of results per page (default 50).
schema:
type: integer
minimum: 1
maximum: 100
default: 50
id:
name: id
in: path
required: true
description: The resource ID.
schema:
type: string
page:
name: page
in: query
required: false
description: The page of results to return.
schema:
type: integer
minimum: 1
default: 1
responses:
BadRequest:
description: The request was malformed or missing required fields.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Auth. Supply your Vimeo OTT API key as the username and leave the password blank.