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:
- For assets < 2 GB use:
POST /v3/cms/assets/upload - For assets >= 2 GB use:
POST /v4/cms/assets/upload
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:
tus-js-client — by tus Add tus v1.0.0 resumable file uploads to client web apps that are built with JavaScript.
tus-java-client— by tus Add tus v1.0.0 resumable file uploads to client app using Java.
tus-py-client — by Ifedapo Olarewaju Integrate tus v1.0.0 with Python clients
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 (via link)
# 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:
- Audiomack
- Audius
- Dailymotion
- Datpiff
- Gfycat
- Giphy
- Imgur
- Likee
- Soundcloud
- Streamable
- Tenor
- TikTok
- Vimeo
- YouTube
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. |
Sound Metadata
Get Sound Metadata info
# GET /drm/sound-metadata/{soundID}?platform={platform1}
# Sample response
{
"sound_id": "87654",
"url": "www.platform.com/87654",
"title": "title1",
"artist": "author1",
"platform": "platform1",
"is_original": true,
"video_count": 10000000
}
Description: Retrieves metadata info from sound ID and its corresponding platform.
HTTP Request
GET /drm/sound-metadata/{soundID}?platform={platform}
Path Parameters
| Name | Description |
|---|---|
| platform string, required |
platform name |
Response Fields
| Name | Description |
|---|---|
| sound_id string |
sound ID |
| url string |
URL associated with the sound ID |
| title string |
title |
| artist string |
artist |
| platform string |
platform associated with the sound ID |
| is_original bool |
content uploaded by user or present in platform's library |
| video_count integer |
number of videos using this sound ID |
Get List of Sound Metadata info
# POST /drm/sound-metadata
Formatted JSON Data
[
{
"sound_id": "87654",
"platform": "platform1"
},
{
"sound_id": "987654",
"platform": "platform2"
}
]
# Sample response
[
{
"sound_id": "87654",
"url": "www.platform1.com/87654",
"title": "title1",
"artist": "author1",
"platform": "platform1",
"is_original": true,
"video_count": 10000000
},
{
"sound_id": "987654",
"url": "www.platform2.com/987654",
"title": "title2",
"artist": "author2",
"platform": "platform2",
"is_original": false,
"video_count": 2000000
}
]
Description: Retrieves a list of metadata info from sound IDs and their corresponding platforms. Up to 100 sound IDs can be queried at once.
HTTP Request
POST /v3/drm/sound-metadata
Body Parameters
| Name | Description |
|---|---|
| sound_id string |
sound ID |
| platform string |
platform associated with the sound ID |
Response Fields
| Name | Description |
|---|---|
| sound_id string |
sound ID |
| url string |
URL associated with the sound ID |
| title string |
title |
| artist string |
artist |
| platform string |
platform associated with the sound ID |
| is_original bool |
content uploaded by user or present in platform's library |
| video_count integer |
number of videos using this sound ID |
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. |