Vidyard's APIs allow development teams to integrate video functionality into applications and workflows. These APIs support tasks such as automating video creation, management, and distribution, as well as tracking viewer analytics.

With flexible endpoints, Vidyard’s APIs enable use cases ranging from embedding personalized videos to gathering detailed engagement data. They are designed for scalability and ease of use, providing the tools needed to build custom video solutions.

Authentication and API Access

Before interacting with Vidyard's API, you need to authenticate. Vidyard uses OAuth 2.0 for secure and token-based access to their services. Developers can obtain an access token by following Vidyard's OAuth flow.

Example: Request an Access Token

code
curl -X POST https://api.vidyard.com/oauth/token 
-H "Content-Type: application/x-www-form-urlencoded" \
-d
"grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
code

You must include the returned access token in the Authorization header for all subsequent API requests:

code
Authorization: Bearer YOUR_ACCESS_TOKEN

Explanation:

  • -X POST sends a POST request to the OAuth token endpoint.
  • -H "Content-Type: application/x-www-form-urlencoded" specifies the content type of the form data.
  • -d contains the client credentials required for token issuance.

Response Example:

code
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}

Common Errors:

  • 401 Unauthorized: Invalid or missing credentials.
  • 400 Bad Request: Malformed request.
  • 403 Forbidden: Insufficient permissions.

Video Management with Vidyard API

Vidyard allows you to manage video content programmatically through its API. This includes uploading, updating metadata, and deleting videos.

Example: Upload a Video

code
curl -X POST https://api.vidyard.com/api/v1/videos \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@path_to_your_video_file.mp4"
code

Response Example:

code
{
"id": "video-12345",
"playback_url": "https://play.vidyard.com/video-12345.html"
}

Update Video Metadata:

code
curl -X PUT https://api.vidyard.com/api/v1/videos/{video_id} \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "New Title", "description": "Updated description"}'
code

Explanation:

  • id: The video ID.
  • playback_url: URL to view or embed the video.

Example: Update Video Metadata

code
curl -X PUT https://api.vidyard.com/api/v1/videos/{video_id} \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{"title": "New Video Title", "description": "Updated description"}'
code

Explanation:

  • -F uploads the video using multipart/form-data.
  • The PUT request with JSON updates the title and description.

Interactive Video Features

Vidyard’s API allows you to incorporate interactive features into your videos. You can programmatically add elements like call-to-action buttons, forms, and links to your videos to enhance user engagement.

Add a CTA Button:

code
curl -X POST https://api.vidyard.com/api/v1/videos/{video_id}/cta \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "link",
"text": "Learn More",
"url": "https://your-website.com",
"start_time": 30
}'

Response Example:

code
{
"cta_id": "cta-67890",
"status": "added"
}

This will show a clickable CTA link at 30 seconds into the video.

Explanation:

  • Type: Defines CTA type (link, form, etc.).
  • Text and URL: Button label and destination.
  • start_time: When the CTA appears during playback.

Analytics and Reporting

Vidyard offers extensive analytics features that can help track viewer engagement, including view counts, user interactions, and video performance. The API allows you to fetch detailed statistics about your videos, such as the number of plays, completion rates, and average watch time.

Get Overall Video Analytics:

code
curl -X GET https://api.vidyard.com/api/v1/videos/{video_id}/analytics \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This will return various metrics, such as the total number of views, watch time, and audience retention for the video.

Sample Response:

code
{
"views": 1583,
"average_watch_time": 45.2,
"completion_rate": 0.62
}

Get Viewer-Level Insights (with Pagination):

code
curl -X GET "https://api.vidyard.com/api/v1/videos/{video_id}/viewers?page=1&per_page=50" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
code

Sample Response:

code
{
"viewers": [
{
"email": "viewer@example.com",
"watch_time": 60,
"interactions": ["cta_clicked"]
}
],
"pagination": {
"current_page": 1,
"total_pages": 5
}
}
code

This will provide a list of viewers and their interaction data, such as the time spent watching the video and engagement with any embedded CTAs.

Explanation:

  • curl -X GET https://api.vidyard.com/api/v1/videos/{video_id}/analytics \: Sends a GET request to retrieve analytics data for a specific video.
  • -H "Authorization: Bearer YOUR_ACCESS_TOKEN": Authenticates the request using the provided bearer token.
  • curl -X GET https://api.vidyard.com/api/v1/videos/{video_id}/viewers \: Sends a GET request to fetch the list of viewers for the specified video.
  • -H "Authorization: Bearer YOUR_ACCESS_TOKEN": Supplies the access token for API authorization.

Video Playback and Embedding

Vidyard also provides APIs to manage video playback options, including embedding videos on external websites. The POST /videos/{video_id}/embed endpoint can be used to generate a video embed code with custom parameters for controlling playback behavior.

Generate an Embed Code:

code
curl -X POST https://api.vidyard.com/api/v1/videos/{video_id}/embed \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"player_size": "large",
"autoplay": true,
"controls": true
}'

Sample Response:

code
{
"embed_code": "<iframe src='https://play.vidyard.com/video-12345.html' width='640' height='360' allowfullscreen></iframe>"
}

This will return a standard iframe embed code, which can be inserted into your website.

Explanation:

  • player_size: Choose from predefined sizes (small, medium, large).
  • Autoplay and Controls: Control playback behavior and UI options.

Custom Video Thumbnails

Vidyard also allows you to set custom thumbnails for your videos via the API. Custom thumbnails are useful for branding purposes or for improving user engagement with a more compelling visual.

Video Thumbnail:

code
curl -X PUT https://api.vidyard.com/api/v1/videos/{video_id}/thumbnail \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"thumbnail_url": "https://your-website.com/thumbnail.jpg"
}'

This will update the video thumbnail to the provided image URL.

Response:

code
{ "status": "updated"}
code

Explanation:

thumbnail_url: Must be a publicly accessible image URL (JPG, PNG, etc.).

Video Security and Privacy

Vidyard allows you to control the privacy of your videos, restricting access to authorized users or specific domains. You can set videos to be private, password-protected, or accessible only to specific referrers.

Set a Video to Private:

code
curl -X PUT https://api.vidyard.com/api/v1/videos/{video_id}/privacy \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"privacy": "private"
}'
code

This will ensure that the video can only be accessed by authenticated users or specified referrers.

Explanation:

  • Purpose: curl is a command-line tool used for making HTTP requests.
  • {video_id}: This is a placeholder for the actual ID of the video you want to update.
  • Bearer YOUR_ACCESS_TOKEN: This is the authorization method where YOUR_ACCESS_TOKEN should be replaced with the actual access token.
  • application/json: Specifies that the data being sent in the body is in JSON format.
  • "privacy": "private": This JSON object specifies that the privacy of the video should be set to "private".