Videos

The Videos API lets you retrieve and filter video content based on metadata, entitlements, watch history, and search parameters. Built for performance and flexibility, it supports dynamic filtering so you can efficiently access videos that match specific criteria. Whether you’re building personalized experiences or optimizing content discovery, this API makes it easy to pull in the right videos for your application.

Use this API when you need:

Real-time video filtering and search
Dynamic filtering based on user input
Complex filtering combinations
Up-to-the-minute video availability

Authentication Type

Use the read-only endpoint authentication.

Endpoint

GET https://external.parone.io/v2/videos/

Request Parameters

Parameter	Type	Description
`contentKey`	string (optional)	Information about a single `content-key`
`feedId`	string (optional)	Filter videos by a specific feed. If no feed is listed, videos are searched (subject to networkVideos).
`mmi`	string (optional)	Filter videos by MMI.
`networkVideos`	boolean (optional)	If networkVideos is 1 all videos available to the organization will be searched. If set to 0 only your videos will be searched. Default to 0
`watchedByTput`	string (optional)	Filter videos by a specific user `tput` who watched them.
`searchString`	string (optional)	Filter videos by a search string matching titles, descriptions, or `content-keys`.
`categories`	array of strings (optional)	Filter videos by categories.
`customFields`	array of strings (optional)	Filter videos by custom field entries.
`events`	array of strings (optional)	Filter videos by events.
`tags`	array of strings (optional)	Filter videos by tags.
`page`	integer (optional)	The page number for pagination. Defaults to 1
`pageSize`	integer (optional)	The number of videos to return per page. Defaults to 100

Special Characters in Parameters

You can search for videos that have all or some of the text, categories, tags, events, and custom fields you specify.

searchString, events, tags, and categories all use the following syntax to filter videos.

Character	Operation	Description
`,`	AND	Returns videos that match ALL specified values
`\|`	OR	Returns videos that match ANY of the specified values

Examples

# Find videos with a category of "Mexico 2025" and "playoff"
categories=Mexico#202025,playoff

# Find videos with a category of "Mexico 2025" or "playoff"
categories=Mexico#202025|playoff

# Find videos with tags (beginner or instructional) 
# and categories (advanced and technique)
tags=beginner|instructional&categories=advanced,technique"

# Finds videos with the words "LPGA," "Ko," and "highlights" 
# in the title, description, or contentKey.
searchString=LPGA,Ko,highlights

`contentKey`

type: string

The contentKey parameter allows you to return information about a single video.

# Example: get information for content-key 1237868712379

curl "https://external.parone.io/v2/videos?contentKey=1237868712379"

`feedId`

type: string

The feedId parameter allows you to find videos in a specific feed. If no feedId is provided, all available videos across all feeds will be searched, depending on the networkVideos parameter. This makes it easy to query videos belonging to a particular feed for targeted delivery.

# Example: Fetch videos from a specific feed

curl "https://external.parone.io/v2/videos?feedId=your-feed-id"

`mmi` Requires MMI

type: string

Use the mmi parameter to filter videos by a specific MMI (Media Management Identifier). This can be helpful when you need to isolate videos related to a certain sub-organization.

# Example: Fetch videos associated with a specific Media Management Identifier

curl "https://external.parone.io/v2/videos?mmi=your-mmi"

`networkVideos` Requires Network Videos

type: boolean

The networkVideos parameter determines whether or not to find videos from other organizations. By setting this to true, you’ll retrieve network-related videos; false limits results to just your organization’s videos.

# Example: Fetch videos including network syndicated content

curl "https://external.parone.io/v2/videos?networkVideos=1"

`watchedByTput` Requires TPUT

type: string

The watchedByTput parameter allows you to filter videos based on the specific user tput who has watched them. This is useful for retrieving videos that are relevant to a particular user’s viewing history, enabling personalized content delivery.

# Example: Fetch videos including network syndicated content

curl "https://external.parone.io/v2/videos?watchedByTput=your-user-tput"

`searchString`

type: string

The searchString parameter filters videos by matching titles, descriptions, or content keys. This allows users to search for videos that contain specific keywords or phrases, improving the efficiency of content discovery. It is particularly useful for finding relevant videos quickly without needing to know exact metadata..

# Example: Search for videos containing specific text

curl "https://external.parone.io/v2/videos?searchString=bryson"

`categories`

type: array of strings

The categories parameter allows you to filter videos by specific categories assigned to them. By providing an array of strings, you can narrow down the video selection to those matching the specified categories. This is helpful when you need to organize videos based on custom groupings.

# Example: Fetch videos that belong to the 'golf' category

curl "https://external.parone.io/v2/videos?categories=golf"

`customFields` Requires Custom Fields

type: array of strings

You can filter videos based on custom fields using the customFields parameter. This allows you to specify a list of custom field entries that should match the video metadata. It provides flexibility for filtering content according to non-standard attributes set by your video library.

Custom fields use the ‘!’ as the OR parameter

Character	Operation	Description
`!`	AND	Returns videos that match ALL of the specified values
`\|`	OR	Returns videos that match ANY of the specified values

# Find videos that have custom field "instructor" with values "harmon" or "pelz"
customFields=[{instructor:harmon|pelz}]

# Find videos that have custom field "instructor" with values "butch" and "harmon"
customFields=[{instructor:butch!harmon}]

`events` Requires Events

type: array of strings

The events parameter filters videos by specific events that are associated with them. By passing an array of event names or IDs, you can ensure that only videos tied to particular events are returned. This is useful for event-driven content filtering, such as tournaments or promotional events.

# Example: Fetch videos associated with specific events

curl "https://external.parone.io/v2/videos?events=event1,event2"

`tags`

type: array of strings

The tags parameter enables filtering of videos based on custom tags assigned to them. By passing an array of tags, you can narrow down the search to videos that have the specified tags, making it easier to categorize and retrieve videos based on specific keywords or themes.

# Example: Fetch videos with specific tags

curl "https://external.parone.io/v2/videos?tags=tag1,tag2"

`page`

type: integer

The page parameter allows you to specify which page of results you want to retrieve when paginating through a large set of videos. This is useful for breaking down large sets of data into manageable chunks, ensuring your application can load and display results without overwhelming the user interface.

# Example: Fetch the first page of video results

curl "https://external.parone.io/v2/videos?page=1"

`pageSize`

type: integer

The pageSize parameter sets the number of videos returned per page. By adjusting this value, you control the pagination size, which helps optimize performance and user experience when displaying video results. This parameter allows you to fine-tune the number of items shown in each batch of API responses.

# Example: Fetch 10 videos per page

curl "https://external.parone.io/v2/videos?page=1&pageSize=10"

Success Response

This call will return a JSON object that has a list of videos for your organization.

{
  "count": 2,
  "message": "200",
  "page" : 1,
  "pageSize" : 100,
  "data": [
    {
      "contentKey": "AbC123xYz",
      "createdDate": "2025-04-25T14:32:10.000Z",
      "publishedDate": "2025-04-26T08:00:00.000Z",
      "title": "Top 5 Drills to Improve Your Golf Swing",
      "description": "Learn quick drills from pro golfers to improve your consistency and distance on the course.",
      "duration": 180,
      "paroneCategories": ["Instruction", "Training"],
      "categories": ["Golf Tips", "Swing Drills"],
      "tags": ["beginner", "distance", "accuracy"],
      "events": ["Spring Training Series 2025"],
      "customFields": [
        { "difficulty": "beginner" },
        { "clubUsed": "driver" }
      ],
      "isLive": false,
      "thumbnail": "https://thumbnails.parone.io/AbC123xYz.jpg",
      "url": "https://cdn.parone.io/videos/AbC123xYz-1080p.mp4",
      "urlHLS": "https://cdn.parone.io/videos/AbC123xYz/master.m3u8"
    },
    {
      "contentKey": "XyZ789wVu",
      "createdDate": "2025-04-20T10:12:45.000Z",
      "publishedDate": "2025-04-22T07:00:00.000Z",
      "title": "Highlights: 2025 LIV Miami Invitational",
      "description": "Catch the best shots and biggest moments from the 2025 LIV Miami Invitational.",
      "duration": 420,
      "paroneCategories": ["Highlights"],
      "categories": ["Tournament Recap"],
      "tags": ["LIV", "Miami", "highlights"],
      "events": ["LIV Miami Invitational 2025"],
      "customFields": [
        { "eventType": "tournament" },
        { "featurePlayer": "Brooks Koepka" }
      ],
      "isLive": false,
      "thumbnail": "https://thumbnails.parone.io/XyZ789wVu.jpg",
      "url": "https://cdn.parone.io/videos/XyZ789wVu-1080p.mp4",
      "urlHLS": "https://cdn.parone.io/videos/XyZ789wVu/master.m3u8"
    }
  ]
}

Structure of the Returned Results

Field	Value
`count`	The total number of videos matching the query.
`page`	The page number of results
`pageSize`	The page size used to paginate.
`contentKey`	A unique identifier assigned to each video.
`createdDate`	The date and time when the video was first created in the system.
`publishedDate`	The date and time when the video was published and made available to users.
`title`	The official title of the video.
`description`	A brief summary or overview of the video’s content.
`duration`	The total runtime of the video in seconds.
`paroneCategories`	The syndicated categories assigned to the video within the ParOne system.
`categories`	Keywords or labels that help describe and categorize the video.
`tags`	Keywords or labels that the video has tagged
`events`	Any relevant events associated with the video, such as tournaments or special broadcasts.
`customFields`	A collection of additional metadata fields that may vary based on the organization’s needs.
`isLive`	Indicates whether the video is a live stream (`true`) or a pre-recorded video (`false`).
`thumbnail`	The URL of the video’s thumbnail image. See Image Optimization
`url`	The direct URL to download the video file.
`urlHLS`	The HLS (HTTP Live Streaming) URL for adaptive streaming playback.

Videos

Authentication Type

Endpoint

Request Parameters

Special Characters in Parameters

Examples

contentKey

feedId

mmi Requires MMI

networkVideos Requires Network Videos

watchedByTput Requires TPUT

searchString

categories

customFields Requires Custom Fields

events Requires Events

tags

page

pageSize

Success Response

Structure of the Returned Results

`contentKey`

`feedId`

`mmi` Requires MMI

`networkVideos` Requires Network Videos

`watchedByTput` Requires TPUT

`searchString`

`categories`

`customFields` Requires Custom Fields

`events` Requires Events

`tags`

`page`

`pageSize`