NAV Navbar
Examples Go Javascript

Introduction

██████╗ ███████╗██╗  ██╗
██╔══██╗██╔════╝╚██╗██╔╝
██████╔╝█████╗   ╚███╔╝ 
██╔═══╝ ██╔══╝   ██╔██╗ 
██║     ███████╗██╔╝ ██╗
╚═╝     ╚══════╝╚═╝  ╚═╝

Welcome to the Pex Discovery API documentation.

This API allows Pex data to be created, retrieved, updated and deleted using requests with token-based authetication and JSON format using standard HTTP verbs.

There are five main paths:

Endpoint Path
asset /v3/cms/assets
asset_v4 /v4/cms/assets
collection /v3/cms/collections
whitelist /v3/cms/whitelists
copy /v3/drm/copies

Sample JSON request input and response output have been provided for each endpoint below.

The rate of calls to the API must not exceed 16 per second.

Authentication

Pex API keys

# HTTP calls should always have the authorization header
curl "api endpoint here"
  -H "Authorization: Bearer YWxhZGRpbjpvcGVuc2VzYW1l"

API keys can be created using the API key page in your Pex settings

Pex expects the API key to be included in all API requests to the server in a header that looks like the following:

"Authorization: Bearer YWxhZGRpbjpvcGVuc2VzYW1l"

Assets

Get all assets

# List two failed assets with ID lower than 1234567890123456789
# GET /v3/cms/assets?count=2&max_id=1234567890123456789&status=failed
[
   {
      "asset_id":1234567890123456788,
      "asset_id_str":"1234567890123456788",
      "title":"example #1",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "updated_at":"2014-02-14T00:00:00.000000Z",
      "production_date":"2014-02-14T00:00:00Z",
      "collection_ids":[
         0
      ],
      "is_tracked":true,
      "tracked_from":"2014-02-14T00:00:00.000000Z",
      "processing_status": "failed"
   },
   {
      "asset_id":1234567890123456787,
      "asset_id_str":"1234567890123456788",
      "title":"example #2",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "updated_at":"2014-02-14T00:00:00.000000Z",
      "production_date":"2014-02-14T00:00:00Z",
      "collection_ids":[
         0
      ],
      "is_tracked":false,
      "tracked_from":"2014-02-14T00:00:00.000000Z",
      "processing_status": "failed"
   },
   "excluded_segments": [
        {
            "lower":0,
            "upper":15
        },
        {
            "lower":20,
            "upper":25
        }
    ]
]

Description: Lists all assets within given parameters. Assets returned will be in listed in descending order by ID ( the newest assets wil be listed first).

HTTP Request

GET /v3/cms/assets?count={count}&max_id={max_id}&min_id={min_id}&status={status}&is_tracked={tracking_status}&isrc={isrc_1}&isrc={isrc_2}

Query Parameters

Name Description
count
integer
number of assets to list (default: 100)
max_id
integer
highest ID that can be returned (exclusive)
min_id
integer
lowest ID that can be returned (inclusive)
status
string
processing status of the asset (failed, uploaded, or sampled)
is_tracked
string
tracking status, either true or false (any other value will exclude the parameter)
isrc
string
ISRC value(s), can be concatenated to match more than one value simultaneously (accepts alphanumeric values only, any other will be excluded from search). If multiple ISRCs are provided, the search will return assets that match any (OR logic) of the given ISRCs.

Response Fields

Name Description
updated_at
string
timestamp when the asset was last updated
tracked_from
string
timestamp when the asset tracking status was set to true (empty if not tracked)
title
string
title of the asset
production_date
string
string representing the production date (YYYY-MM-DD)
is_tracked
boolean
tracking status
created_at
string
timestamp when the asset was created
collection_ids
integer[]
list of collections IDs
asset_id_str
string
string representation of the asset ID
asset_id
integer
asset ID (signed 64 bit integer)
excluded_segments
object[]
range in seconds of excluded segments from an asset

Create an asset (via upload)

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "os"
)

// genfid is a function that creates a file ID by hashing
// the first 512KB of a file on disk
func genfid(pathtofile string) (string, error) {
    // read the file from path, and handle error if any
    f, err := os.Open(pathtofile)
    if err != nil {
        return "", err
    }
    defer f.Close()

    // create a buffer to hold the first 512KB of data
    buff := make([]byte, 512*1024)
    if _, err := io.ReadFull(f, buff[:]); err != nil {
        return "", err
    }

    // create a hasher to create the file ID
    hash := sha256.Sum256(buff)

    fid := hex.EncodeToString(hash[:])

    return fid, nil
}


func main() {
    filename := "path/to/local-file.mp3"
    fid, err := genfid(filename)
    if err != nil {
        // handle error
        panic(err)
    }
    fmt.Println(fid)
}
// Example Javascript FID generation
function generateFID(file) {
   return new Promise((resolve, reject) => {
      const blob = file.slice(0, 512 * 1024)
      const reader = new FileReader()
      if (typeof reader.readAsBinaryString !== 'function') {
         resolve(null)
      }
      reader.onloadend = (e: any) => {
         if (e.target.readyState === FileReader.DONE) {
            resolve(window.forge_sha256(e.target.result))
         }
      }
      reader.onerror = reject
      reader.readAsBinaryString(blob)
   })
}
# (v3/v4) STEP 2 - Sample JSON request body metatada for 
# uploading a mpeg file asset
{
   "title":"example",
   "production_date":"2014-02-14",
   "media_type": "video",
   "match_types": ["audio", "video"],
   "mime_type":"video/mpeg",
   # see Step 1 in description
   "fid":"6a3facd53527bcf1fb787fa1b550bea5580a827a89d6a88325bcd7a919b111e4",
   "collection_ids":[
      0
   ],
   "reference_ids":[
      "example"
   ],
   "music":{
      "iswcs":[
         "example"
      ],
      "isrcs":[
         "example"
      ],
      "artist":"artist",
      "album":"album"
   },
   "youtube_content_id":{
      "asset_id":"example"
   }
}

# (v3) Step 2 - Sample Response
{
    "asset_id": 5415322847017312256,
    "asset_id_str": "5415322847017312256",
    "file_url": "https://api.pex.com/int/file-upload/db9435c1-42b4-4093-841b-8c91f1cd9019?token=3235363735363738392d61343965313636363164613864373032333966356130373666386639626535322d37323030"
}

# (v4) Step 2 - Sample Response
{
    "asset_id": 5413324158216313856,
    "asset_id_str": "5413324158216313856",
    "blob_id": "ddc254ba-0beb-41c8-8262-64bd57c57173"
}

# (v3) Step 3  - Example Upload Using cURL
curl -v -X PUT -H "Content-Type: video/mpeg" \
   --data-binary "@file.mpeg" \
   "https://api.pex.com/int/file-upload/db9435c1-42b4-4093-841b-8c91f1cd9019?token=3235363735363738392d61343965313636363164613864373032333966356130373666386639626535322d37323030"

Description: There are two endpoints. For assets < 2 GB use the v3 endpoint instructions, otherwise use the v4 endpoint ones. You will POST the metadata to us first in both cases.

HTTP Request:

v3 Upload Instructions:
1. Generate a file ID (FID) for your asset by applying a SHA256 hash to the first 512kb of data in your file. Please refer to the examples provided in the Go or Javascript examples in tabs on the right.

2. Create and send a request to the upload endpoint /v3/cms/assets/upload with a JSON body containing metadata related to the file (this does not upload the asset). A file URL will be provided in the response. This URL leads to an Azure Blob Storage bucket corresponding to the location of your future file upload.

3. Upload the file using a PUT request to the file URL provided in the response from Step 2. The body of the PUT request is the binary content of the file you would like to upload. The MIME type from Step 2 should be added as a header of the PUT request under the key Content-Type, e.g. "Content-Type: audio/mp3"

4. Use the verify endpoint to check that your file has successfully uploaded.

v4 Upload Instructions:
1. Generate a file ID (FID) for your asset by applying a SHA256 hash to the first 512kb of data in your file. Please refer to the examples provided in the Go or Javascript examples in tabs on the right.

2. Create and send a request to the v4 upload endpoint /v4/cms/assets/upload with a JSON body containing metadata related to the file (this does not upload the asset). An asset_id and blob_id will be returned. Make sure you do not lose these values. Copy them.

3. Use a tus client to upload the file to this endpoint /v4/cms/assets/file-upload/. You must attach two headers: your Authorization header, and a Blob-ID header.

Officially supported clients are found here:

You can read about other clients here: https://tus.io/implementations.html

Pex expects the Authorization and Blob-ID header to be included in all API requests to this endpoint in the format shown below.

'Authorization: Bearer YWxhZGRpbjpvcGVuc2VzYW1l'
'Blob-ID: "ddc254ba-0beb-41c8-8262-64bd57c57173"'

Replace YWxhZGRpbjpvcGVuc2VzYW1l with your personal API key.
Replace ddc254ba-0beb-41c8-8262-64bd57c57173 with your personal Blob-ID

4. Use the verify endpoint to check that your file has successfully uploaded. The v3 endpoint is still used for verification.

Body Parameters

Name Description
title
string, required
title of the asset
media_type
string, required
media type (audio, video, or audiovisual)
match_types
string[]
match types the asset should generate (audio, video)
mime_type
string, required
MIME type (video/mpeg, audio/mp3, etc.)
fid
string, required
SHA256 hash of the first 512kb of data in your file
production_date
string, required
string representing the production date (YYYY-MM-DD)
collection_ids
integer[]
list of collections IDs
reference_ids
string[]
list of reference IDs
music
object
music metadata
music.iswcs
string[]
list of iswcs
music.isrcs
string[]
list of isrcs
music.artist
string
artist
music.album
string
album
youtube_content_id
object
youtube content ID metadata
youtube_content_id.asset_id
string
ID of content ID asset

v3 Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
file_url
string
URL location of the uploaded asset file

v4 Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
blob_id
string
used to identify your file during upload

Verify an asset

# Sample response - uploaded
{
   "asset_id": 1234567890123456789,
   "asset_id_str": "1234567890123456789",
   "uploaded": true
}

# Sample response - not uploaded
{
   "asset_id": 5254502778690505216,
   "asset_id_str": "5254502778690505216",
   "uploaded": false
}

Description: Verifies if an asset has been successfully uploaded, this also works for assets uploaded through the v4 end point.

HTTP Request

GET /v3/cms/assets/{asset_id}/verify

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
uploaded
boolean
true if upload was successful
# Create an asset to track the Youtube video for Despacito
{
   "link":"https://www.youtube.com/watch?v=kJQP7kiw5Fk",
   "media_type" : "audiovisual",
   "match_types": ["audio", "video"],
   "collection_ids":[
      0
   ],
   "reference_ids":[
      "ref-example-123"
   ],
   "production_date":"2017-01-12"
}

# Sample response
{  
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789"
}

Description: Creates an asset from a supported link.

Supported platforms:

HTTP Request

POST /v3/cms/assets/link

Body Parameters

Name Description
link
string, required
url used to create the asset
media_type
string, required
media type (audio, video, or audiovisual)
match_types
string[]
match types the asset should generate (audio, video)
collection_ids
integer[]
list of collections ids
reference_ids
string[]
list of reference ids
production_date
string
string representing the production date (YYYY-MM-DD)

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID

Get an asset

# Retrieve the asset we created with the Youtube video for Despacito
# GET /cms/assets/1234567890123456789
{  
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789",
   "reference_ids":[  
      "example"
   ],
   "title":"Luis Fonsi - Despacito ft. Daddy Yankee",
   "created_at":"2014-02-14T00:00:00.000000Z",
   "updated_at":"2014-02-14T00:00:00.000000Z",
   "production_date":"2017-01-12T21:00:02Z",
   "collection_ids":[  
      0
   ],
   "is_tracked":true,
   "tracked_from":"2014-02-14T00:00:00.000000Z",
   "media_type" : "video",
   "match_types":["video"],
   "thumbnail_url":"https://pexpdrmthumbnails.blob.core.windows.net/images-na/example.jpg",
   "duration":100,
   "processing_status":{  
      "status":"",
      "error":""
   },
   "youtube_content_id":{  
      "cid_asset_id":"example",
   },
   "music":{  
      "isrcs":"example",
      "iswcs":"example",
      "album":"example",
      "artist":"example"
   },
   "excluded_segments": [
        {
            "lower":0,
            "upper":15
        },
        {
            "lower":20,
            "upper":25
        }
    ]
}

Description: Retrieves data for a specified asset.

HTTP Request

GET /v3/cms/assets/{asset_id}

Path Parameters

Name Description
asset_id
string, required
asset ID

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
is_tracked
boolean
tracking status
media_type
string
media type (audio, video, or audiovisual)
tracked_from
string
timestamp when the asset tracking status was set to true (empty if not tracked)
match_types
string[]
match types the asset generates (audio, video)
created_at
string
timestamp when the asset was created
updated_at
string
timestamp when the asset was last updated
production_date
string
string representing the production date (YYYY-MM-DD)
title
string
title of the asset
collection_ids
integer[]
list of collections IDs
reference_ids
string[]
list of reference IDs
duration
integer
duration of the asset (second)
processing_status
object
processing status metadata
processing_status.status
string
processing status
processing_status.error
string
error associated with the processing status
youtube_content_id
object
youtube content ID metadata
youtube_content_id.asset_id
string
ID of content ID asset
music
object
music metadata
music.iswcs
string[]
list of iswcs
music.isrcs
string[]
list of isrcs
music.artist
string
artist
music.album
string
album
excluded_segments
object[]
range in seconds of excluded segments from an asset

Update an asset

# Update an asset with the following properties
{
   "reference_ids":[
      "example"
   ],
   "title":"update example",
   "production_date":"2000-01-01",
   "collection_ids":[
      0
   ],
   "media_type" : "audiovisual",
   "match_types": ["audio", "video"],
   "youtube_content_id":{
      "asset_id":"example"
   },
   "music":{
      "album":"album",
      "artist":"artist",
      "isrcs":[
         "example"
      ],
      "iswcs":[
         "example"
      ]
   },
   "excluded_segments": [
        {
            "lower":0,
            "upper":15
        },
        {
            "lower":20,
            "upper":25
        }
    ]
}

# Sample response
{  
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789"
}

Description: Updates data for a specified asset.

HTTP Request

PUT /v3/cms/assets/{asset_id}

Path Parameters

Name Description
asset_id
string, required
asset ID

Body Parameters

Name Description
title
string, required
title of the asset
collection_ids
integer[]
list of collections IDs
reference_ids
string[]
list of reference IDs
production_date
string
string representing the production date (YYYY-MM-DD)
youtube_content_id
object
youtube content ID metadata
youtube_content_id.asset_id
string
ID of content ID asset
music
object
music metadata
music.iswcs
string[]
list of iswcs
music.isrcs
string[]
list of isrcs
music.artist
string
artist
music.album
string
album
match_types
string[]
match types the asset should generate (audio, video)
excluded_segments
object[]
range in seconds of excluded segments from an asset

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID

Patch an asset

# Update an asset with any of the following properties
{
   "reference_ids":[
      "example"
   ],
   "title":"update example",
   "production_date":"2000-01-01",
   "collection_ids":[
      0
   ],
   "media_type" : "audiovisual",
   "match_types": ["audio", "video"],
   "youtube_content_id":{
      "asset_id":"example"
   },
   "music":{
      "album":"album",
      "artist":"artist",
      "isrcs":[
         "example"
      ],
      "iswcs":[
         "example"
      ]
   }
   "excluded_segments": [
        {
            "lower":0,
            "upper":15
        },
        {
            "lower":20,
            "upper":25
        }
    ]
}

# Sample response
{  
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789"
}

Description: Update specific fields for a given asset.

HTTP Request

PATCH /v3/cms/assets/{asset_id}

Path Parameters

Name Description
asset_id
string, required
asset ID

Body Parameters

Name Description
title
string
title of the asset
collection_ids
integer[]
list of collections IDs
reference_ids
string[]
list of reference IDs
production_date
string
string representing the production date (YYYY-MM-DD)
youtube_content_id
object
youtube content ID metadata
youtube_content_id.asset_id
string
ID of content ID asset
music
object
music metadata
music.iswcs
string[]
list of iswcs
music.isrcs
string[]
list of isrcs
music.artist
string
artist
music.album
string
album
match_types
string[]
match types the asset should generate (audio, video)
excluded_segments
object[]
range in seconds of excluded segments from an asset

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID

Delete an asset

# DELETE /cms/assets/1234567890123456789
# Sample response
{  
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789"
}

Description: Deletes a specified asset.

HTTP Request

DELETE /v3/cms/assets/{asset_id}

Path Parameters

Name Description
asset_id
string, required
asset ID

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID

Get tracking status

# GET /cms/assets/1234567890123456789/track
# Sample response
{
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789",
   "is_tracked":true,
   "tracked_from":"2014-02-14T00:00:00.000000Z",
}

Description: Gets the tracking status for a specified asset.

HTTP Request

GET /v3/cms/assets/{asset_id}/track

Path Parameters

Name Description
asset_id
string, required
asset ID

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
is_tracked
boolean
tracking status
tracked_from
string
timestamp when the asset tracking status was set to true (empty if not tracked)

Update tracking status

# Remove tracking for asset 1234567890123456789
# PUT /cms/assets/1234567890123456789/track
{
   "is_tracked":false
}

# Sample response
{  
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789"
}

Description: Modifies the tracking status for a specified asset.

HTTP Request

PUT /v3/cms/assets/{asset_id}/track

Path Parameters

Name Description
asset_id
string, required
asset ID

Body Parameters

Name Description
is_tracked
string, required
tracking status

Response Fields

Name Description
asset_id
integer
asset ID (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID

Collections

Get all collections

# List two collections with ID lower than 1234567890123456789
# GET /cms/collections?count=2&max_id=1234567890123456789
[
   {
      "collection_id":1234567890123456788,
      "collection_id_str":"1234567890123456788",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "updated_at":"2014-02-14T00:00:00.000000Z",
      "reference_id":"example",
      "title":"example #1",
      "is_autocollection":true
   },
   {
      "collection_id":1234567890123456789,
      "collection_id_str":"1234567890123456789",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "updated_at":"2014-02-14T00:00:00.000000Z",
      "reference_id":"example",
      "title":"example #2",
      "is_autocollection":false
   }
]

Description: Lists all collections within given parameters. Collections returned will be in listed in descending order by ID (the newest collections wil be listed first).

HTTP Request

GET /v3/cms/collections?count={count}&max_id={max_id}&min_id={min_id}

Query Parameters

Name Description
count
integer
number of assets to list (default: 100)
max_id
integer
highest ID that can be returned (exclusive)
min_id
integer
lowest ID that can be returned (exclusive)

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID
created_at
string
timestamp when the collection was created
updated_at
string
timestamp when the collection was last updated
title
string
title of the collection
reference_id
string
list of reference IDs
is_autocollection
boolean
is the collection automated

Create a collection

# Create a collection with the follwing properties
{
   "title":"example",
   "reference_id":"example"
}

# Sample response
{  
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789"
}

Description: Creates a manual or automated collection.

HTTP Request

POST /v3/cms/collections

Body Parameters

Name Description
title
string
title of the colllection
reference_id
string
reference ID

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID

Get a collection

{
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789",
   "created_at":"2014-02-14T00:00:00.000000Z",
   "updated_at":"2014-02-14T00:00:00.000000Z",
   "reference_id":"example",
   "title":"example",
   "assets_count":0,
   "is_autocollection":false
}

Description: Retrieves data for a specified collection.

HTTP Request

GET /v3/cms/collections/{collection_id}

Path Parameters

Name Description
collection_id
string, required
collection ID

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID
created_at
string
timestamp when the collection was created
updated_at
string
timestamp when the collection was last updated
title
string
title of the collection
reference_id
string
list of reference IDs
is_autocollection
boolean
is the collection automated

Update a collection

# Update a collection with the following properties
{
   "title":"example",
   "reference_id":"example"
}

# Sample response
{  
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789"
}

Description: Modifies the specified collection.

HTTP Request

PUT /v3/cms/collections/{collection_id}

Path Parameters

Name Description
collection_id
string, required
collection ID

Body Parameters

Name Description
title
string
title of the colllection
reference_id
string
reference ID

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID

Delete a collection

# DELETE /cms/collections/1234567890123456789
# Sample response
{  
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789"
}

Attempting to delete an auto collection using this endpoint will result in a 405 (method not allowed) response. Please use the auto collection endpoint (see below)

Description: Deletes a specified collection. All assets within collection are automatically moved to the default collection. Auto collections can't be removed through this function.

HTTP Request

DELETE /v3/cms/collections/{collection_id}

Path Parameters

Name Description
collection_id
string, required
collection ID

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID

Create an auto collection

# Create an auto collection with the following link
{  
   "title":"example",
   "source_url":"https://www.youtube.com/watch?v=MXgnIP4rMoI",
   "is_active":true
}

# Sample response
{  
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789"
}

Description: Creates an auto collection from a source URL.

HTTP Request

POST /v3/cms/collections/auto

Body Parameters

Name Description
title
string
title of the colllection
source_url
string
URL used to create the collection
is_active
boolean
collection status

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID

Get an auto collection

# Retrieve information about collection 1234567890123456789
{
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789",
   "created_at":"2014-02-14T00:00:00.000000Z",
   "updated_at":"2014-02-14T00:00:00.000000Z",
   "source_url":"https://www.youtube.com/watch?v=MXgnIP4rMoI",
   "title":"example",
   "assets_count":0,
   "is_active":true
}

Description: Retrieves data for a specified auto collection.

HTTP Request

GET /v3/cms/collections/auto/{collection_id}

Path Parameters

Name Description
collection_id
string, required
collection ID

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID
created_at
string
timestamp when the collection was created
updated_at
string
timestamp when the collection was last updated
title
string
title of the collection
is_active
string
collection status
source_url
string
URL used to create the collection
assets_count
integer
number of assets in the collection

Update an auto collection

# Toggle the state of collection 1234567890123456789
# PUT /cms/collections/auto/1234567890123456789
{
   "is_active":false
}

# Sample response
{  
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789"
}

Description: Changes the state of an auto collection

HTTP Request

PUT /v3/cms/collections/auto/{collection_id}

Path Parameters

Name Description
collection_id
string, required
collection ID

Body Parameters

Name Description
is_active
boolean
collection status

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID

Delete an auto collection

# DELETE /cms/collections/auto/1234567890123456789
# Sample response
{  
   "collection_id":1234567890123456789,
   "collection_id_str":"1234567890123456789"
}

Description: Deletes a specified auto collection. All assets are automatically removed.

HTTP Request

DELETE /v3/cms/collections/auto/{collection_id}

Path Parameters

Name Description
collection_id
string, required
collection ID

Response Fields

Name Description
collection_id
integer
collection ID (signed 64 bit integer)
collection_id_str
string
string representation of the collection ID

Whitelists

Get all whitelists

# List two whitelists with ID lower than 1234567890123456789
# GET /cms/whitelists?count=2&max_id=1234567890123456789
[
   {
      "whitelist_id":1234567890123456788,
      "whitelist_id_str":"123456789012345678",
      "title":"example #1",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "updated_at":"2014-02-14T00:00:00.000000Z",
      "dates_limit":{
         "start_date":"2014-02-14",
         "end_date":"2114-02-14",
      }
   },
   {
      "whitelist_id":1234567890123456789,
      "whitelist_id_str":"1234567890123456789",
      "title":"example #2",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "updated_at":"2014-02-14T00:00:00.000000Z",
      "dates_limit":{
         "start_date":"-infinity",
         "end_date":"infinity"
      }
   }
]

Description: Lists all whitelists within given parameters. Whitelists returned will be in listed in descending order by ID (the newest whitelists wil be listed first).

HTTP Request

GET /v3/cms/whitelists?count={count}&max_id={max_id}&min_id={min_id}

Query Parameters

Name Description
count
integer
number of whitelists to list (default: 100)
max_id
integer
highest ID that can be returned (exclusive)
min_id
integer
lowest ID that can be returned (exclusive)

Response Fields

Name Description
whitelist_id
integer
whitelist ID (signed 64 bit integer)
whitelist_id_str
string
string representation of the collection ID
title
string
whitelist title
created_at
string
timestamp when the whitelist was created
updated_at
string
timestamp when the whitelist was last updated
dates_limit
object
information about when the whitelist is active
dates_limit.start_date
string
timestamp representing when the whitelist starts to be active (YYYY-MM-DD)
dates_limit.end_date
string
timestamp representing when the whitelist stops being active (YYYY-MM-DD)

Create a whitelist

# Create a new whitelist with the following properties
{
   "title":"example",
   "dates_limit":{
      "start_date":"2014-02-14",
      "end_date":"2114-02-14"
   }
}

# Sample response
{  
   "whitelist_id":1234567890123456789,
   "whitelist_id_str":"1234567890123456789"
}

Description: Creates a new whitelist

HTTP Request

POST /v3/cms/whitelists

Body Parameters

Name Description
title
string
title of the whitelist
dates_limit
object
information about when the whitelist is active
dates_limit.start_date
string, required
timestamp representing when the whitelist starts to be active (YYYY-MM-DD)
dates_limit.end_date
string, required
timestamp representing when the whitelist stops being active (YYYY-MM-DD)

Response Fields

Name Description
whitelist_id
integer
whitelist ID (signed 64 bit integer)
whitelist_id_str
string
string representation of the whitelist ID

Get a whitelist

{
   "whitelist_id":1234567890123456789,
   "whitelist_id_str":"1234567890123456789",
   "title":"example",
   "created_at":"2014-02-14T00:00:00.000000Z",
   "updated_at":"2014-02-14T00:00:00.000000Z",
   "url_stats":{
      "failed":0,
      "succeed":0
   },
   "dates_limit":{
      "start_date":"2014-02-14",
      "end_date":"2114-02-14"
   }
}

Description: Retrieves data for a specified whitelist.

HTTP Request

GET /v3/cms/whitelists/{whitelist_id}

Path Parameters

Name Description
whitelist_id
string, required
whitelist ID

Response Fields

Name Description
whitelist_id
integer, required
whitelist ID (signed 64 bit integer)
whitelist_id_str
string, required
string representation of the collection ID
title
string, required
whitelist title
created_at
string, required
timestamp when the whitelist was created
updated_at
string
timestamp when the whitelist was last updated
url_stats
object
information the URLs in the whitelist
url_stats.failed
integer, required
amount of URLs in the whitelist that have errors
url_stats.succeed
string, required
amount of URLs in the whitelist that were successfully processed
dates_limit
object
information about when the whitelist is active
dates_limit.start_date
string, required
timestamp representing when the whitelist starts to be active (YYYY-MM-DD)
dates_limit.end_date
string, required
timestamp representing when the whitelist stops being active (YYYY-MM-DD)

Delete a whitelist

# DELETE /cms/whitelists/1234567890123456789
# Sample response
{  
   "whitelist_id":1234567890123456789,
   "whitelist_id_str":"1234567890123456789"
}

Description: Deletes a specified whitelist and all URLs associated with it

HTTP Request

DELETE /v3/cms/whitelists/{whitelist_id}

Path Parameters

Name Description
whitelist_id
string, required
whitelist ID

Response Fields

Name Description
whitelist_id
integer
whitelist ID (signed 64 bit integer)
whitelist_id_str
string
string representation of the whitelist ID

Get all whitelist URLs

# List two URLs with ID lower than 1234567890123456789
# GET /cms/whitelists/urls?count=2&max_id=1234567890123456789
[
   {
      "url_id":1234567890123456788,
      "url_id_str":"1234567890123456788",
      "source_url":"https://www.youtube.com/user/example",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "processing_status":{
         "status":"ok",
         "error":""
      }
   },
   {
      "url_id":1234567890123456789,
      "url_id_str":"1234567890123456789",
      "source_url":"https://www.youtube.com/channel/example",
      "created_at":"2014-02-14T00:00:00.000000Z",
      "processing_status":{
         "status":"ok",
         "error":""
      }
   }
]

Description: Gets list of all URLs within whitelist. Whitelist URLs returned will be in listed in descending order by ID (the newest whitelist URLs wil be listed first).

HTTP Request

GET /v3/cms/whitelists/{whitelist_id}/urls?count={count}&max_id={max_id}

Path Parameters

Name Description
whitelist_id
string, required
whitelist ID

Query Parameters

Name Description
count
integer
number of whitelists to list (default: 100)
max_id
integer
highest ID that can be returned (exclusive)
min_id
integer
lowest ID that can be returned (exclusive)

Response Fields

Name Description
whitelist_id
integer
whitelist ID (signed 64 bit integer)
whitelist_id_str
string
string representation of the collection ID
source_url
string
URL
created_at
string
timestamp when the whitelist was created
processing_status
object
processing status metadata
processing_status.status
string
processing status
processing_status.error
string
error associated with the processing status

Add a whitelist url

# Add a URL to whitelist
{
   "source_url":"https://www.youtube.com/user/example"
}

# Sample response
{  
   "url_id":1234567890123456789,
   "url_id_str":"1234567890123456789"
}

Description: Inserts a new URL into the specified whitelist.

HTTP Request

POST /v3/cms/whitelists/{whitelist_id}/urls

Path Parameters

Name Description
whitelist_id
string, required
whitelist ID

Get a whitelist url

# Retrieve details about the URL 1234567890123456789
{
    "url_id": 1623578019101113334,
    "url_id_str": "1623578019101113334",
    "source_url": "https://www.youtube.com/user/example",
    "created_at": "2014-02-14T00:00:00.000000Z",
    "processing_status": {
        "status": "ok",
        "error": ""
    }
}

Description: Retrieves data for a specified URL in a whitelist.

HTTP Request

GET /v3/cms/whitelists/{whitelist_id}/urls/{url_id}

Path Parameters

Name Description
whitelist_id
string, required
whitelist ID
url_id
string, required
URL ID

Response Fields

Name Description
url_id
integer
URL ID (signed 64 bit integer)
url_id_str
string
string representation of the URL ID
source_url
string
URL
processing_status
object
processing status metadata
processing_status.status
string
processing status
processing_status.error
string
error associated with the processing status

Delete a whitelist url

# DELETE /cms/whitelists/1234567890123456789/urls/1234567890123456789
# Sample response
{  
   "url_id":1234567890123456789,
   "url_id_str":"1234567890123456789"
}

Description: Removes the specified URL from a whitelist.

HTTP Request

DELETE /v3/cms/whitelists/{whitelist_id}/urls/{url_id}

Path Parameters

Name Description
whitelist_id
string, required
whitelist ID
url_id
string, required
URL ID

Response Fields

Name Description
url_id
integer
URL ID (signed 64 bit integer)
url_id_str
string
string representation of the URL ID

Copies

Get all copies

# List two copies with ID lower than 1234567890123456789
# GET /drm/copies?count=2&max_id=1234567890123456789&platform=example&is_taken_down=true&collection=0&isrc=example
[
   {
      "match_id":1234567890123456788,
      "match_id_str":"1234567890123456788",
      "asset_id":1234567890123456789,
      "asset_id_str":"1234567890123456789",
      "whitelist_ids":[
         1234567890123456789
      ],
      "whitelist_ids_str":[
         "1234567890123456789"
      ],
      "created_at":"2014-02-14T00:00:00.000000Z",
      "platform":"example",
      "copy_media_url":"example",
      "copy_user_url":"example",
      "copy_user_name":"example",
      "copy_user_real_name":"Example",
      "copy_user_is_verified":false,
      "copy_title":"Title Example",
      "copy_upload_date":"2014-02-14T00:00:00.000000Z",
      "copy_duration":15,
      "copy_sound_id": null,
      "copy_statistics":{
         "views_count":0,
         "shares_count":0,
         "comments_count":0,
         "likes_count":0,
         "dislike_count":0
      },
      "match_data":{
         "matching_segments_in_asset":[],
         "matching_segments_in_copy":[],
         "copy_percentage_asset":0,
         "copy_percentage_copy":0,
         "length_of_match":0,
         "is_audio_modified":false
      },
      "match_category":"SN30",
      "user_actions":{
         "statuses":[
            10,
            11
         ]
      }
      "is_nsfw": true,
      "is_taken_down": true
   },
   {
      "match_id":1234567890123456789,
      "match_id_str":"1234567890123456789",
      "asset_id":1234567890123456789,
      "asset_id_str":"1234567890123456789",
      "whitelist_ids":[
         1234567890123456789
      ],
      "whitelist_ids_str":[
         "1234567890123456789"
      ],
      "created_at":"2014-02-14T00:00:00.000000Z",
      "platform":"example",
      "copy_media_url":"example",
      "copy_user_url":"example",
      "copy_user_name":"example",
      "copy_user_real_name":"Example",
      "copy_user_is_verified":true,
      "copy_title":"Title Example",
      "copy_upload_date":"2014-02-14T00:00:00.000000Z",
      "copy_duration":15,
      "copy_sound_id": "2570399001262912",
      "copy_statistics":{
         "views_count":0,
         "shares_count":0,
         "comments_count":0,
         "likes_count":0,
         "dislike_count":0
      },
      "match_data":{
         "matching_segments_in_asset":[],
         "matching_segments_in_copy":[],
         "copy_percentage_asset":0,
         "copy_percentage_copy":0,
         "length_of_match":0,
         "is_audio_modified":false
      },
      "match_category":"SN30",
      "user_actions":{
         "statuses":[
            10,
            60
         ]
      }
      "is_nsfw": true,
      "is_taken_down": true,
      "content_type": "audio"
   }
]

Description: Lists all copies within given parameters. Copies returned will be in listed in descending order by ID ( the newest copies wil be listed first).

HTTP Request

GET /v3/drm/copies?count={count}&max_id={max_id}&min_id={min_id}&collection={collection_id}&isrc={isrc_id}&platform={platform_id}&is_taken_down={true|false}

Query Parameters

Name Description
count
integer
number of copies to list (must be between 1 and 100; default: 100)
max_id
integer
highest ID that can be returned (exclusive)
min_id
integer
lowest ID that can be returned (exclusive)
asset_id
integer
returns copies with this asset ID
status
integer
returns copies that have this status
start
date
returns copies that have updates >= the start date in format "mm-dd-yyyy"
collection
integer
returns copies that have this collection
isrc
string
returns copies that have this isrc
platform
string
returns copies that have this platform
is_taken_down
boolean
if true, returns only copies that have been taken down

Response Fields

Name Description
match_id
integer
match ID (signed 64 bit integer)
match_id_str
string
string representation of the match ID
asset_id
integer
asset ID associated with this copy (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
whitelist_ids
integer[]
list of the whitelist IDs associated with the copy
whitelist_ids_str
string[]
list of the string representations of the whitelist IDs
created_at
string
timestamp when the database record of the copy was created
platform
string
website associated with the copy
copy_media_url
string
URL associated with the copy
copy_user_url
string
user URL associated with the copy
copy_user_name
string
user name associated with the copy
copy_user_real_name
string
user real name associated with the copy
copy_user_is_verified
boolean
is user associated with the copy verified
copy_title
string
name of the copy title
copy_upload_date
string
when the copy was first uploaded
copy_duration
float
duration of the copy, in seconds
copy_sound_id
string
sound ID associated with the copy
copy_statistics
object
copy statistics metadata
copy_statistics.views_count
object
number of views
copy_statistics.shares_count
object
number of shares
copy_statistics.comments_count
object
number of comments
copy_statistics.likes_count
object
number of likes
copy_statistics.dislikes_count
object
number of dislikes
match_data
object
match details
match_data.matching_segments_in_asset
integer[]
timestamps in asset associated with the match
match_data.matching_segments_in_copy
integer[]
timestamps in copy associated with the match
match_data.copy_percentage_of_asset
integer
percent of asset that matched copy
match_data.asset_percentage_of_copy
integer
percent of copy that matched asset
match_data.length_of_match
integer
total length of the match
match_data.is_audio_modified
bool
is the match on modified audio
match_category
string
match category (EC, FC, PC, SN, SN30, SN10, SN5)
useractions
object
contains the match statuses
user_actions.statuses
integer[]
match statuses
is_nsfw
boolean
is the match from a NSFW platform
is_taken_down
boolean
is the match taken down
content_type
string
is the type of match (audio,video or audiovisual)

Get a copy

# Retrieve information about the copy with match ID 1234567890123456789
{
   "match_id":1234567890123456789,
   "match_id_str":"1234567890123456789",
   "asset_id":1234567890123456789,
   "asset_id_str":"1234567890123456789",
   "whitelist_ids":[
      1234567890123456789
   ],
   "whitelist_ids_str":[
      "1234567890123456789"
   ],
   "created_at":"2014-02-14T00:00:00.000000Z",
   "platform":"example",
   "copy_media_url":"example",
   "copy_user_url":"example",
   "copy_user_name":"example",
   "copy_user_real_name":"Example",
   "copy_user_is_verified":false,
   "copy_title":"Example Title",
   "copy_upload_date":"2014-02-14T00:00:00.000000Z",
   "copy_duration":15,
   "copy_sound_id": "2570399001262912",
   "copy_statistics":{
      "views_count":0,
      "shares_count":0,
      "comments_count":0,
      "likes_count":0,
      "dislike_count":0,
      "is_audio_modified":false
   },
   "match_data":{
      "matching_segments_in_asset":[],
      "matching_segments_in_copy":[],
      "copy_percentage_asset":0,
      "copy_percentage_copy":0,
      "length_of_match":0
   },
   "match_category":"SN30",
   "user_actions":{
      "statuses":[
         10,
         60
      ]
   },
   "is_nsfw": true,
   "is_taken_down": true,
   "content_type": "audio"
}

Description: Retrieves data for the specified match.

HTTP Request

GET /v3/drm/copies/{match_id}

Path Parameters

Name Description
match_id
string, required
match ID

Response Fields

Name Description
match_id
integer
match ID (signed 64 bit integer)
match_id_str
string
string representation of the match ID
asset_id
integer
asset ID associated with this copy (signed 64 bit integer)
asset_id_str
string
string representation of the asset ID
whitelist_ids
integer[]
list of the whitelist IDs associated with the copy
whitelist_ids_str
string[]
list of the string representations of the whitelist IDs
created_at
string
timestamp when the database record of the copy was created
platform
string
website associated with the copy
copy_media_url
string
URL associated with the copy
copy_user_url
string
user URL associated with the copy
copy_user_name
string
user name associated with the copy
copy_user_real_name
string
user real name associated with the copy
copy_user_is_verified
boolean
is user associated with the copy verified
copy_title
string
name of the copy title
copy_upload_date
string
when the copy was first uploaded
copy_duration
float
duration of the copy, in seconds
copy_sound_id
string
sound ID associated with the copy
copy_statistics
object
copy statistics metadata
copy_statistics.views_count
object
number of views
copy_statistics.shares_count
object
number of shares
copy_statistics.comments_count
object
number of comments
copy_statistics.likes_count
object
number of likes
copy_statistics.dislikes_count
object
number of dislikes
match_data
object
match details
match_data.matching_segments_in_asset
integer[]
timestamps in asset associated with the match
match_data.matching_segments_in_copy
integer[]
timestamps in copy associated with the match
match_data.copy_percentage_of_asset
integer
percent of asset that matched copy
match_data.asset_percentage_of_copy
integer
percent of copy that matched asset
match_data.length_of_match
integer
total length of the match
match_data.is_audio_modified
bool
is the match on modified audio
match_category
string
match category (EC, FC, PC, SN, SN30, SN10, SN5)
useractions
object
contains the match statuses
user_actions.statuses
integer[]
match statuses
is_nsfw
boolean
is the match from a NSFW platform
is_taken_down
boolean
is the match taken down
content_type
string
is the type of match (audio,video or audiovisual)

Get copy status

# GET /drm/copies/1234567890123456789/status
# Sample response
{
   "match_id":1234567890123456789,
   "match_id_str":"1234567890123456789",
   "user_actions":{
      "statuses":[
         10,
         11
      ]
   }
}

Description: Retrieved the statuses for the specified match.

HTTP Request

GET /v3/drm/copies/{match_id}/status

Path Parameters

Name Description
match_id
string, required
match ID

Response Fields

Name Description
match_id
integer
match ID (signed 64 bit integer)
match_id_str
string
string representation of the collection ID
user_actions
object
contains the match statuses
user_actions.statuses
[], required*
match statuses

Add copy status

# POST /drm/copies/1234567890123456789/status
Formatted JSON Data
{  
   "status":60
}

# Sample response
{  
   "match_id":1234567890123456789,
   "match_id_str":"1234567890123456789"
}

Description: Add a new status the specified match.

HTTP Request

POST /v3/drm/copies/{match_id}/status

Path Parameters

Name Description
match_id
string, required
match ID

Body Parameters

Name Description
status
integer, required
status to add to the copy

Response Fields

Name Description
match_id
integer
match ID (signed 64 bit integer)
match_id_str
string
string representation of the match ID

Delete copy status

# DELETE /drm/copies/1234567890123456789/60
# Sample response
{  
   "match_id":1234567890123456789,
   "match_id_str":"1234567890123456789"
}

Description: Removes the specified status from the copy.

HTTP Request

DELETE /v3/drm/copies/{match_id}/status/{status_id}

Path Parameters

Name Description
match_id
string, required
match ID
status_id
string, required
status

Response Fields

Name Description
match_id
integer
match ID (signed 64 bit integer)
match_id_str
string
string representation of the match ID

Get organization statuses

# GET /drm/copies/statuses
# Sample response
[
    {
        "status": 10,
        "status_str": "10",
        "title": "False positive (cover)",
        "created_at": "2019-12-19T20:12:52.270334Z",
        "updated_at": "2019-12-19T20:12:52.270334Z"
    },
]

Description: Retrieves all statuses available to your organization.

HTTP Request

GET /v3/drm/copies/statuses

Response Fields

Name Description
status
integer
status ID (signed 64 bit integer)
status_str
string
string representation of the status ID
title
string
status title
created_at
string
timestamp when the status was created
updated_at
string
timestamp when the status was updated

Create custom organization status

# POST /drm/copies/status
Formatted JSON Data
{  
   "title":"Needs further review"
}
# Sample response
{
    "status": 300,
    "status_str": "300",
    "title": "Needs further review",
    "created_at": "2019-12-19T20:12:52.270334Z"
}

Description: Creates a custom status for an organization - up to 5 custom statuses can be created.

HTTP Request

POST /v3/drm/copies/status

Body Parameters

Name Description
title
string
title of the status

Response Fields

Name Description
status
integer
status ID (signed 64 bit integer)
status_str
string
string representation of the status ID
title
string
status title
created_at
string
timestamp when the status was created

Delete organization custom status

# DELETE /drm/copies/status/{status_id}

# Sample response
{
    "status": 300,
    "title": "Needs further review",
}

Description: Deletes a custom status of an organization.

HTTP Request

DELETE /v3/drm/copies/status/{status_id}

Path Parameters

Name Description
status_id
string, required
status ID

Response Fields

Name Description
status
integer
status ID (signed 64 bit integer)
title
string
status title

Statuses

Status Meaning
10 False Positive - Cover
11 False Positive - Missing Audio
12 False Positive - Missing Video
13 False Positive - Not My Content
30 Externally Actioned
40 Infringing
50 Fair Use
60 For Further Review
70 Claim Attempted
71 Takedown Attempted
72 Takedown Retraction Attempted

Match categories

Status Meaning
EC Exact copy, the entire asset was copied.
PC Partial copy, less than 98% of the asset was copied and the copy has other content.
FC Full copy, more than 98% of the asset was copied and the copy has other content.
SN Snippet, part of the asset was copied and the copy also contains other content.
SN5 Snippet under 5 seconds long.
SN10 Snippet under 10 seconds long.
SN30 Snippet under 30 seconds long.

Errors

PEX uses the following error codes:

Code Meaning
400 Bad Request -- Your request is invalid. Please check your input.
401 Unauthorized -- Your API key is wrong or missing.
403 Forbidden -- You are not allowed to access this endpoint/data.
404 Not Found -- The data you were looking for could not be found.
405 Method Not Allowed -- You tried to access an invalid method or accessed a wrong endpoint.
429 Too Many Requests -- You have exceeded your rate limit.
500 Internal Server Error -- We had a problem with our server. Please try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.