Media Management API Overview

The Media Management API is a RESTful API for accessing and configuring the components of the domain for an authorized user. The multi-faceted and cascading configuration hierarchy gives the domain owner the ability to set-up domain, application, catalog and mediaitem level settings. An API keyholder has the ability to create, read, update and delete anything from ad configurations to metadata on independent media items. This API provides easy to use methods for fronting UI components in an existing CMS or through a programmatic function.

You will receive your domainId and API Key from your account management team, all other Ids may be retrieved using the API methods below.

API Base URL

All Media Management API methods utilize the following base URL

https://api.unicornmedia.com/media-management-api/domains/{domainId}

API URL Variables

Within this guide, any example URL value in {singleBrackets} must be replaced (without brackets).

Request header

Required HTTP Header

X-BC-ONCE-API-KEY : {yourApiKey}

Error Guide

Error Code Error Cause
400 Bad Request Incorrect or invalid request body
403 Forbidden Missing or incorrect API Key
404 Not Found Incorrect or invalid URL path

Domain Methods

Get Domain details

Retrieves domain name and domainId.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}

Request Body

(none)

Response Body

{
    "id": "1234abcd-1234-abcd-56ef-098765fedcba",
    "name": "ExampleDomain"
}

Response Fields

Field Type Description
id String The domainId
name String The domain name

Get All Domain renditions

Retrieves all Transcoding Renditions available in your domain (note, new videos will be assigned renditions based on the configured Catalog Renditions).

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/renditions

Request Body

(none)

Response Body

{
    "results": [
        {
            "id": "ac2e7f0b-a345-11e4-bfdb-005056837bc7",
            "name": "OV2 Once 512 ZC 384x216 448.64 29.97 B30",
            "default": true
        },
        {
            "id": "5ff484d6-a33d-11e4-bfdb-005056837bc7",
            "name": "OV2 Once 264 ZC 256x144 200.64 29.97 B30",
            "default": true
        }
    ]
}

Response Fields

Field Type Description
id String Each renditionId
name String Each rendition name
default Boolean If true, will be assigned to new catalogs by default

Get Domain Rendition Details

Retrieves video and audio encoding settings for the specified renditionId..

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/renditions/{renditionId}

Request Body

(none)

Response Body

{
    "id": "076ea1a2-a35b-11e4-bfdb-005056837bc7",
    "name": "OV2 Once 1200 ZC 640x360 1104.96 29.97 B31",
    "width": 640,
    "height": 360,
    "videoBitRate": 1104,
    "audioBitRate": 96,
    "codecsValue": "mp4a.40.2,avc1.42001f"
}

Response Fields

Field Type Description
id String The renditionId
name String The rendition name
width Number The frame width in pixels
height Number The frame height in pixels
videoBitRate Number The video bitrate in kbps
audioBitRate Number The audio bitrate in kbps
codecsValue String The audio and video codecs

Get All Domain Publication Rules

Retrieves all publicationRuleIds configured on the Domain level.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/publicationRules

Request Body

(none)

Response Body

[
    "602de576-68c3-403a-87f6-56108c6b1d1c"
]

Response Fields

Field Type Description
publicationRuleIds String[] A comma-separated array of publicationRuleIds configured at the Domain level (will be inherited by new catalogs)

Get All Domain Publication Rule Details

Retrieves configuration of a domain-level publication rule.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/publicationRules/{publicationRuleId}

Request Body

(none)

Response Body

{
        "channel": "5fba5bb0-5fba-5bb0-06ed-8768600306ed",
        "startDate": 1436384287,
        "endDate": 1752003487,
        "clientFilters": [
            {
                "variableName": "IpAddress",
                "value": "127.0.0.1",
                "filterType": "Equals",
                "isDenied": true
            }
        ],
        "countryRules": [
            {
                "countryCode": "FI",
                "isDenied": true
            }
        ],
        "id": "602de576-68c3-403a-87f6-56108c6b1d1c",
        "domain": "1234abcd-1234-abcd-56ef-098765fedcba"
    }

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
endDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The publication rule’s parent domainId

Create Domain Publication Rule

Create new domain-level Publication Rule. New rule will be inherited by new catalogs, but not existing catalogs. See below for details on adding publication rules to existing catalogs.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/publicationRules

Request Body

{
        "startDate": 1436384287,
        "endDate": 1952003487,
        "clientFilters": [
            {
                "variableName": "IpAddress",
                "value": "127.0.0.1",
                "filterType": "Equals",
                "isDenied": true
            }
        ],
        "countryRules": [
            {
                "countryCode": "FI",
                "isDenied": true
            }
        ]
    }

Request Fields

Field Type Required? Description
startDate Number Yes Epoch time (in seconds) when publication rule becomes effective
endDate Number Yes Epoch time (in seconds) when publication rule expires
clientFilters Object[] No Array of client-based filters
  variableName String If clientFilters are specified The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String If clientFilters are specified A string against which requests will be filtered
  filterType String If clientFilters are specified The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean If clientFilters are specified True: All other values will be permitted
False: Only this value will be permitted
countryRules Object[] No Array of country-based filters
  countryCode String If countryRules are specified ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean If countryRules are specified True: All other values will be permitted
False: Only this value will be permitted

Response Body

{
"channel": "5fba5bb0-5fba-5bb0-06ed-8768600306ed",
"startDate": 1436384287,
"endDate": 1752003487,
"clientFilters": [
    {
        "variableName": "IpAddress",
        "value": "127.0.0.1",
        "filterType": "Equals",
        "isDenied": true
    }
],
"countryRules": [
    {
        "countryCode": "FI",
        "isDenied": true
    }
],
"id": "602de576-68c3-403a-87f6-56108c6b1d1c",
"domain": "1234abcd-1234-abcd-56ef-098765fedcba"
}

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
startDate Number Epoch time (in seconds) when publication rule expires
clientFilters Object[] Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Object[] Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The publication rule’s parent domainId

Delete Domain Publication Rule

Deletes the specified domain publication rule. NOTE: Deleting a domain publication rule will prevent it from being added to new catalogs, but will not delete publication rules of existing catalogs or mediaItems within. Please see below for methods to delete publication rules assigned to catalogs or mediaItems.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/publicationRules/{publicationRuleId}

Request Body

(none)

Response Body

{
"id": "8c9cdb48-90ac-450f-bc5d-0bb2cbe3a206"
}

Get All Domain Timed Text

Retrieves all timed text for captions and subtitles for the domain.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/timedText

Request Body

(none)

Response Body

{
    "results": [{
        "id": "1e0a4a12-4aae-4975-97ea-f934292ef483",
        "domainId": "869a60ba-25da-4458-a558-50664e7a969d",
        "languages": ["en"],
        "format": "SRT",
        "version": 0
    }, {
        "id": "a44eb311-b1a6-4d0c-ba92-d54841c51126",
        "domainId": "869a60ba-25da-4458-a558-50664e7a969d",
        "languages": ["en"],
        "format": "SRT",
        "version": 0
    }, {
        "id": "c3255f78-e2e7-4a3c-bb78-240756ea9f9a",
        "domainId": "869a60ba-25da-4458-a558-50664e7a969d",
        "languages": ["fr"],
        "format": "SRT",
        "version": 0
    }],
    "prev": null,
    "next": null,
    "totalResults": null
}

Response Fields

Field Type Description
results Object[]

Array of timedText objects

  id String

Each timedText Id

  domainId String

The domain id

  languages String[]

An array of ISO 639-1 two-letter language codes for the captions or subtitles - for example: ["en", "fr"]

  format String

The format of the captions or subtitles, such as SRT

  version Number

The version of the captions or subtitles

prev String

URL to get the previous 20 results (if any)

next String

URL to get the next 20 results (if any)

totalResults Number

The total number of results (will be null unless there are more than 20 results)

Get Domain Timed Text Asset

Retrieves a timed text asset for captions and subtitles by id.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/timedText/{timedTextid}

Request Body

(none)

Response Body

{
    "id": "a44eb311-b1a6-4d0c-ba92-d54841c51126",
    "domainId": "869a60ba-25da-4458-a558-50664e7a969d",
    "languages": ["en"],
    "format": "SRT",
    "version": 0
}

Response Fields

Field Type Description
results Object[]

Array of timedText objects

  id String

Each timedText Id

  domainId String

The domain id

  languages String[]

An array of ISO 639-1 two-letter language codes for the captions or subtitles - for example: ["en", "fr"]

  format String

The format of the captions or subtitles, such as SRT

  version Number

The version of the captions or subtitles

Delete Media Item Timed Text Asset

Deletes a timed text asset for a media item.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/timedText/{timedTextId}

Request Body

(none)

Response Body

{
                  "requestId": "0e574fc1-f3ea-4825-af7e-fd09055f0524"
              }

Response Fields

Field Type Description
requestId String

Job id for the request

Catalog Methods

Get All Catalogs

Retrieves all catalogs in a domain. This method returns 20 results by default, totalResults indicates the total number of catalogs, previous and/or next page request URLs will be included within the response if necessary. URL Parameters may be appended to modify result sets.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs

Response

{
    "results": [
        {
            "id": "4321abcd-4321-dcba-fe65-567890fedcba",
            "name": "ExampleCatalog01",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
        },
        {
            "id": "4422abcd-4321-dcba-fe65-567890fedcba",
            "name": "ExampleCatalog02",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
        }
    ],
    "prev": null,
    "next": null,
    "totalResults": 2
}

Response Fields

Field Type Description
results Object[] Array of catalogs in result set
  id String Each catalogId
  name String Each catalog's name
  domainId String Each catalog’s parent domainId
prev URL URL to GET the previous catalog result set (if necessary)
next URL URL to GET the next catalog result set (if necessary)
totalResults Number The total number of catalogs in the domain

Get Catalog Details

Retrieves details of a specified catalog.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}

Request Body

(none)

Response Body

{
    "id": "4321abcd-4321-dcba-fe65-567890fedcba",
    "name": "ExampleCatalog01",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
}

Response Fields

Field Type Description
id String The catalogId
name String The catalog name
domainId String The catalog's parent domainId

Create Catalog

Creates a new catalog within the parent domainId. You may specify renditions when creating the catalog, otherwise it will be assigned all domain renditions marked as default. The new catalog will also inherit any domain publication rules.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs

Request Body

{
    "name":"ExampleCatalog03",
    "renditions": [
        {
        "id": "5ff484d6-a33d-11e4-bfdb-005056837bc7"
        },
        {
        "id": "ac2e7f0b-a345-11e4-bfdb-005056837bc7"
        }
    ]
}

Request Fields

Field Type Required? Description
name String Yes The new catalog name
renditions String[] No An array of renditions to be assigned to the catalog. If omitted, catalog will be assigned default domain renditions.
  id String Only if renditions are specified Each renditionId to be assigned to the catalog

Response Body

{
    "id": "f8933df8-dfa3-4d69-9f27-0420897e24aa",
    "name": "ExampleCatalog03",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
}

Response Fields

Field Type Description
id String The new catalogId
name String The new catalog name
domainId String The new catalog's parent domainId

Update Catalog Name

Assign a new name to the specified catalogId.

PUT https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs

Request Body

{
    "id": "4321abcd-4321-dcba-fe65-567890fedcba",
    "name": "ExampleCatalog001"
}

Request Fields

Field Type Required? Description
id String Yes The catalogId to be updated
name String Yes The new catalog name

Response Body

{
    "id": "4321abcd-4321-dcba-fe65-567890fedcba",
    "name": "ExampleCatalog001"
}

Response Fields

Field Type Description
id String The update catalogId
name String The updated catalog name

Get All Catalog Renditions

Retrieves the rendition set assigned to the specified catalog. NOTE: All videos ingested to this catalog will have these renditions assigned.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/renditions

Request Body

(none)

Response Body

{
    "results": [
        {
            "id": "076ea1a2-a35b-11e4-bfdb-005056837bc7",
            "name": "OV2 Once 1200 ZC 640x360 1104.96 29.97 B31"
        },
        {
            "id": "225bd8bb-a577-11e4-bfdb-005056837bc7",
            "name": "OV2 Once 2000 ZC 960x540 1872.128 29.97 M31"
        }
    ]
}

Response Fields

Field Type Description
results Object[] Array of renditions assigned to catalog
  id String The renditionId
  name String The rendition name

Get Catalog Rendition Details

Retrieves video and audio encoding settings for the specified renditionId.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/renditions/{renditionId}

Request Body

(none)

Response Body

{
    "id": "076ea1a2-a35b-11e4-bfdb-005056837bc7",
    "name": "OV2 Once 1200 ZC 640x360 1104.96 29.97 B31",
    "width": 640,
    "height": 360,
    "videoBitRate": 1104,
    "audioBitRate": 96,
    "codecsValue": "mp4a.40.2,avc1.42001f"
}

Response Fields

Field Type Description
id String The renditionId
name String The rendition name
width Number The frame width in pixels
height Number The frame height in pixels
videoBitRate Number The video bitrate in kbps
audioBitRate Number The audio bitrate in kbps
codecsValue String The audio and video codecs

Replace All Catalog Renditions

Replace (overwrite) the specified catalog’s current rendition set, using an updated array in the request body. NOTE: This method will not add the specified rendition(s) to, nor will it remove renditions from, existing mediaitems in the specified catalog. Please contact Support if you also need renditions assigned to or removed from previously-ingested mediaItems in the catalog.

PUT https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/renditions

Request Body

[
    {
        "id": "076ea1a2-a35b-11e4-bfdb-005056837bc7"
    },
    {
        "id": "225bd8bb-a577-11e4-bfdb-005056837bc7"
    },
    {
        "id": "468fb310-a585-11e4-bfdb-005056837bc7"
    }
]

Request Fields

Field Type Required? Description
id String Yes Each renditionId to be assigned to catalog

Response Body

[
    {
        "id": "076ea1a2-a35b-11e4-bfdb-005056837bc7"
    },
    {
        "id": "225bd8bb-a577-11e4-bfdb-005056837bc7"
    },
    {
        "id": "468fb310-a585-11e4-bfdb-005056837bc7"
    }
]

Response Fields

Field Type Description
id String Each renditionId to be assigned to catalog

Add Catalog Rendition

Add the specified new rendition to a catalog’s rendition set. New mediaItems ingested to the catalog will be assigned the specified rendition. NOTE: This method will not add the specified rendition to existing mediaItems in the catalog. Please contact Support if you also need new renditions assigned to previously-ingested mediaItems.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/renditions

Request Body

{
    "id": "8efbb9ca-a586-11e4-bfdb-005056837bc7"
}

Request Fields

Field Type Required? Description
id String Yes The new renditionId to be added to the catalog

Response Body

{
    "id": "8efbb9ca-a586-11e4-bfdb-005056837bc7"
}

Response Fields

Field Type Description
id String The new renditionId added to the catalog rendition set

Delete Catalog Rendition

Delete the specified rendition from a catalog’s rendition set. New mediaItems ingested to the catalog will no longer be assigned the specified rendition. NOTE: This method will not remove the specified rendition from existing mediaItems in the catalog. Please contact Support if you also need the specified rendition removed from previously-ingested mediaItems.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/renditions/{renditionId}

Request Body

(none)

Response Body

{
    "id": "825b7f2a-a31b-11e4-bfdb-005056837bc7"
}

Response Fields

Field Type Description
id String The renditionId removed from the catalog rendition set

Get All Catalog Publication Rules

Retrieves all publicationRuleIds assigned to a Catalog.

Please review the Content Restriction section of our Once VOD 2.0 Guide for details on what Publication Rules can do and how they are inherited.

GET https:api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/publicationRules

Request Body

(none)

Response Body

[
    "7454cab9-9491-43bb-84f4-b208487ca1fb"
]

Response Fields

Field Type Description
publicationRuleIds String[] A comma-separated array of publicationRuleIds assigned to the catalog (will be inherited by mediaItems ingested to the catalog)

Get Catalog Publication Rule Details

Retrieves configuration of a catalog-level publication rule.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/publicationRules/{publicationRuleId}

Request Body

(none)

Response Body

{
    "startDate": 1436384287,
    "endDate": 1752003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ],
    "id": "7454cab9-9491-43bb-84f4-b208487ca1fb",
    "domain": "1234abcd-1234-abcd-56ef-098765fedcba",
    "catalog": "4321abcd-4321-dcba-fe65-567890fedcba"
}

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
endDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The catalog's parent domainId
catalog String The publication rule's parent catalogId

Create Catalog Publication Rule

Create a catalog publication rule. NOTE: A new catalog publication rule created by this method will only be applied to new mediaItems ingested to the catalog, but will not be applied to existing mediaItems within. Please see below for a method to create or update publication rules assigned to individual mediaItems.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/publicationRules

Request Body

{
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ]
}

Request Fields

Field Type Required? Description
startDate Number Yes Epoch time (in seconds) when publication rule becomes effective
endDate Number Yes Epoch time (in seconds) when publication rule expires
clientFilters Object[] No Array of client-based filters
  variableName String If clientFilters are specified The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String If clientFilters are specified A string against which requests will be filtered
  filterType String If clientFilters are specified The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean If clientFilters are specified True: All other values will be permitted
False: Only this value will be permitted
countryRules Object[] No Array of country-based filters
  countryCode String If countryRules are specified ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean If countryRules are specified True: All other values will be permitted
False: Only this value will be permitted

Response Body

{
    "channel": "5fba5bb0-5fba-5bb0-06ed-8768600306ed",
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ],
    "id": "7454cab9-9491-43bb-84f4-b208487ca1fb",
    "domain": "1234abcd-1234-abcd-56ef-098765fedcba",
    "catalog": "4321abcd-4321-dcba-fe65-567890fedcba"
}

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
startDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The catalog's parent domainId
catalog String The publication rule's parent catalogId

Update Catalog Publication Rule

Update a catalog publication rule. NOTE: Updates made by this method will only be applied to new mediaItems ingested to the catalog, but will not update publication rules of existing mediaItems within. Please see below for a method to update publication rules assigned to individual mediaItems.

PUT https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/publicationRules/{publicationRuleId}

Request Body

{
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ]
}

Request Fields

Field Type Required? Description
startDate Number Yes Epoch time (in seconds) when publication rule becomes effective
endDate Number Yes Epoch time (in seconds) when publication rule expires
clientFilters Object[] No Array of client-based filters
  variableName String If clientFilters are specified The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String If clientFilters are specified A string against which requests will be filtered
  filterType String If clientFilters are specified The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean If clientFilters are specified True: All other values will be permitted
False: Only this value will be permitted
countryRules Object[] No Array of country-based filters
  countryCode String If countryRules are specified ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean If countryRules are specified True: All other values will be permitted
False: Only this value will be permitted

Response Body

{
    "channel": "5fba5bb0-5fba-5bb0-06ed-8768600306ed",
    "startDate": 1436384287,
    "endDate": 1752003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ],
    "id": "7454cab9-9491-43bb-84f4-b208487ca1fb",
    "domain": "1234abcd-1234-abcd-56ef-098765fedcba",
    "catalog": "4321abcd-4321-dcba-fe65-567890fedcba"
}

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
startDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The catalog's parent domainId
catalog String The publication rule's parent catalogId

Delete Catalog Publication Rule

Deletes the specified catalog publication rule. NOTE: Deleting a catalog publication rule will prevent it from being applied to new mediaItems ingested to the catalog, but will not delete publication rules of existing mediaItems within. Please see below for the method to delete publication rules assigned to mediaItems.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/publicationRules/{publicationRuleId}

Request Body

(none)

Response Body

{
"id": "7454cab9-9491-43bb-84f4-b208487ca1fb"
}

MediaItem Methods

Get All MediaItems In Catalog

Retrieves a list of mediaItems in a catalog. This method returns 20 results by default, totalResults indicates the total number of mediaItems in the catalog, previous and/or next page request URLs will be included within the response if necessary. URL Parameters may be appended to modify result sets.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems

URL Parameters

Request Body

(none)

Response Body

{
    "results": [
        {
            "id": "784c2091-5b28-4092-b135-5135b02adbfb",
            "catalogId": "4321abcd-4321-dcba-fe65-567890fedcba",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
            "isAd": false,
            "foreignKey": "mediaItemExample01",
            "title": "mediaItemExample01",
            "draftVersion": 0,
            "publishedVersion": 0
        },
        {
            "id": "895effcb-4e08-4874-8b84-bb6a9dc9a2de",
            "catalogId": "4321abcd-4321-dcba-fe65-567890fedcba",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
            "isAd": false,
            "foreignKey": "mediaItemExample02",
            "title": "mediaItemExaple02",
            "draftVersion": 0,
            "publishedVersion": 0
        }
    ],
    "prev": null,
    "next": null,
    "totalResults": 2
}

Response Fields

Field Type Description
results Object[] Array of mediaItems in result set
  id String Each mediaItem’s Id
  catalogId String Each mediaItem’s parent catalogId
  domainId String Each mediaItem’s parent domainId
  isAd Boolean (Internal use only)
  foreignKey String Each mediaItem’s foreignKey
  title String Each mediaItem’s title
  draftVersion Number The iteration of that specific mediaItem (will increment if a new version of the video is ingested)
  publishedVersion Number The iteration of that specific mediaItem (will increment if a new version of the video is ingested)
prev URL URL to GET the previous catalog result set (if necessary)
next URL URL to GET the next catalog result set (if necessary)
totalResults Number The total number of catalogs in the domain

Get MediaItem Details

Retrieves details of a specified mediaItem.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}

Request Body

(none)

Response Body

{
    "id": "fd2572c7-8d27-4813-af58-81b287f4e2e9",
    "catalogId": "4321abcd-4321-dcba-fe65-567890fedcba",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "foreignKey": "mediaItemExample01",
    "title": "mediaItemExample01",
    "draftVersion": 0,
    "publishedVersion": 0,
    "description": "An example mediaItem for documentation",
    "keywords": [
        "Example",
        "Test"
    ],
    "cuePoints": [
        {
            "unit": "Seconds",
            "valueIn": 10
        },
        {
            "unit": "Seconds",
            "valueIn": 25
        }
    ],
    "publicationRules": [
        {
            "startDate": 1436384287,
            "endDate": 1752003487,
            "clientFilters": [
                {
                    "variableName": "IpAddress",
                    "value": "127.0.0.1",
                    "filterType": "Equals",
                    "isDenied": true
                }
            ],
            "countryRules": [
                {
                    "countryCode": "FI",
                    "isDenied": true
                }
            ]
        }
    ],
    "metadata": {
        "JobId": "JobIdValue",
        "AdvertisingId": "AdvertisingIdValue",
        "OtherKey": "OtherValue"
    }
}

Response Fields

Field Type Description
id String The mediaItemId
catalogId String The mediaItem's parent catalogId
domainId String The mediaItem's parent domainId
foreignKey String The mediaItem's foreignKey
title String The mediaItem's title
draftVersion Number The iteration of that specific mediaItem (will increment if a new version of the video is ingested)
publishedVersion Number The iteration of that specific mediaItem (will increment if a new version of the video is ingested)
description String The description of the video
keywords String[] Array of video keywords
cuePoints Object[] Array of cue point objects
  unit String Unit of time
  valueIn Number Time of cue point
publicationRules Object[] Array of Publication Rules
  startDate Number Epoch time (in seconds) when publication rule becomes effective
  endDate Number Epoch time (in seconds) when publication rule expires
  clientFilters Array Array of client-based filters
    variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
    value String A string against which requests will be filtered
    filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
    isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
  countryRules Array Array of country-based filters
    countryCode String ISO 3166-1 alpha-2 country code being filtered
    isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
metadata Object Map of Extended Metadata key-value pairs

Update MediaItem

Updates the mediaItem to reflect the request body. NOTE: All mediaItem fields must be present in your request, not just those you wish to update. Existing fields with missing values in the update request will be overwritten with null values.

We recommend using the Get MediaItem Details method to gather existing details before POSTing the update method, to ensure your update request preserves all existing fields.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}

Request Body

{
    "id": "fd2572c7-8d27-4813-af58-81b287f4e2e9",
    "catalogId": "4321abcd-4321-dcba-fe65-567890fedcba",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "foreignKey": "mediaItemExample01",
    "title": "mediaItemExample001",
    "description": "An example mediaItem for documentation",
    "keywords": [
        "Example",
        "Test"
    ],
    "cuePoints": [
        {
            "unit": "Seconds",
            "valueIn": 10
        },
        {
            "unit": "Seconds",
            "valueIn": 25
        }
    ],
    "publicationRules": [
        {
            "startDate": 1436384287,
            "endDate": 1752003487,
            "clientFilters": [
                {
                    "variableName": "IpAddress",
                    "value": "127.0.0.1",
                    "filterType": "Equals",
                    "isDenied": true
                }
            ],
            "countryRules": [
                {
                    "countryCode": "FI",
                    "isDenied": true
                }
            ]
        }
    ],
    "metadata": {
        "JobId": "JobIdValue",
        "AdvertisingId": "AdvertisingIdValue",
        "OtherKey": "OtherValue"
    }
}

Request Fields

Field Type Required? Description
id String Yes The mediaItemId
catalogId String Yes The mediaItem's parent catalogId
domainId String Yes The mediaItem's parent domainId
foreignKey String No The mediaItem's foreignKey
title String No The mediaItem's title
description String No The description of the video
keywords String[] No Array of video keywords
cuePoints Object[] No Array of cue point objects
  unit String If cuePoints are specified Unit of time
  valueIn Number If cuePoints are specified Time of cue point
publicationRules Object[] No Array of Publication Rules
  startDate Number If pubRules are specified Epoch time (in seconds) when publication rule becomes effective
  endDate Number If pubRules are specified Epoch time (in seconds) when publication rule expires
  clientFilters Array No Array of client-based filters
    variableName String If clientFilters are specified The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
    value String If clientFilters are specified A string against which requests will be filtered
    filterType String If clientFilters are specified The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
    isDenied Boolean If clientFilters are specified True: All other values will be permitted
False: Only this value will be permitted
  countryRules Array No Array of country-based filters
    countryCode String If countryRules are specified ISO 3166-1 alpha-2 country code being filtered
    isDenied Boolean If countryRules are specified True: All other values will be permitted
False: Only this value will be permitted
metadata Object No Map of Extended Metadata key-value pairs

Response Body

{
    "id": "fd2572c7-8d27-4813-af58-81b287f4e2e9",
    "catalogId": "4321abcd-4321-dcba-fe65-567890fedcba",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "foreignKey": "mediaItemExample01",
    "title": "mediaItemExample001",
    "draftVersion": 0,
    "publishedVersion": 0,
    "description": "An example mediItem for documentation",
    "keywords": [
        "Different",
        "Words"
    ],
    "cuePoints": [
        {
            "unit": "Seconds",
            "valueIn": 30
        },
        {
            "unit": "Seconds",
            "valueIn": 12
        }
    ],
    "publicationRules": [
        {
            "startDate": 1436384287,
            "endDate": 1752003487,
            "clientFilters": [
                {
                    "variableName": "IpAddress",
                    "value": "127.0.0.1",
                    "filterType": "Equals",
                    "isDenied": true
                }
            ],
            "countryRules": [
                {
                    "countryCode": "UK",
                    "isDenied": true
                }
            ]
        }
    ],
    "metadata": {
        "OtherKey": "OtherValue",
        "AdvertisingId": "AdvertisingIdValue",
        "JobId": "JobIdValue"
    }
}

Response Fields

Field Type Description
id String The mediaItemId
catalogId String The mediaItem's parent catalogId
domainId String The mediaItem's parent domainId
foreignKey String The mediaItem's foreignKey
title String The mediaItem's title
draftVersion Number The iteration of that specific mediaItem (will increment if a new version of the video is ingested)
publishedVersion Number The iteration of that specific mediaItem (will increment if a new version of the video is ingested)
description String The description of the video
keywords String[] Array of video keywords
cuePoints Object[] Array of cue point objects
  unit String Unit of time
  valueIn Number Time of cue point
publicationRules Object[] Array of Publication Rules
  startDate Number Epoch time (in seconds) when publication rule becomes effective
  endDate Number Epoch time (in seconds) when publication rule expires
  clientFilters Array Array of client-based filters
    variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
    value String A string against which requests will be filtered
    filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
    isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
  countryRules Array Array of country-based filters
    countryCode String ISO 3166-1 alpha-2 country code being filtered
    isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
metadata Object Map of Extended Metadata key-value pairs

Get All MediaItem Publication Rules

Retrieves all publicationRuleIds assigned to a mediaItem.

Please review the Content Restriction section of our Once VOD 2.0 Guide for details on what Publication Rules can do and how they are inherited.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/publicationRules

Request Body

(none)

Response Body

[
    "e4f3e3de-e580-42a7-9960-f43faccfbee5"
]

Response Fields

Field Type Description
publicationRuleIds String[] A comma-separated array of publicationRuleIds assigned to the mediaItem

Get MediaItem Publication Rule Details

Retrieves configuration of a mediaItem-level publication rule.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/publicationRules/{publicationRuleId}

Request Body

(none)

Response Body

{
    "startDate": 1440720000,
    "endDate": 1914105600,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ]
    "id": "e4f3e3de-e580-42a7-9960-f43faccfbee5",
    "domain": "1234abcd-1234-abcd-56ef-098765fedcba",
    "catalog": "4321abcd-4321-dcba-fe65-567890fedcba",
    "mediaitem": "09daf3a0-5efe-4048-a761-351137a23c6f"
}

Response Fields

Field Type Description
startDate Number Epoch time (in seconds) when publication rule becomes effective
startDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The catalog's parent domainId
catalog String The publication rule's parent catalogId
mediaItem String The publication rule’s parent mediaItemId

Create MediaItem Publication Rule

Create a mediaItem publication rule.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/publicationRules

Request Body

{
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ]
}

Request Fields

Field Type Required? Description
startDate Number Yes Epoch time (in seconds) when publication rule becomes effective
endDate Number Yes Epoch time (in seconds) when publication rule expires
clientFilters Object[] No Array of client-based filters
  variableName String If clientFilters are specified The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String If clientFilters are specified A string against which requests will be filtered
  filterType String If clientFilters are specified The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean If clientFilters are specified True: All other values will be permitted
False: Only this value will be permitted
countryRules Object[] No Array of country-based filters
  countryCode String If countryRules are specified ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean If countryRules are specified True: All other values will be permitted
False: Only this value will be permitted

Response Body

{
    "channel": "5fba5bb0-5fba-5bb0-06ed-8768600306ed",
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ],
    "id": "e4f3e3de-e580-42a7-9960-f43faccfbee5",
    "domain": "1234abcd-1234-abcd-56ef-098765fedcba",
    "catalog": "4321abcd-4321-dcba-fe65-567890fedcba",
    "mediaitem": "09daf3a0-5efe-4048-a761-351137a23c6f"
}

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
startDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The catalog's parent domainId
catalog String The publication rule's parent catalogId
mediaItem String The publication rule’s parent mediaItemId

Update MediaItem Publication Rule

Update a mediaItem publication rule.

PUT https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/publicationRules

Request Body

{
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ]
}

Request Fields

Field Type Required? Description
startDate Number Yes Epoch time (in seconds) when publication rule becomes effective
endDate Number Yes Epoch time (in seconds) when publication rule expires
clientFilters Object[] No Array of client-based filters
  variableName String If clientFilters are specified The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String If clientFilters are specified A string against which requests will be filtered
  filterType String If clientFilters are specified The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean If clientFilters are specified True: All other values will be permitted
False: Only this value will be permitted
countryRules Object[] No Array of country-based filters
  countryCode String If countryRules are specified ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean If countryRules are specified True: All other values will be permitted
False: Only this value will be permitted

Response Body

{
    "channel": "5fba5bb0-5fba-5bb0-06ed-8768600306ed",
    "startDate": 1436384287,
    "endDate": 1952003487,
    "clientFilters": [
        {
            "variableName": "IpAddress",
            "value": "127.0.0.1",
            "filterType": "Equals",
            "isDenied": true
        }
    ],
    "countryRules": [
        {
            "countryCode": "FI",
            "isDenied": true
        }
    ],
    "id": "e4f3e3de-e580-42a7-9960-f43faccfbee5",
    "domain": "1234abcd-1234-abcd-56ef-098765fedcba",
    "catalog": "4321abcd-4321-dcba-fe65-567890fedcba",
    "mediaitem": "09daf3a0-5efe-4048-a761-351137a23c6f"
}

Response Fields

Field Type Description
channel String (Internal Use Only)
startDate Number Epoch time (in seconds) when publication rule becomes effective
startDate Number Epoch time (in seconds) when publication rule expires
clientFilters Array Array of client-based filters
  variableName String The type of client variable being filtered: (IpAddress, UserAgent, ReferringHost)
  value String A string against which requests will be filtered
  filterType String The method of filtering against the value string: (Equals, NotEquals, In, NotIn, Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith)
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
countryRules Array Array of country-based filters
  countryCode String ISO 3166-1 alpha-2 country code being filtered
  isDenied Boolean True: All other values will be permitted
False: Only this value will be permitted
id String The publicationRuleId
domain String The catalog's parent domainId
catalog String The publication rule's parent catalogId
mediaItem String The publication rule’s parent mediaItemId

Delete MediaItem Publication Rule

Deletes the specified mediaItem publication rule.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/publicationRules/{publicationRuleId}

Request Body

(none)

Response Body

{
"id": "e4f3e3de-e580-42a7-9960-f43faccfbee5"
}

Delete MediaItem

Delete the mediaItem and all associated metadata and renditions from Brightcove. NOTE: This action cannot be canceled or reversed.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}

Request Body

(none)

Response Body

{ "delete": "MediaItem: fd2572c7-8d27-4813-af58-81b287f4e2e9 scheduled for deletion" }

Get Media Item Timed Text Asset

Retrieves the timed text assets for a media item.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/timedText

Request Body

(none)

Response Body

{
    "results": [{
        "id": "6e376b50-e8e5-46fe-922c-17199e5950cd",
        "languages": ["kr"],
        "timedTextType": "SUBTITLE"
    }, {
        "id": "a44eb311-b1a6-4d0c-ba92-d54841c51126",
        "languages": ["en"],
        "timedTextType": "CAPTION"
    }, {
        "id": "c3255f78-e2e7-4a3c-bb78-240756ea9f9a",
        "languages": ["fr"],
        "timedTextType": "SUBTITLE"
    }]
}

Response Fields

Field Type Description
results Object[]

Array of timedText objects

  id String

Each timedText Id

  languages String[]

An array of ISO 639-1 two-letter language codes for the captions or subtitles - for example: ["en", "fr"]

  timedTextType String

The type of the timed text: CAPTION or SUBTITLE, or EMBEDDED

Create Media Item Timed Text Asset

Creates a timed text asset for a media item.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/timedText

Request Body

{
    "domain":"869a60ba-25da-4458-a558-50664e7a969d",
    "catalog":"5daddac0-b74e-43c4-a560-f5d690893857",
    "mediaItem":"045da231-a9ae-4444-a46b-6a865be222aa",
    "timedText": {
        "media": {
            "sourceURL": "https://s3-us-west-2.amazonaws.com/tjones-test-resources/timedText/longCaptionLines.srt"
        },
        "timedTextType": "SUBTITLE",
        "languages": ["en"]
    }
}

Request Body Fields

Field Type Description
domain String

The domain id

catalog String

The catalog id

mediaItem String

The mediaItem id

timedText Object

The timed text object

  media Object

Object detailing the timed text media asset

    sourceURL String

Location of the timed text media asset

  timedTextType String

The type for the timed text

Allowed values: "CAPTION", "SUBTITLE", "EMBEDDED"

  languages String[]

An array of ISO 639-1 two-letter language codes for the captions or subtitles - for example: ["en", "fr"]

Response Body

{
    "requestId": "0e574fc1-f3ea-4825-af7e-fd09055f0524"
}

Response Fields

Field Type Description
requestId String

Job id for the request

Update Media Item Timed Text Asset

Updates a timed text asset for a media item.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/catalogs/{catalogId}/mediaItems/{mediaItemId}/timedText/{timedTextId}

Request Body

{
    "domain":"869a60ba-25da-4458-a558-50664e7a969d",
    "catalog":"5daddac0-b74e-43c4-a560-f5d690893857",
    "mediaItem":"045da231-a9ae-4444-a46b-6a865be222aa",
    "timedText": {
        "media": {
            "sourceURL": "https://s3-us-west-2.amazonaws.com/tjones-test-resources/timedText/longCaptionLines.srt"
        },
        "timedTextType": "SUBTITLE",
        "languages": ["en"]
    }
}

Request Body Fields

Field Type Description
domain String

The domain id

catalog String

The catalog id

mediaItem String

The mediaItem id

timedText Object

The timed text object

  media Object

Object detailing the timed text media asset

    sourceURL String

Location of the timed text media asset

  timedTextType String

The type for the timed text

Allowed values: "CAPTION", "SUBTITLE", "EMBEDDED"

  languages String[]

An array of ISO 639-1 two-letter language codes for the captions or subtitles - for example: ["en", "fr"]

Response Body

{
    "requestId": "0e574fc1-f3ea-4825-af7e-fd09055f0524"
}

Response Fields

Field Type Description
requestId String

Job id for the request

Application Methods

Get All Applications

Returns all applications configured in the domain. This method returns 20 results by default, totalResults indicates the total number of applications in the domain, previous and/or next page request URLs will be included within the response if necessary. URL Parameters may be appended to modify result sets.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/

URL Parameters

Request Body

(none)

Response Body

{
    "results": [
        {
            "id": "2baf3c54-2baf-3c54-be91-147ffc57ebbe",
            "name": "ExampleApplication01",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
        },
        {
            "id": "a5ca87ef-a5ca-87ef-928c-70794563a8a1",
            "name": "ExampleApplication02",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
        }
    ],
    "prev": null,
    "next": null,
    "totalResults": 2
}

Response Fields

Field Type Description
results Object[] Array of applications in result set
  id String Each applicationId
  name String Each application's name
  domainId String Each application's parent domainId
prev URL URL to GET the previous application result set (if necessary)
next URL URL to GET the next application result set (if necessary)
totalResults Number The total number of applications in the domain

Get Application Details

Retrieves the details of an application, including its ad configurations. Below are two examples:

  1. Single VAST ad request(s) will be made for each configured adPosition (preRoll, midRoll, and/or postRoll).
  2. Multiple (ad) configuration, enabling an ad decisioning server to specify all ad breaks in a single response (Freewheel SmartXML, DFP Ad Rules).

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/{applicationId}

Request Body

(none)

Response Body (Example 1)

{
    "id": "2baf3c54-2baf-3c54-be91-147ffc57ebbe",
    "name": "ExampleApplication01",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "adConfig": {
        "preRoll": {
            "id": "657d722b-a031-4422-87cc-6ae27329edf2",
            "name": "ExampleVASTPreRollConfig",
            "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
            "adServerName": "ExampleVASTAdServer",
            "adPosition": "preroll"
        },
        "postRoll": {
            "id": "a0314422-a031-4422-87cc-6ae27329edf2",
            "name": "ExampleVASTPostRollConfig",
            "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
            "adServerName": "ExampleVASTAdServer",
            "adPosition": "postroll"
        }
    },
    "preRollAdCount": 1,
    "midRollAdCount": 0,
    "postRollAdCount": 1
}

Response Fields (Example 1)

Field Type Description
id String The applicationId
name String The application's name
domainId String The application's parent domainId
adConfig Object An object set of ads configured to the application
  preRoll Object A single VAST adConfig for the preRoll slot
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for a single VAST ad
    adPosition String The position into which the ad will be inserted (preRoll)
  midRoll Object A single VAST adConfig for the midRoll slot
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for a single VAST ad
    adPosition String The position into which the ad will be inserted (midRoll)
  postRoll Object A single VAST adConfig for the postRoll slot
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for a single VAST ad
    adPosition String The position into which the ad will be inserted (postRoll)
preRollAdCount Number The number of single VAST ads to be requested for the preRoll position
midRollAdCount Number The number of single VAST ads to be requested for the midRoll position
postRollAdCount Number The number of single VAST ads to be requested for the postRoll position

Response Body (Example 2)

{
    "id": "a5ca87ef-a5ca-87ef-928c-70794563a8a1",
    "name": "ExampleApplication02",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "adConfig": {
        "ad": {
            "id": "a96a8715-5b80-468f-9cf0-683e52f5768b",
            "name": "ExamplePodAdConfig",
            "adServerId": "4f7ceb38-5093-437b-883b-ba96c413c4d7",
            "adServerName": "ExamplePodAdServer",
            "adPosition": "dfp"
        }
    },
    "preRollAdCount": 0,
    "midRollAdCount": 0
    "postRollAdCount": 0
}

Response Fields (Example 2)

Field Type Description
id String The applicationId
name String The application's name
domainId String The application's parent domainId
adConfig Object An object set of ads configured to the application
ad Object An adConfig where a single request will return a full, multiple ad load
  id String The adConfigId/td>
  name String The adConfig's name
  adServerId String The adServerId which will be requested for the multiple ad load
  adServerName String The adServer’s name
  adPosition String The multiple adServer configuration type (dfp or smartxml)
preRollAdCount Number Leave at zero (the adServer will determine number of ads returned for preRoll position)
midRollAdCount Number Leave at zero (the adServer will determine number of ads returned for midRoll position)
postRollAdCount Number Leave at zero (the adServer will determine number of ads returned for postRoll position)

Create Application

Creates an new application in the domain.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications

Request Body

{
    "name": "ExampleApplication03",
    "preRollAdCount": 0,
    "midRollAdCount": 0,
    "postRollAdCount": 0
}

Request Fields

Field Type Required? Description
name String Yes Name of the new application
preRollAdCount Number only if using single VAST adConfig Number of single VAST ads to be requested for the preRoll position
midRollAdCount Number only if using single VAST adConfig Number of single VAST ads to be requested for the midRoll position
postRollAdCount Number only if using single VAST adConfig Number of single VAST ads to be requested for the postRoll position

Response Body

{
    "id": "2baf3c54-7761-4a31-be91-147ffc57ebbe",
    "name": "ExampleApplication03",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "adConfig": null,
    "preRollAdCount": 0,
    "midRollAdCount": 0,
    "postRollAdCount": 0
}

Response Fields

Field Type Description
id String The applicationId
name String The application's name
domainId String The application's parent domainId
adConfig Object Will remain null until adConfig has been added (see methods below)
preRollAdCount Number The number of single VAST ads to be requested for the preRoll position
midRollAdCount Number The number of single VAST ads to be requested for the midRoll position
postRollAdCount Number The number of single VAST ads to be requested for the postRoll position

Update Application

Update the name or number of ads requested in the VAST pre/mid/postRoll slots.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/{applicationId}

Request Body

{
    "name": "ExampleApplication03",
    "preRollAdCount": 1,
    "midRollAdCount": 0,
    "postRollAdCount": 1
}

Request Fields

Field Type Required? Description
name String Yes Name of the new application
preRollAdCount Number only if using single VAST adConfig Number of single VAST ads to be requested for the preRoll position
midRollAdCount Number only if using single VAST adConfig Number of single VAST ads to be requested for the midRoll position
postRollAdCount Number only if using single VAST adConfig Number of single VAST ads to be requested for the postRoll position

Response Body

{
    "id": "2baf3c54-7761-4a31-be91-147ffc57ebbe",
    "name": "ExampleApplication03",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "adConfig": null,
    "preRollAdCount": 1,
    "midRollAdCount": 0,
    "postRollAdCount": 1
}

Response Fields

Field Type Description
id String The applicationId
name String The application's name
domainId String The application's parent domainId
adConfig Object Will remain null until adConfig has been added (see methods below)
preRollAdCount Number The number of single VAST ads to be requested for the preRoll position
midRollAdCount Number The number of single VAST ads to be requested for the midRoll position
postRollAdCount Number The number of single VAST ads to be requested for the postRoll position

Delete Application

Deletes an application from the domain. This method will delete all of the application’s adConfigs, but will not delete any related adServer(s). See below for a method to delete adServers.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/{applicationId}

Request Body

(none)

Response Body

{
    "id": "2baf3c54-7761-4a31-be91-147ffc57ebbe"
}

Application Ad Configuration Methods

Get All Application Ad Configurations

Retrieves all adConfigs assigned to a single Application. Below are two examples:

  1. Single VAST ad request(s) will be made for each configured adPosition (preRoll, midRoll, and/or postRoll).
  2. Multiple (ad) configuration, enabling an ad decisioning server to specify all ad breaks in a single response (Freewheel SmartXML, DFP Ad Rules).

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/{applicationId}/adConfig

Request Body

(none)

Response Body (Example 1)

{
    "preRoll": {
        "id": "657d722b-a031-4422-87cc-6ae27329edf2",
        "name": "ExampleVASTPreRollConfig",
        "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
        "adServerName": "ExampleVASTAdServer",
        "adPosition": "preroll"
    },
    "midRoll": {
        "id": "6ae27329-a031-4422-87cc-6ae27329edf2",
        "name": "ExampleVASTMidRollConfig",
        "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
        "adServerName": "ExampleVASTAdServer",
        "adPosition": "midroll"
    },
    "postRoll": {
        "id": "a0314422-a031-4422-87cc-6ae27329edf2",
        "name": "ExampleVASTPostRollConfig",
        "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
        "adServerName": "ExampleVASTAdServer",
        "adPosition": "postroll"
    }
}

Response Fields (Example 1)

Field Type Description
preRoll Object A single VAST adConfig for the preRoll slot
  id String The AdConfigId
  name String The AdConfig's name
  AdServerId String The adServerId which will be requested for a single VAST ad
  AdServerName String The adServer's name
  AdPosition String The position into which the ad will be inserted (preRoll)
midRoll Object A single VAST adConfig for the midRoll slot
  id String The AdConfigId
  name String The AdConfig's name
  AdServerId String The adServerId which will be requested for a single VAST ad
  AdServerName String The adServer's name
  AdPosition String The position into which the ad will be inserted (midRoll)
postRoll Object A single VAST adConfig for the postRoll slot
  id String The AdConfigId
  name String The AdConfig's name
  AdServerId String The adServerId which will be requested for a single VAST ad
  AdServerName String The adServer's name
  AdPosition String The position into which the ad will be inserted (postRoll)

Response Body (Example 2)

{
    "ad": {
        "id": "a96a8715-5b80-468f-9cf0-683e52f5768b",
        "name": "ExampleSmartXMLAdConfig",
        "adServerId": "5093883b-5093-437b-883b-ba96c413c4d7",
        "adServerName": "ExampleSmartXMLAdServer",
        "adPosition": "smartxml"
    }
}

Response Fields (Example 2)

Field Type Description
Ad Object An adConfig where a single request will return a full, multiple ad load
  id String The AdConfigId
  name String The AdConfig's name
  AdServerId String The adServerId which will be requested for the multiple ad load
  AdServerName String The adServer's name
  AdPosition String The multiple adServer configuration type (dfp or smartxml)

Add or Replace Application Ad Configuration

Add or replace the adConfig assigned to the specified application. Below are two examples:

  1. Single VAST ad request(s) will be made for each configured adPosition (preRoll, midRoll, and/or postRoll).
  2. Multiple (ad) configuration, enabling an ad decisioning server to specify all ad breaks in a single response (Freewheel SmartXML, DFP Ad Rules).

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/{applicationId}/adConfig

Request Body (Example 1)

{
    "preRoll": {
        "name": "ExampleNewVASTPreRollConfig",
        "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d"
    },
    "midRoll": {
        "name": "ExampleNewVASTMidRollConfig",
        "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d"
    },
    "postRoll": {
        "name": "ExampleNewVASTPostRollConfig",
        "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d"
    }
}

Request Fields (Example 1)

Field Type Required? Description
preRoll Object If VAST preRoll ad needed A single VAST adConfig for the preRoll slot
  name String If preRoll specified A single VAST adConfig for the preRoll slot
  adServerId String If preRoll specified The adServerId which will be requested for a single VAST ad
midRoll Object If VAST midRoll ad needed A single VAST adConfig for the midRoll slot
  name String If midRoll specified A single VAST adConfig for the midRoll slot
  adServerId String If midRoll specified The adServerId which will be requested for a single VAST ad
postRoll Object If VAST postRoll ad needed A single VAST adConfig for the postRoll slot
  name String If postRoll specified A single VAST adConfig for the postRoll slot
  adServerId String If postRoll specified The adServerId which will be requested for a single VAST ad

Response Body (Example 1)

{
    "id": "2baf3c54-2baf-3c54-be91-147ffc57ebbe",
    "name": "ExampleApplication01",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "adConfig": {
        "preRoll": {
            "id": "657d722b-a031-4422-87cc-6ae27329edf2",
            "name": "ExampleNewVASTPreRollConfig",
            "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
            "adServerName": "ExampleVASTAdServer",
            "adPosition": "preroll"
        },
              "midRoll": {
            "id": "6ae27329-a031-4422-87cc-6ae27329edf2",
            "name": "ExampleNewVASTMidRollConfig",
            "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
            "adServerName": "ExampleVASTAdServer",
            "adPosition": "midroll"
        },
              "postRoll": {
            "id": "a0314422-a031-4422-87cc-6ae27329edf2",
            "name": "ExampleNewVASTPostRollConfig",
            "adServerId": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
            "adServerName": "ExampleVASTAdServer",
            "adPosition": "postroll"
        }
    },
    "preRollAdCount": 1,
    "midRollAdCount": 2,
    "postRollAdCount": 1
}

Response Fields (Example 1)

Field Type Description
id String The applicationId
name String The application's name
domainId String The application's parent domainId
adConfig Object An object set of ads configured to the application
  preRoll Object An object set of ads configured to the application
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for a single VAST ad
    adServerName String The adServer's name
    adPosition String The position into which the ad will be inserted (preRoll)
  midRoll Object An object set of ads configured to the application
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for a single VAST ad
    adServerName String The adServer's name
    adPosition String The position into which the ad will be inserted (midRoll)
  postRoll Object An object set of ads configured to the application
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for a single VAST ad
    adServerName String The adServer's name
    adPosition String The position into which the ad will be inserted (postRoll)
preRollAdCount Number The number of single VAST ads to be requested for the preRoll position
midRollAdCount Number The number of single VAST ads to be requested for the midRoll position
postRollAdCount Number The number of single VAST ads to be requested for the postRoll position

Request Body (Example 2)

{
    "ad": {
        "name": "ExampleSmartXMLAdConfig",
        "adServerId": "5093883b-5093-437b-883b-ba96c413c4d7",
        "adPosition": "smartxml"
    }
}

Request Fields (Example 2)

Field Type Required? Description
ad Object Yes An adConfig where a single request will return a full, multiple ad load
  name String Yes The new/updated adConfig’s name
  adServerId String Yes The adServerId which will be requested for the multiple ad load
  adPosition String Yes The multiple adServer configuration type. Syntax must be dfp or smartxml

Response Body (Example 2)

{
    "id": "2baf3c54-2baf-3c54-be91-147ffc57ebbe",
    "name": "ExampleApplication01",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "adConfig": {
        "ad": {
            "id": "a96a8715-5b80-468f-9cf0-683e52f5768b",
            "name": "ExampleSmartXMLAdConfig",
            "adServerId": "5093883b-5093-437b-883b-ba96c413c4d7",
            "adServerName": "ExampleSmartXMLAdServer",
            "adPosition": "smartxml"
        }
    },
    "preRollAdCount": 0,
    "midRollAdCount": 0,
    "postRollAdCount": 0
}

Response Fields (Example 2)

Field Type Description
id String The applicationId
name String The application's name
domainId String The application's parent domainId
adConfig Object An object set of ads configured to the application
  ad Object An adConfig where a single request will return a full, multiple ad load
    id String The adConfigId
    name String The adConfig's name
    adServerId String The adServerId which will be requested for the multiple ad load
    adServerName String The adServerId's name
    adPosition String The multiple adServer configuration type (dfp or smartxml)
preRollAdCount Number Leave at zero (the adServer will determine number of ads returned for preRoll position)
midRollAdCount Number Leave at zero (the adServer will determine number of ads returned for midRoll position)
postRollAdCount Number Leave at zero (the adServer will determine number of ads returned for postRoll position)

Delete Application Ad Configurations

Deletes all ad configurations from the specified application.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/applications/{applicationId}/adConfig

Request Body

(none)

Response Body

{
    "id": [
        "a96a8715-5b80-468f-9cf0-683e52f5768b"
    ]
}

Response Fields

Field Type Description
id String[] An array of adConfigId(s) which have been deleted

Ad Decisioning Server Methods

Get All Ad Decisioning Servers

Retrieves all ad decisioning servers configured in the domain. This method returns 20 results by default, totalResults indicates the total number of applications in the domain, previous and/or next page request URLs will be included within the response if necessary. URL Parameters may be appended to modify result sets.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/adServers

URL Parameters

Request Body

(none)

Response Body

{
    "results": [
        {
            "id": "4f7ceb38-5093-437b-883b-ba96c413c4d7",
            "name": "ExamplePodAdServer",
            "baseUrl": "http://adpod.adprovider.com/adpath/ads?sz=640x480&impl=s&gdfp_req=1&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
        },
        {
            "id": "799c9ffa-78cc-4fc5-81ca-39297734ef2d",
            "name": "ExampleVASTAdServer",
            "baseUrl": "http://ads.vastadserver.com/path/ads?dur=15",
            "domainId": "1234abcd-1234-abcd-56ef-098765fedcba"
        }
    ],
    "prev": null,
    "next": null,
    "totalResults": 2
}

Response Fields

Field Type Description
results Object[] Array of adServers in result set
  id String Each adServerId
  name String Each adServer's name
  baseUrl String Each adServer's base URL
  domainId String Each adServer's parent domainId
prev URL URL to GET the previous adServer result set (if necessary)
next URL URL to GET the next adServer result set (if necessary)
totalResults URL The total number of adServer in the domain

Get Ad Decisioning Server Details

Retrieves details of a specified adServer.

GET https://api.unicornmedia.com/media-management-api/domains/{domainId}/adServers/{adServerId}

Request Body

(none)

Response Body

{
    "id": "4f7ceb38-5093-437b-883b-ba96c413c4d7",
    "name": "ExamplePodAdServer",
    "baseUrl": "http://adpod.adprovider.com/adpath/ads?sz=640x480&impl=s&gdfp_req=1&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "variables": {
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params",
        "cachebuster": "{{randomnumber32}}",
        "url": "{{referringURL}}",
    }
}

Response Fields

Field Type Description
id String Each adServerId
name String Each adServer's name
baseUrl String Each adServer's base URL
domainId String Each adServer's parent domainId
variables Object An object set of query string key/value pairs which will be inserted/appended to the base URL at request time

Create Ad Decisioning Server

Create an adServer, defining the base URL and query string variables that will be fired to your ad provider for a single VAST ad or DFP/SmartXML ad playlist response. Please see our guide for Converting an ad tag for the Once Media Management API.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/adServers

Request Body

{
    "name": "Documentation adServer Example",
    "baseUrl": "http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "variables": {
        "url": "{{referringURL}}",
        "cachebuster": "{{randomnumber32}}",
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params"
    }
}

Request Fields

Field Type Required? Description
name String Yes The new adServer’s name
baseUrl String Yes The new adServer’s base URL
variables Object Yes, see Description An object set of query string key/value pairs to be inserted/appended to the base URL at request time.

If your base URL requires no variables, include an empty variables object ("variables": {})

Response Body

{
    "id": "c06cb299-776d-47d1-9940-7d08f1ffcbe7",
    "name": "Documentation adServer Example",
    "baseUrl": "http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "variables": {
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "url": "{{referringURL}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params",
        "cachebuster": "{{randomnumber32}}"
    }
}

Response Fields

Field Type Description
id String Each adServerId
name String Each adServer's name
baseUrl String Each adServer's base URL
domainId String Each adServer's parent domainId
variables Object An object set of query string key/value pairs which will be inserted/appended to the base URL at request time

Response variable order may not match your original input, this is expected and will not affect ad tag performance.

Update Ad Decisioning Server

Update the specified adServer’s name, base URL, and/or variables. NOTE: This change will affect any application adConfigs utilizing the updated adServer.

If you need an updated adServer configuration without changing existing applications or ad configurations, create a new adServer and then create or modify applications and their adConfigs to use the new adServer.

POST https://api.unicornmedia.com/media-management-api/domains/{domainId}/adServers/{adServerId}

Request Body

{
    "name": "Documentation Updated adServer Example",
    "baseUrl": "http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "variables": {
        "url": "{{referringURL}}",
        "cachebuster": "{{randomnumber32}}",
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params"
    }
}

Request Fields

Field Type Required? Description
name String Yes The new adServer’s name
baseUrl String Yes The new adServer’s base URL
variables Object Yes, see description An object set of query string key/value pairs to be inserted/appended to the base URL at request time.

If your base URL requires no variables, include an empty variables object ("variables": {})

Response Body

{
    "id": "c06cb299-776d-47d1-9940-7d08f1ffcbe7",
    "name": "Documentation Updated adServer Example",
    "baseUrl": "http://adserver.adprovider.com/adpath/ads?sz=640x480&impl=s&env=vp&output=xml_vast2&{{ph01}}&{{ph02}}&unviewed_position_start=1&ad_rule=1&nofb=1&ss_req=1",
    "domainId": "1234abcd-1234-abcd-56ef-098765fedcba",
    "variables": {
        "{{ph01}} vid": "{{mediaitem.foreignkey}}",
        "url": "{{referringURL}}",
        "{{ph02}} ip": "{{ipaddress}}",
        "UMADPARAM": "UMADPARAMiu",
        "UMPTPARAM": "UMPTPARAMcust_params",
        "cachebuster": "{{randomnumber32}}"
    }
}

Response Fields

Field Type Description
id String Each adServerId
name String Each adServer's name
baseUrl String Each adServer's base URL
domainId String Each adServer's parent domainId
variables Object An object set of query string key/value pairs which will be inserted/appended to the base URL at request time

Response variable order may not match your original input, this is expected and will not affect ad tag performance.

Delete Ad Decisioning Server

Deletes the specified ad decisioning server. NOTE: This change will remove any application adConfigs utilizing the deleted adServer.

DELETE https://api.unicornmedia.com/media-management-api/domains/{domainId}/adServers/{adServerId}

Request Body

(none)

Response Body

{
    "id": "c06cb299-776d-47d1-9940-7d08f1ffcbe7"
}

Response Fields

Field Type Description
id String The adServerId which has been deleted

URL Parameters

The URL parameters below can be used to sort and page results for the following requests.

Parameter Type Description
pageSize optional

Number(1-100)

The number of items to return for the request

page optional

Number

The set of items (based on pageSize) to return

Default value: 0

name optional

String

Filter to applications that have name substring. E.g. name=foo could return applications named "foo", "foobar", "foorific"

sortField optional

String

Filter to applications that have name substring. E.g. name=foo could return applications named "foo", "foobar", "foorific"

Default value: updatedate

Allowed values: "name", "createdate", "updatedate"

sortDirection optional

String

Sort ascending or descending.

Default value: desc

Allowed values: "asc", "desc"