Getting started with VIA APIs

This section provides an overview of the essential concepts and practices for working with VIA APIs.

If you need VIA product documentation for the CMS and back-office workflows (screens and tasks in the web app), see the VIA user guide. This hub focuses on APIs and integration; the introduction explains how the two fit together.

Endpoint links below open the matching Scalar operation in the API reference (Vimond REST API, Image Service, Content Discovery, or Play Service). Viewer-facing services without a dedicated spec yet link to their guide pages.

General

Gain insight into key terminology, concepts, and frequently asked questions related to VIA APIs.

• Terminology and Concepts
• Frequently Asked Questions
• REST API: Best Practices
• A Note on XML and JSON Formats

Authentication

Learn about the different authentication methods for both machine-to-machine and end-user interactions.

• Guide: Machine-to-Machine API Authentication
• Guide: End-User Authentication

Configuration/onboarding

Discover how to manage regions, region platforms, publishers, metadata definitions, and image configuration.

Manage Regions

A region defines a specific geographic area for content distribution and access control within the VIA API ecosystem.

• Guide: Multi-Region publishing and Geo-blocking
• GET /admin/regions - All regions
• PUT /admin/regions/{region} - Create or update Region
• DELETE /admin/regions/{region} - Delete Region

Manage Region Platforms

A region platform defines platforms like “Web,” “Mobile App,” or “Smart TV” within a region, enabling tailored content distribution and control through VIA APIs.

• GET /admin/regions/{region}/platforms - Get Region Platforms
• PUT /admin/regions/{region}/platforms/{platform} - Create or update Region Platform
• DELETE /admin/regions/{region}/platforms/{platform} - Delete Region Platform

Manage Metadata definitions

Metadata definitions define the structure and attributes of content metadata, enabling standardized categorization and organization.

• Guide: Content Metadata
• GET /api/metadata/definitions - Get all metadata definitions
• GET /api/metadata/definition/{field} - Get a fields metadata definition
• PUT /api/metadata/definition/{field} - Update or create a fields metadata definition

Manage Image Configuration

Image configuration facilitates the management of image settings, ensuring optimal display and presentation of asset artwork on every device.

• Guide: Image service
• PUT /adminAPI/imageLocationConfigs - Save Image Location Configs
• GET /adminAPI/imageLocationConfigs
• GET /adminAPI/imageLocationConfigs/{field}
• PUT /adminAPI/imageLocationConfigs/{field}
• PUT /adminAPI/imageLocationConfigs/{field}/label
• POST /adminAPI/regions
• PUT /adminAPI/regions/{region}

Manage Editorial User Accounts

This section covers the management of publishers, editorial users, roles, and permissions.

Manage Publishers

A publisher represents an entity that produces and distributes content, managing content offerings and interactions via VIA APIs.

• GET /api/companies/ - All publishers
• POST /api/companies/ - Create publisher
• GET /api/companies/{publisherId} - Get Publisher
• PUT /api/companies/{publisherId} - Update Publisher
• DELETE /api/companies/{publisherId} - Delete Publisher

Manage Editorial Users

An editorial user in the context of VIA is an authorized individual responsible for creating, curating, and managing content within the platform.

• GET /cms/api/user/me
• GET /cms/api/userinfo/extended
• GET /cms/api/settings/accounts/currentuser
• GET /cms/api/settings/accounts/users
• POST /api/settings/accounts/users
• PATCH /cms/api/settings/accounts/users
• DELETE /cms/api/settings/accounts/users
• POST /cms/api/settings/accounts/password

Manage Roles

A role in the context of VIA refers to a predefined set of permissions and responsibilities assigned to users, determining their access and actions within the platform; examples include “Admin,” “Editor, “Publisher”, and “Customer Service.”

• GET /cms/api/settings/accounts/roles
• PATCH /cms/api/settings/accounts/user/{userId}/roles

Manage content

Explore how to ingest assets with video, images, and metadata, manage categories, assets, and more.

Ingest Assets with Video, Images and Metadata

• Guide: Feed Ingest
• Guide: Content Metadata

Manage Categories

• POST /api/{platform}/category/ - Create category
• GET /api/{platform}/category/{categoryId} - Get category
• PUT /api/{platform}/category/{categoryId} - Update category
• DELETE /api/{platform}/category/{categoryId} - Delete category
• GET: /api/{platform}/category/{categoryId}/categories - Get Sub-Categories

Manage Assets

• Guide: Asset Relations and Multiple Camera Angles
• Guide: Asset Types: Organize Content Efficiently
• POST /api/{platform}/asset - Create asset
• GET /api/{platform}/asset/{assetId} - Get Asset
• PUT /api/{platform}/asset/{assetId} - Update asset
• DELETE /api/{platform}/asset/{assetId} - Delete asset
• GET /api/{platform}/category/{categoryId}/assets - Get Assets in a category
• GET /api/{platform}/asset/types - Get Asset types

Add Images to Categories and Assets

• Guide: Content Images
• Guide: Image service
• GET /api/v2/imageLocationConfigs - Get all image locations
• GET /api/v2/img/{imagePackId} - Get image
• POST /adminAPI/imagePacks - Create image pack
• GET /adminAPI/imagePacks - Get all image pack IDs
• GET /adminAPI/imagePack/{id}
• PUT /adminAPI/imagePack/{id}
• POST /adminAPI/imagePack/{id}/{imageLocationName}/upload
• POST /adminAPI/imagePack/{id}/{imageLocationName}/fetchImage
• POST /adminAPI/imagePack/{id}/uploadImageFromUrl
• POST /adminAPI/imagePack/{id}uploadFile
• POST /adminAPI/imagePack/{id}/upload

Manage Metadata

Metadata in the context of VIA refers to descriptive information attached to content, aiding in categorization and search; examples include titles, descriptions, and tags.

• Guide: Content Metadata
• GET /api/metadata/asset/{assetId} - Get asset metadata
• GET /api/metadata/category/{categoryId} - Get category metadata
• POST /api/metadata/asset/{assetId} - Set asset metadata
• DELETE /api/metadata/asset/{assetId} - Delete asset metadata
• DELETE /api/metadata/asset/{assetId}/{field} - Delete asset metadata field
• DELETE /api/metadata/asset/{assetId}/{field}/{language} - Delete asset metadata field in language
• DELETE /api/metadata/category/asset/language/{assetId} - Delete all asset metadata in language
• POST /api/metadata/category/{categoryId} - Set category metadata
• DELETE /api/metadata/category/{categoryId} - Delete category metadata
• DELETE /api/metadata/category/{categoryId}/{field} - Delete category metadata field
• DELETE /api/metadata/category/{categoryId}/{field}/{language} - Delete category metadata field in language

Metadata Lookup

• GET /api/metadata/lookup/assets/{field} - Find assets with metadata
• GET /api/admin/metadata/asset/autocomplete - Autocomplete asset metadata
• GET /api/metadata/lookup/categories/{field} - Find categories with metadata
• GET /api/admin/metadata/category/autocomplete - Autocomplete category metadata

Manage Timeline Markers

Timeline markers in VIA are metadata points that provide specific temporal references within an asset, aiding navigation and enhancing content engagement. For instance, timeline markers could mark key scenes, interviews, ads, or events within a video asset.

• POST /api/{platform}/asset/{assetId}/items
• GET /api/{platform}/asset/{assetId}/items - Get Asset Items
• GET /api/{platform}/asset/{assetId}/item/{itemId} - Get Asset Item
• PUT /api/{platform}/asset/{assetId}/item/{itemId}
• DELETE /api/{platform}/asset/{assetId}/item/{itemId}

Manage subtitles

Subtitles in the context of VIA are textual translations displayed on-screen that provide a translated version of the spoken dialogue in a video. For example, displaying English subtitles for a French-language video allows non-French-speaking viewers to understand the content.

• POST /api/asset/{assetId}/subtitle - Create or update subtitle for asset
• GET /api/{platform}/asset/{assetId}/subtitles - Get subtitles for asset
• GET /api/{platform}/asset/{assetId}/subtitle/{subtitleId} - Get Subtitle for asset
• DELETE /api/asset/{assetId}/subtitle/{id} - Delete subtitle for asset

Manage Category Publish Windows

Category Publish Windows in VIA refers to scheduled periods during which specific categories of content become available or unavailable for users, aiding content management and viewer access control. For instance, a streaming service might use Category Publish Windows to release a collection of new movies on a particular date, ensuring synchronized content availability.

• PUT /api/vcc/{levelType}/{categoryId}/publish-unpublish-updated - Setting category publishing status and scheduled dates

Manage Asset Publish and License Windows

Asset Publish and License Windows in VIA refer to scheduled dates for making content available and managing licensing rights. For instance, an asset might be published on web platforms on a specific date while being accessible on mobile platforms a week later, ensuring tailored release strategies.

• GET v/api/{platform}/asset/{assetId}/publish - Get asset publishing info
• PUT /api/{platform}/asset/{assetId}/publish/ALL - Publish asset
• PUT /api/{platform}/asset/{assetId}/unpublish/ALL - Unpublish asset
• PUT /api/{platform}/asset/{assetId}/publishinfo - Setting scheduled asset publishing and license dates

Manage Ingest Feeds

Feed Ingest in the context of VIA refers to the process of importing external content, including videos, images, and metadata, into the platform for management and distribution.

• Guide: Feed Ingest
• GET /cms/api/batch-import/feeds - Fetch all feeds
• POST /cms/api/batch-import/feeds - Create feed
• PUT /cms/api/batch-import/company/{companyId}/feeds/{feedId} - Update feed
• DELETE /cms/api/batch-import/company/{companyId}/feeds/{feedId} - Delete feed
• POST /cms/api/batch-import/feed/{feedId} - Ingest content
• PUT /cms/api/batch-import/job/{jobId}/abort - Abort import job
• PUT /cms/api/batch-import/job/{jobId}/retry - Retry import job
• PUT /cms/api/batch-import/task/{taskId}/abort
• PUT /cms/api/batch-import/task/{taskId}/retry - Retry import task
• GET /cms/api/batch-import/company/{companyId}/feeds/{feedId} - Fetch feed status
• GET cms/api/batch-import/company/{companyId}/feeds/{feedId}/jobs - Fetch import jobs for a feed
• GET /cms/api/batch-import/company/{companyId}/feeds/{feedId}/jobs/{jobId}/tasks - Fetch import tasks for a import job

Consuming content

Delve into content discovery, play service APIs, player session service and APIs, and playlist service and APIs.

Content Discovery

Content Discovery in the context of VIA refers to the process of helping users find relevant and engaging content within the platform through various search and recommendation mechanisms.

• Guide: Content Discovery
• Categories
  • GET /api/v1/categories - Perform a full-text search to retrieve categories
  • GET /api/v1/categories/{categoryId} - Retrieve an category by its id
• Assets
  • GET /api/v1/assets - Perform a full-text search to retrieve assets
  • GET /api/v1/assets/{assetId} - Retrieve an asset by its id
• Lists
  • GET /api/v1/lists - Search list
  • GET /api/v1/lists/{alias} - Search list by alias

Play service APIs

In the context of VIA, the Play Service refers to the API and functionality that enables users to access and play video content seamlessly.

• Guide: Video Playback
• Guide: Play service API
• POST /api/v2/asset/{assetId}/play - Get play urls for an asset

Player Session Service and APIs

Player Session Service in the context of VIA is a functionality that tracks and manages user interactions during video playback sessions for analytical and operational purposes.

• Guide: Video Playback
• Guide: Player session API
• POST /api/v1/external/player-events/{playCorrelationId} - Write a player events to the message bus and poll for possible kick events

Playlist Service and APIs

Playlist Service in the context of VIA refers to the feature that enables users to create, manage, and organize collections of assets for seamless playback and content consumption.

• Guide: Playlist Service
• Guide: Playlist API
• GET /api/v1/playlists - Get playlists
• POST /api/v1/playlists - Create playlist
• DELETE /api/v1/playlists - Delete playlists
• GET /api/v1/playlists/{playlistId} - Get playlist by id
• PUT /api/v1/playlists/{playlistId} - Update playlist
• DELETE /api/v1/playlists/{playlistId}- Delete playlist
• POST /api/v1/playlists/{playlistId}/assets/{assetId} - Add asset to playlist
• DELETE /api/v1/playlists/{playlistId}/assets/{assetId} - Remove asset from playlist

Subprofile Service and APIs

The Subprofile Service in the context of VIA refers to the functionality that allows users to create and manage personalized sub-profiles within their accounts, tailoring their viewing experiences.

• Guide: Subprofile Service
• Guide: Subprofile API
• GET /api/v1/subprofiles/{id} - Get one sub profile for logged in user
• PUT /api/v1/subprofiles/{id} - Update a sub profile for logged in user
• DELETE /api/v1/subprofiles/{id} - Delete a sub profile for logged in user
• GET /api/v1/subprofiles - Get all sub profiles for logged in user
• POST /api/v1/subprofiles - Create a new sub profile for logged in user
• DELETE /api/v1/subprofiles - Delete all subprofiles for logged in user
• GET api/v1/subprofiles/{id}/token - Get token for specified sub profile of the logged in user

User Viewing History and APIs

The User Viewing History Service in VIA tracks and manages a user’s content consumption history, providing insights into their watched content and progress.

• Guide: User Viewing History Service
• DELETE /api/v1/viewinghistory - Delete all viewing history for logged in user and sub profile
• GET /api/v1/viewinghistory/all - Retrieve all viewing history for the logged user
• GET /api/v1/viewinghistory/all/{categoryId} - Retrieve all viewing history for the logged user for the requested category
• GET /api/v1/viewinghistory/completed - Retrieve completed viewing history for the logged user
• GET /api/v1/viewinghistory/completed/{categoryId} - Retrieve completed viewing history for the logged user for the requested category
• GET /api/v1/viewinghistory/progress - Retrieve progress viewing history for the logged user
• GET /api/v1/viewinghistory/progress/{categoryId} - Retrieve progress viewing history for the logged user for the requested category
• GET /api/v1/viewinghistory/{assetId} - Retrieve all viewing history for the logged user for the requested asset
• DELETE /api/v1/viewinghistory/{assetId} - Delete viewing history for asset for logged in user and sub profile

Device Registration and APIs

Device Registration in the context of VIA refers to the process of authenticating and registering devices for access to content, allowing control over user access and content protection. For instance, a user might be limited to streaming a movie on only two devices simultaneously to prevent unauthorized sharing.

• Guide: Device Registration
• GET /api/v1/usages - Get complete usage report for logged in user
• GET /api/v1/usages/{ruleSetName} - Get usage report for given ruleset for logged in user
• POST /api/v1/usages/{ruleSetName} - Check device and register if necessary
• PUT /api/v1/usages/{ruleSetName} - Check device without registering it
• GET /api/v1/usages/{ruleSetName}/{udid} - Retrieve device information
• PUT /api/v1/usages/{ruleSetName}/{udid} - Update device information
• DELETE /api/v1/usages/{ruleSetName}/{udid} - Delete device

Monetize content

Get insights into various monetization strategies, including SVOD, AVOD, TVOD, and payment methods.

• Guide: SVOD: Subscription-based Video on Demand
• Guide: AVOD: Advertising-based Video on Demand
• Guide: TVOD: Transactional-based Video on Demand
• Guide: Payment

Protecting content

Discover methods to protect your content, such as multi-region publishing, geo-blocking, and device registration.

• Guide: Multi-Region publishing and Geo-blocking
• Guide: Stream Count
• Guide: Device Registration

VIA Data APIs

Learn about VIA Data Event Stream and VIA Data Exports for accessing and managing data.

• Guide: VIA Data Event Stream
• Guide: VIA Data Exports