ParentTV DAM API (1.2.0)

Download OpenAPI specification:Download

Base URL: https://dam.parenttv.com

Assets from the ParentTV DAM include videos, images and other documents.

To serve an asset's source file, see the stream link in <asset>._links.stream.

Some asset types (video and image) have embed code attached (see <asset>.embed).

Additional data about the asset includes:

  • Tags (keywords/phrases relevant to the asset)
  • Topics (broad categories the asset belongs to)
  • Groups (non-contextual groupings of assets)

Access to assets is mediated by your license key. This means you won't need to renew tokens, as your license key itself will be checked on each request. If your license key is expired or otherwise invalid, requests to the DAM will be rejected with HTTP Status Code 401 - Unauthorized.

If you need to renew or replace your license, please contact apiteam@parenttv.com

assets

Assets are records containing all relevant data about an item of media (video, image, document, etc). An example of an asset might look like this:

{
  "asset_type": "video",
  "contributors": [{ ... }],
  "description": "A long form, probably HTML, description of the asset",
  "excerpts": { ... },
  "groups": { ... },
  "language": { ... },
  "_meta": { 
    "duration": "25"
  },
  "name": "The name of the asset",
  "ref": "A unique identifier for the asset",
  "tags": { ... },
  "topics": { ... },
  "variants": { ... },
  "embed": "A precoded iframe with the streaming src",
  "_links": {
    "self": "/assets/:licenseKey/:assetRef",
    "stream": "/stream/:streamKey/:assetRef"
  }
}

(see the example responses for more complete examples) The most common use of the asset record is to retrieve the stream link in order to present the asset to end users.

In the example above, you'll find those elements with { ... } will have reference links (e.g. groups._links) which provide URLs to get related items (assets, contributors, groups, etc) which share the same categorisation. See the response examples below for a more detailed demonstration.

List assets.

Assets in this listing will include details about tags, groups and topics.

To access the file itself, see the stream link in data[n]._links.stream. The stream links should be used the same way you would use any file uri. So for images, for example, you would set the src attribute of an img tag to the value in data[n]._links.stream.

Assets may be filtered using the query parameters provided. Note that these are cumulative filters, so that (for example) the query string ?types[]=video&langs[]=en&tags[]=biting will only match English language videos tagged "biting"

path Parameters
licenseKey
required
string
query Parameters
per_page
integer
Default: 20

How many items to return

page
integer
Default: 1

Which page of items to return

id
Array of strings

Select only these assets.

groups
Array of strings

Include only assets which are in these groups.

not_groups
Array of strings

Exclude assets which are in these groups.

langs
Array of strings

Include only assets which have these language (ISO codes) [en|es|hi|ar|zh-cn|zh-hk].

not_langs
Array of strings

Exclude assets which have these languages (ISO codes) en|es|hi|ar|zh-cn|zh-hk].

tags
Array of strings

Include only assets which have these tags.

not_tags
Array of strings

Exclude assets which have these tags.

topics
Array of strings

Include only assets which are in these topics.

not_topics
Array of strings

Exclude assets which are in these topics.

types
Array of strings

Filter by asset type [video|image|document].

Responses

Response samples

Content type
application/json
{
  • "_metadata": {
    },
  • "data": [
    ]
}

Retrieve a single asset

Asset data includes details about tags, groups and topics.

To access the file itself, see the stream link in _links.stream. The stream links should be used the same way you would use any file uri. So for images, for example, you would set the src attribute of an img tag to the value in _links.stream.

path Parameters
licenseKey
required
string
ref
required
string

Responses

Response samples

Content type
application/json
{
  • "asset_type": "video",
  • "contributors": [
    ],
  • "description": "We now understand that outcomes for children are not just determined by their genes, but also by the environment they interact with in the first thousand days of their life. The experiences of this period help their brains work out what capabilities it will need.",
  • "excerpts": {
    },
  • "groups": {
    },
  • "language": {