Documentation Powered by ReDoc

ParentTV DAM API (1.2.0)

Download OpenAPI specification:Download

E-mail: apiteam@parenttv.com

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": {
    },
  • "_meta": {
    },
  • "name": "Why the first 1000 days of a child's life are so important",
  • "ref": "d0fad5d6-e996-4437-8fb9-5f40bbcfd7cc",
  • "tags": {
    },
  • "topics": {
    },
  • "variants": {
    },
  • "embed": "<iframe src=\"https://player.parenttv.com/:licenseKey/19170bda-008e-11ec-a2e0-0242ac170002\" width=\"1920\" height=\"1080\" frameborder=\"0\" allow=\"autoplay; fullscreen; picture-in-picture\" allowfullscreen title=\"`What exercises can I do?\"/>",
  • "_links": {
    }
}

groups

Groups are a categorisation of assets and include definitions of the packages available for licensing.

The standard group definition looks like this:

{
  "ref": "childcare",
  "description": "childcare",
  "count": 678,
  "_links": {
    "assets": "https://dam.parenttv.com/assets/:licenseKey?groups=childcare",
    "contributors": "https://dam.parenttv.com/contributors/:licenseKey?groups=childcare",
    "languages": "https://dam.parenttv.com/languages/:licenseKey?groups=childcare",
    "self": "https://dam.parenttv.com/groups/:licenseKey/childcare",
    "tags": "https://dam.parenttv.com/tags/:licenseKey?groups=childcare",
    "topics": "https://dam.parenttv.com/topics/:licenseKey?groups=childcare"
  }
}

Where you'll be able to see the number of assets within that group, and a set of reference links for other items which include assets in it.

List groups.

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 groups.

langs
Array of strings

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

not_langs
Array of strings

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

tags
Array of strings

Include only groups with assets which have these tags.

not_tags
Array of strings

Exclude groups with assets which have these tags.

topics
Array of strings

Include only groups with assets which are in these topics.

not_topics
Array of strings

Exclude groups with assets which are in these topics.

Responses

Response samples

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

Retrieve a single group

path Parameters
licenseKey
required
string
ref
required
string

Responses

Response samples

Content type
application/json
{
  • "ref": "string",
  • "description": "string",
  • "count": 0,
  • "_links": {
    }
}

Retrieve a single group

path Parameters
licenseKey
required
string
ref
required
string

Responses

Response samples

Content type
application/json
{
  • "ref": "string",
  • "description": "string",
  • "count": 0,
  • "_links": {
    }
}

tags

Tags are effectively keywords which can be used to find assets

The standard tag definition looks like this:

{
  "ref": "biting",
  "description": "biting",
  "count": 5,
  "_links": {
    "assets": "https://dam.parenttv.com/assets/:licenseKey?tags=development",
    "contributors": "https://dam.parenttv.com/contributors/:licenseKey?tags=development",
    "languages": "https://dam.parenttv.com/languages/:licenseKey?tags=development",
    "self": "https://dam.parenttv.com/tags/:licenseKey/development",
    "topics": "https://dam.parenttv.com/topics/:licenseKey?tags=development",
    "groups": "https://dam.parenttv.com/tags/:licenseKey?tags=development"
  }
}

Where you'll be able to see the number of assets that share a tag, and a set of reference links for other items which include assets having it.

List tags.

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 tags.

groups
Array of strings

Include only tags with assets which are in these groups.

not_groups
Array of strings

Exclude tags with assets which are in these groups.

langs
Array of strings

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

not_langs
Array of strings

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

topics
Array of strings

Include only tags with assets which have these topics.

not_topics
Array of strings

Exclude tags with assets which have these topics.

Responses

Response samples

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

topics

Topics are a more specific categorisation of assets and describe the general idea behind an asset.

The standard topic definition looks like this:

{
  "ref": "development",
  "description": "Development",
  "count": 20,
  "_links": {
    "assets": "https://dam.parenttv.com/assets/:licenseKey?topics=development",
    "contributors": "https://dam.parenttv.com/contributors/:licenseKey?topics=development",
    "languages": "https://dam.parenttv.com/languages/:licenseKey?topics=development",
    "self": "https://dam.parenttv.com/topics/:licenseKey/development",
    "tags": "https://dam.parenttv.com/tags/:licenseKey?topics=development",
    "groups": "https://dam.parenttv.com/topics/:licenseKey?topics=development"
  }
}

Where you'll be able to see the number of assets within that topic, and a set of reference links for other items which include assets in it.

List topics.

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 topics.

groups
Array of strings

Include only topics with assets which are in these groups.

not_groups
Array of strings

Exclude topics with assets which are in these groups.

langs
Array of strings

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

not_langs
Array of strings

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

tags
Array of strings

Include only topics with assets which have these tags.

not_tags
Array of strings

Exclude topics with assets which have these tags.

Responses

Response samples

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

Retrieve a single topics

path Parameters
licenseKey
required
string
ref
required
string

Responses

Response samples

Content type
application/json
{
  • "ref": "string",
  • "description": "string",
  • "count": 0,
  • "_links": {
    }
}