Content Discovery

The Content Discovery API allows clients to discover and retrieve information about the content that has been published to end-users. This guide provides information on the different endpoints and functionalities offered by the API.

API reference: Vimond Content Discovery API (Scalar, from OpenAPI). Compact index for agents: /openapi/content-discovery.llms.md.

Endpoints

The Content Discovery API exposes the following endpoints to retrieve specific types of metadata:

Document	Path	Description
Asset	/api/v1/assets	Represents video asset metadata
Category	/api/v1/categories	Represents content category metadata
Curated lists	/api/v1/lists	Represents fully extended curated list metadata
EPG	/api/v1/epg	Represents live channels and epg metadata

Note: Additional APIs may be introduced in the future to serve specific content types such as TV series or sport events.

All of these documents can be served via direct look up, or via a search query.

The service caches responses by default: 1 minute for direct lookups and 2 minutes for search queries. Those values can be configured per customer with the help of a Vimond support agent.

📘 You can check if a response has been served from the cache or not by checking the response header X-Cache. Also the Cache-Control response header indicates the configured caching time in seconds

Lookup

You can use direct lookup to retrieve a specific document if you know its identifier

Asset lookup

To fetch an asset document with a specific ID, use the following command:

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/v1/assets/73833 \
  -H 'Accept-Language: en_US'

The response will include detailed information about the asset, including its ID, title, timestamp, creation time, category, access information, duration, asset type, description, and images. The metadata fields are computed based on the specified locale.

{
  "data": [
    {
      "id": "73833",
      "title": "That's A Lot!! Pork Bowl Rice [Egg Yolk & Garlic POWER]+ Soup!! 6,4Kg 14357kcal",
      "timestamp": "2018-03-05T08:32:58Z",
      "createTime": "2018-03-05T08:32:45Z",
      "category": {
        "id": "27351",
        "path": "999 27351"
        "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/27351"
      },
      "labeledAsFree": false,
      "drmProtected": false,
      "duration": 243.533,
      "assetType": "clip",
      "description": "Meet the famous Japanese eater Yuka",

      // Metadata are computed based on the locale,
      // then added to the response
      "sport": "food",
      "episode": 1,

      "images": {
        "defaultUrl": "https://image-service.vimond.io/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597",
        "version": "original",
        "templates": {
          "regions": ["austalia", "new-zealand"],
          "locations": [
            "carousel-item",
            "poster"
          ],
          "withRegion": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?region=${REGION}",
          "withLocation": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?location=${LOCATION}",
          "complete": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?region=${REGION}&location=${LOCATION}"
        }
      }
    }
  ]
}

📘 Images

Note that the image will always follow this template. This way the client simply has to follow a URL to fetch the image.

The access level of a particular asset will be reflected in the response of asset lookup. The response will contain a field called accessInfo based on access type. If the asset type of an asset is paid (default) then the field will not be visible otherwise the response will contain the field. Clients should get the following value of the field based on the access type of an asset.

Access Type of an asset is free without login

{
  "data": [
    {
      "id": "73833",
      "title": "That's A Lot!! Pork Bowl Rice [Egg Yolk & Garlic POWER]+ Soup!! 6,4Kg 14357kcal",
      "timestamp": "2018-03-05T08:32:58Z",
      "createTime": "2018-03-05T08:32:45Z",
      "category": {
        "id": "27351",
        "path": "999 27351"
        "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/27351"
      },
      "labeledAsFree": true,
      "drmProtected": false,
      "duration": 243.533,
      "assetType": "clip",
      "description": "Meet the famous Japanese eater Yuka",

      // Metadata are computed based on the locale,
      // then added to the response
      "sport": "food",
      "episode": 1,

      "images": {
        "defaultUrl": "https://image-service.vimond.io/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597",
        "version": "original",
        "templates": {
          "regions": ["austalia", "new-zealand"],
          "locations": [
            "carousel-item",
            "poster"
          ],
          "withRegion": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?region=${REGION}",
          "withLocation": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?location=${LOCATION}",
          "complete": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?region=${REGION}&location=${LOCATION}"
        }
      },
      "accessInfo": {
        "accessType": "FREE_NOLOGIN"
      }
    }
  ]
}

Access Type of an asset is free with login

{
  "data": [
    {
      "id": "73833",
      "title": "That's A Lot!! Pork Bowl Rice [Egg Yolk & Garlic POWER]+ Soup!! 6,4Kg 14357kcal",
      "timestamp": "2018-03-05T08:32:58Z",
      "createTime": "2018-03-05T08:32:45Z",
      "category": {
        "id": "27351",
        "path": "999 27351"
        "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/27351"
      },
      "labeledAsFree": true,
      "drmProtected": false,
      "duration": 243.533,
      "assetType": "clip",
      "description": "Meet the famous Japanese eater Yuka",

      // Metadata are computed based on the locale,
      // then added to the response
      "sport": "food",
      "episode": 1,

      "images": {
        "defaultUrl": "https://image-service.vimond.io/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597",
        "version": "original",
        "templates": {
          "regions": ["austalia", "new-zealand"],
          "locations": [
            "carousel-item",
            "poster"
          ],
          "withRegion": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?region=${REGION}",
          "withLocation": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?location=${LOCATION}",
          "complete": "https://image-service.{domain}/api/v2/img/5aa29e5ee4b08cd076197355-1520897431597?region=${REGION}&location=${LOCATION}"
        }
      },
      "accessInfo": {
        "accessType": "FREE_LOGIN"
      }
    }
  ]
}

📘 Images

Note that, there is no relation between asset level access and content package level access.

Category lookup

To retrieve information about a specific category, you can use the category lookup endpoint

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/{categoryId}

The response will include basic category information such as ID, timestamp, category type, title, parent ID, and path. Additionally, the response will include metadata specific to the category, computed based on the locale.

{
    "data": [
        {
            // The response contains basic category information
            "id": "98",
            "timestamp": "2018-04-03T12:40:03Z",
            "categoryType": "SPORT",
            "title": "[NBA] National Barbecue Association",
            "parentId": 18,
            "path": "1 18 98",
            "children": [],

            // Plus all the category's metadata based on the locale
            "season-id": 2018,
            "round-number": 28,
            "sport": "barbecue"
        }
    ]
}

To retrieve information about the parent and children categories as well, you can use the depth query parameter. For example:

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/{categoryId}?depth=1

The response will include the requested category information along with information about its parent and children categories, up to the specified depth.

{
    "data": [
        {
            // The response contains basic category information
            "id": "98",
            "timestamp": "2018-04-03T12:40:03Z",
            "categoryType": "SPORT",
            "title": "[NBA] National Barbecue Association",

            // Information about the parent and children
            "parentId": 18,
            "path": "1 18 98",
            "children": [
                {
                    // The response contains basic category information
                    "id": "2464",
                    "timestamp": "2018-04-03T12:40:03Z",
                    "categoryType": "SPORT",
                    "title": "[NBA] National Barbecue Association",
                    "parentId": 98,
                    "path": "1 18 98 2464",

                    // This children field will be populated if depth=2
                    "children": [],

                    // Plus all the category's metadata based on the locale
                    "season-id": 2018,
                    "round-number": 28,
                    "sport": "barbecue"
                }
            ],

            // Plus all the category's metadata based on the locale
            "season-id": 2018,
            "round-number": 28,
            "sport": "barbecue"
        }
    ]
}

Curated list lookup

To look up a curated list by its ID or alias, you can use the list lookup endpoint. The default depth level is 2, but you can specify the depth using the depth query parameter.

To look up a list by ID:

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/v1/lists/{listId}

To look up a list by alias:

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/v1/lists/{listAlias}

The response will include information about the list, including its ID, content type, create time, update time, paths, timestamp, parent ID, and elements. The elements field contains information about the list’s child elements, such as assets, categories, or other lists. The response will also include metadata specific to each element based on the locale.

Example response

{
    "data": [
        {
            "id": "lXyip28UT4",
            "contentType": "contentpanel",
            "createTime": "2020-09-03T04:27:56Z",
            "updateTime": "2020-09-03T04:28:06Z",
            "paths": [
                {
                    "path": "/editorial_root/lXyip28UT4",
                    "parents": [
                        "editorial_root"
                    ],
                    "level": 1
                }
            ],
            "timestamp": "2020-10-23T08:17:26Z",
            "parentId": "editorial_root",
            "elements": [
                {
                    "id": "tlL3pCXEcA",
                    "contentType": "contentpanel",
                    "createTime": "2020-09-03T04:28:01Z",
                    "updateTime": "2020-09-03T04:28:06Z",
                    "paths": [
                        {
                            "path": "/editorial_root/lXyip28UT4/tlL3pCXEcA",
                            "parents": [
                                "editorial_root",
                                "lXyip28UT4"
                            ],
                            "level": 2
                        }
                    ],
                    "timestamp": "2020-10-23T08:17:26Z",
                    "parentId": "lXyip28UT4",
                    "elements": [
                        {
                            "id": "209458",
                            "contentType": "asset",
                            "createTime": "2020-09-03T04:28:01Z",
                            "updateTime": "2020-09-03T04:28:01Z",
                            "paths": [
                                {
                                    "path": "/editorial_root/lXyip28UT4/tlL3pCXEcA/209458",
                                    "parents": [
                                        "editorial_root",
                                        "lXyip28UT4",
                                        "tlL3pCXEcA"
                                    ],
                                    "level": 3
                                }
                            ],
                            "content": {
                                "id": "209458",
                                "timestamp": "2020-11-02T14:06:42Z",
                                "createTime": "2020-09-03T04:27:54Z",
                                "category": {
                                    "path": "999 133101 158428",
                                    "link": "https://vimond.content-discovery.cf.eu-north-1-dev.vmnd.tv/api/v1/categories/158428",
                                    "id": "158428"
                                },
                                "labeledAsFree": false,
                                "drmProtected": false,
                                "duration": 0.0,
                                "assetType": "Trailer",
                                "isLive": false,
                                "transmissionTime": "2018-08-10T14:18:31Z",
                                "relatedAssets": [],
                                "qualities": [
                                    "4k",
                                    "hd"
                                ],
                                "markers": [],
                                "version": {
                                    "available": [
                                        "main"
                                    ],
                                    "type": "main"
                                },
                                "publishing": {
                                    "platform": "platforms"
                                },
                                "description": "Which is the smarter? The crow? or the Magpie? Let's find out.",
                                "title": "Crows vs Magpies"
                            },
                            "timestamp": "2020-10-23T08:17:27Z",
                            "parentId": "tlL3pCXEcA",
                            "title": "Crows vs Magpies"
                        }
                    ],
                    "title": "Crows vs Magpies collection"
                },
                {
                    "id": "158428",
                    "contentType": "category",
                    "createTime": "2020-09-03T04:27:56Z",
                    "updateTime": "2020-09-03T04:28:06Z",
                    "paths": [
                        {
                            "path": "/editorial_root/lXyip28UT4/158428",
                            "parents": [
                                "editorial_root",
                                "lXyip28UT4"
                            ],
                            "level": 2
                        }
                    ],
                    "content": {
                        "id": "158428",
                        "timestamp": "2020-10-23T08:21:07Z",
                        "categoryType": "CATEGORY",
                        "parentId": "133101",
                        "path": "999 133101 158428",
                        "children": [],
                        "publishing": {
                            "platform": "web"
                        },
                        "title": "Crow content"
                    },
                    "timestamp": "2020-10-23T08:17:26Z",
                    "parentId": "lXyip28UT4",
                    "title": "The crow category"
                },
                {
                    "id": "209458",
                    "contentType": "asset",
                    "createTime": "2020-09-03T04:27:56Z",
                    "updateTime": "2020-09-03T04:28:06Z",
                    "paths": [
                        {
                            "path": "/editorial_root/lXyip28UT4/209458",
                            "parents": [
                                "editorial_root",
                                "lXyip28UT4"
                            ],
                            "level": 2
                        }
                    ],
                    "content": {
                        "id": "209458",
                        "timestamp": "2020-11-02T14:06:42Z",
                        "createTime": "2020-09-03T04:27:54Z",
                        "category": {
                            "path": "999 133101 158428",
                            "link": "https://vimond.content-discovery.cf.eu-north-1-dev.vmnd.tv/api/v1/categories/158428",
                            "id": "158428"
                        },
                        "labeledAsFree": false,
                        "drmProtected": false,
                        "duration": 0.0,
                        "assetType": "Trailer",
                        "isLive": false,
                        "transmissionTime": "2018-08-10T14:18:31Z",
                        "relatedAssets": [],
                        "qualities": [
                            "4k",
                            "hd"
                        ],
                        "markers": [],
                        "version": {
                            "available": [
                                "main"
                            ],
                            "type": "main"
                        },
                        "publishing": {
                            "platform": "platforms"
                        },
                        "description": "An exciting look into the daily life of crows.",
                        "title": "As the crow flies"
                    },
                    "timestamp": "2020-10-23T08:17:26Z",
                    "parentId": "lXyip28UT4",
                    "title": "As the crow flies"
                }
            ],
            "title": "More about crows"
        }
    ]
}

EPG

You can retrieve all live channels metadata as well as the EPG programs belonging to a specific channel.

EPG channels

Use the following endpoint to fetch all channel documents:

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/api/v1/epg/channels \
  -H 'Accept-Language: en_US'

The response will include detailed information about all the channels, including their ID, title, timestamp, creation time, category, access information, asset type, description, and images. The metadata fields are computed according to the requested locale.

Example response

{
  "data": [
    {
      "id": "1022278",
      "timestamp": "2025-07-23T12:43:49Z",
      "createTime": "2025-07-22T13:04:09Z",
      "updateTime": "2025-07-22T13:04:11Z",
      "locales": [
        "en_US"
      ],
      "category": {
        "path": "0 999 367732 411693",
        "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/411693",
        "id": "411693"
      },
      "labeledAsFree": false,
      "drmProtected": false,
      "duration": 0,
      "assetType": "liveChannelProgram",
      "isLive": true,
      "isParent": true,
      "aspect16x9": true,
      "transmissionTime": "2025-07-22T13:04:09Z",
      "relatedAssets": [],
      "qualities": [],
      "startTime": 0,
      "endTime": 0,
      "version": {
        "available": [
          "main"
        ],
        "type": "main"
      },
      "publishing": {
        "start": "2025-07-22T13:04:11Z",
        "end": "2050-11-25T15:00:00Z",
        "platform": "web",
        "geoExpressions": [
          "any"
        ]
      },
      "products": [
        {
          "id": "2",
          "name": "Free with login",
          "accessType": "FREE_LOGIN"
        },
        {
          "id": "7293",
          "name": "test update by query",
          "accessType": "PAID"
        }
      ],
      "publisher-id": 18981,
      "channelNumber": 1,
      "via-live-channel-id": "5708c28b-7a9a-4686-b797-29803f0a4801",
      "title": "integrationTest_Linear_2025-07-22T13:04:09.460Z"
    }
  ],
  "meta": {
    "numberOfHits": 1,
    "totalPages": 1,
    "pageSize": 1
  },
  "links": {
    "self": "https://{tenant}.content-discovery.cf.{domain}/api/v1/epg/channels",
    "first": "https://{tenant}.content-discovery.cf.{domain}/api/v1/epg/channels",
    "last": "https://{tenant}.content-discovery.cf.{domain}/api/v1/epg/channels"
  }
}

EPG programs

Use the following endpoint to fetch all EPG programs of a live channel for a specified date:

curl -X GET \
  https://{tenant}.content-discovery.cf.{domain}/api/api/v1/epg/channels/{channelId}/programs?date=2025-07-23 \
  -H 'Accept-Language: en_US'

The response will include minimal information about all the programs, including their ID, title, channelId, startDateTimeUTC, endDateTimeUTC, images and link to get detailed information. The metadata fields are computed according to the requested locale.

By default, the response includes EPG programs for the current date, but the request can be adjusted with the date parameter for retrieving data for another date. By default, the max interval is ± 7 days from the current date.

In addition, it is possible to specify a timezone offset to use when filtering EPG programs. All timestamps data are store in UTC so the client can indicate its timezone with the offset parameter (±XX:XX, ex. +10:00) to avoid requesting the wrong data slice. When omitted, the service uses the UTC offset.

Example response

{
  "data": [
    {
      "id": "7f0ae256e1ed4bd498160666ffef444b",
      "timestamp": "2025-07-24T17:52:00Z",
      "channelId": "eac3f322-57e8-494f-a5d9-8f88a50aa16c",
      "startDateTimeUTC": "2025-07-23T16:51:00Z",
      "endDateTimeUTC": "2025-07-23T18:51:00Z",
      "epg": {
        "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/assets/1022588",
        "id": "1022588"
      },
      "title": "past-epg-integrationTest-EPGProgram-Azrin"
    }
  ],
  "meta": {
    "numberOfHits": 1,
    "totalPages": 1,
    "pageSize": 1
  },
  "links": {
    "self": "https://{tenant}.content-discovery.cf.{domain}/api/v1/epg/channels/eac3f322-57e8-494f-a5d9-8f88a50aa16c/programs?date=2025-07-23",
    "first": "https://{tenant}.content-discovery.cf.{domain}/api/v1/epg/channels/eac3f322-57e8-494f-a5d9-8f88a50aa16c/programs?date=2025-07-23",
    "last": "https://{tenant}.content-discovery.cf.{domain}/api/v1/epg/channels/eac3f322-57e8-494f-a5d9-8f88a50aa16c/programs?date=2025-07-23"
  }
}

Filtering Fields in the Response

To reduce the size of the response and retrieve only specific fields, you can use the fields query parameter. Specify the fields you want to retrieve as a comma-separated list.

For example, to retrieve only the ID and title fields of assets, and the ID, category type, and title fields of categories:

curl -X GET \
  'https://{tenant}.content-discovery.cf.{domain}/api/v1/lists/editorial_root?fields=id&fields[asset]=id,title&fields[category]=id,categoryType,title'

The response will only include the requested fields for each document type. Note that some fields will always be present in the response, even if they are not explicitly requested.

Caching

The Content Discovery API caches responses by default, with a cache time of 1 minute for direct lookups and 2 minutes for search queries. The cache time can be configured per customer in collaboration with the Vimond support team.

You can check if a response has been served from the cache or not by checking the response header X-Cache. The Cache-Control response header indicates the configured caching time in seconds.

Conclusion

The Content Discovery API provides powerful capabilities for discovering and retrieving content metadata. By utilizing the provided endpoints and functionalities, developers can easily integrate and leverage the content information available in their applications.