Quantum

REST API Reference

The REST API consists of a set of ‘endpoints’ (URLs such as /catdv/api/clips) that provide access to a set of operations (GET, PUT, POST and DELETE) on a particular type of object (e.g. a Clip).

Common Object Definitions

The REST API sends and receives data formatted as JSON objects of various types. This section describes each of the different types of objects used.

Message Envelope (Reply Object)

As mentioned in the Getting Started section all messages returned by the REST API consist of a common ‘Reply’ message object that contains status information and the actual payload:

Each Reply object contains the following fields

Field

Type

Description

status

OK,ERROR,AUTH,MODIFIED

OK – call succeeded

ERROR – and error occurred. Details in errorMessage field. AUTH – authentication is required to access this endpoint.

MODIFIED – the object being updated has been modified on the server.

data

Object

The payload. Type depends on the endpoint and method.

errorMessage

String

Details of any error that occurred. Not present if message succeeded.

PartialResultSet Object

Where calls may return a large number of items the payload is a wrapped in a ‘PartialResultSet’ object. Each PartialResultSet’ object contains the following fields

Field

Type

Description

totalItems

Integer

The total number of items in the result set. This collection will typically contain a subset of these.

offset

Integer

The offset of the first item in this partial result set into the complete result set.

items

Array

The items.

Methods that return PartialResultSets support two standard URL parameters:

skip – skip the first N items in the result set

take – take N items from that point

The combination of these two parameters allows the client to select any portion of the complete result set allowing efficient implementation of paging in the web UI.

Timecode Object

All Timecodes in CatDV (e.g. clip duration and in/out points) are represented in the REST API as Timecode objects. Each Timecode object contains the following fields

Field

Type

Description

fmt

Short

Timecode format (e.g. 25, 2997).

frm

Int

Timecode value in frames

secs

Double

Timecode value in seconds.

txt

String

Formatted textual representation of timecode

QueryDefinition Object

Each QueryDefinition object contains the following fields

Field

Type

Description

name

String

Name of the query

terms

QueryTerm[]

An array of the query terms that make up the query.

QueryTermObject

Each QueryTermobject contains the following fields

Field

Type

Description

field

String

Field this term operates on (see Clip Query Filter Syntax)

op

String

Comparison operator (see Clip Query Filter Syntax)

params

String

Constant value to compare field against

logicalOR

Boolean

Normally all terms must evaluate to true. However, if some or all terms are marked as ‘OR’ terms then only one of them needs to

evaluate to true. There must always be more than one OR term.

logicalNOT

Boolean

Term evaluates to true is the operator returns false.

ignoreCase

Boolean

Ignore case when applying operator (ignored if not a text field)

Endpoint: /session

Gives access to the current HTTP session.

Object Definitions

Session Object

Each session object contains the following fields

Property

Type

Description

username

String

Username of authenticating user

password

String

Plain text password

encryptedPassword

String

RSA Encrypted password

Operations

GET /session?usr=<username>&pwd=<password> GET /session?usr=<username>&epwd=<encrypted_password>

Returns the jSessionId of the current server session and sets the JSESSIONID cookie so that all subsequent calls attach to the authenticated session.

Parameter

Type

Description

Usr

String

Username of authenticating user

Pwd

String

Plain text password

epwd

String

RSA Encrypted password

In production environments is it always recommended that the encrypted form of this call is used. The encrypted password is sent as a base64 encoded representation of a standard RSA encrypted version of the plain text password using the public session key (see below).

GET /session/key

Returns a base64 encoded public key unique to this session that can be used to encrypt a plain text password before sending over the wire. See section “Password Encryption” for more details.

POST /session

To avoid user credentials appearing in a URL it is recommended that the POST method be used. The POST data should contain a JSON object with the following fields:

DELETE /session

Ends the current session – logs out the user and frees one license.

Endpoint: /catalogs

Represents the collection of all catalogs on the server:

Object Definitions

Catalog Object

Each catalog object contains the following fields

Field

Type

R/O

Description

ID

Integer

Unique ID of catalog

seq

Integer

X

Internal

userID

Integer

Unique ID of user that created this catalog

userName

String

X

Username of catalog creator

groupID

Integer

Unique ID of the production group this catalog belongs to.

groupName

String

X

Name of group catalog belongs to.

name

String

Catalog’s name

fields

Object

Custom catalog fields as name/value pairs

whoCreated

String

X

Name of creator

whoSaved

String

X

Name of person who last updated this catlog

owner

String

Name of catalog’s owner

notes

String

Free text notes field

whenCreated

JSDate

X

When this catalog was created

whenExtended

JSDate

X

When additional clips were last added to this catalog

whenSaved

JSDate

X

When this catalog was last saved

whenPublished

JSDate

X

When this catalog was last published

readOnly

True/False

Is this catalog read only?

readProtected

True/False

Is this catalog protected

password

String

Catalog password

version

Internal

Operations

GET /catalogs[?query=<query>]…

Returns either a simple array or a PartialResultSet (if skip/take parameters are set) of the catalogs on the server that match the query parameter.

URL Parameter

Type

Description

query

Query

Retrieve catalogs that match the provided query. For more information about the syntax of the query parameter see the “Query Filter Syntax” section.

include

String

Specifies which catalog data to include in the result set. Possible values are:

fields – include the user defined catalog fields onlyBasicInfo – only include basic catalog info

Multiple values can be passed as a comma separated list.

sortBy

String

Field the results should be sorted by

sortDir

String

Direction of sort (asc or desc)

skip

Integer

For paging – offset to start of page in result set

take

Integer

For paging – number of items to fetch in this page

GET /catalogs/<id>

Returns the catalog with the specified id;

POST /catalogs/<id>

Add a new catalog. The new catalog must specify the groupID for a valid, accessible group that the catalog will be added to.

PUT /catalogs /<id>

Update an existing catalog. The HTTP POST data should contain a partially populated catalog object. Only fields that are included in the POST data will be updated. All other fields will remain the same except for special fields such as last modified date.

DELETE /catalogs/<id>

Delete the specified catalog. All clips contained within the catalog will also be deleted (or moved to the trash).

Endpoint: /clips

Represents the collection of all clips on the server.

Object Definitions

CatDV represent each Clip as a set of related objects:

Clip – the clips itself

Source Media – represents the media associated with a clip. Note that a master clip and any subclips created from that master clip all share the same Source Media object.

Import Source – represents the media from which the asset was imported. In most cases this will be the same as the Source Media, but it may represent a tape or an XML batch file.

Markers – each clip contains a set of markers that represent.

Tape Info – for tape-based workflows – represents the tape the clip was ingested from.

History – each time the clip status is updated an entry is made in the clip’s history.

The details of the objects are detailed below.

Clip Object

Each clip object contains the following fields

Field

Type

R/O

Description

ID

Integer

Unique ID of clip

catalogID

Integer

Unique ID the catalog this clip belongs to

catalog

Catalog(Partial)

X

Information about the Catalog this clip belongs (Read Only)

userID

Integer

Unique ID of user that created this clip

userName

String

X

Name of user that created this clip (Read Only)

clipref

String

User-settable external reference for this clip

type

ClipType

Simple Clip Types

clip – standard (master) clip

subclip – clip that represents a part of a master clip.

still – a still image

imgseq – a sequence of still images

audio – an audio only clip.

seq – a rough-cut sequence

pending – type is yet to be determined (quick folder scan)

other – some other, non-media asset (e.g. PDF)

Metaclip Types

metaclip – complex media asset made up from multiple essence files (e.g. P2 or op-atom).

folder – simple container for other clips (aka bin).

playlist – members should be played in order end to end.

multicam - members represent different camera views of the same event.

versions – members are different versions of the same asset

typeID

Integer

Low-level type identifier

name

String

Clip’s name

notes

String

Clip notes

bigNotes

String

Extended clip notes

importNotes

String

X

Information/Error messages from importer

tape

String

Tape name

status

String

User defined status of this clip

bin

String

Name of bin this clip is in

format

String

Human readable description of media format

fps

Float

Frames per second

modifiedDate

JSDate

X

Date of last modification

recordedDate

JSDate

X

Date when this clip was recorded

in

Timecode

Timecode of start of clip

out

Timecode

Timecode of end of clip

duration

Timecode

Timecode representing total duration of the clip

in2

Timecode

Timecode of start of selection within the clip

out2

Timecode

Timecode of end of selection within the clip

duration2

Timecode

Timecode representing duration of the selection

marked

Boolean

Flag indicating this clip is marked

hidden

Boolean

Flag indicating this clip is hidden

isEditable

Boolean

X

Flag indicating whether this clip can be edited by the current user

orientation

Integer

Rotation of still images

good

Character

User-defined flag indicating good/bad status of clip

rating

Integer

Rating value from 1 to 5

pos

Integer

Specifies the position of the clip within its container (catalog or metaclip).

posterID

Integer

ID of thumbnail that acts as the poster for this clip

thumbnailIds*

Integer[]

X

Array of IDs of all the thumbnails associated with this clip

transition

String

Transition description

markers*

Marker[]

Array of markers defined on this clip.

history*

History[]

History of changes made to this clip.

seqItems*

SequenceItem[]

(Sequences only) The items in the sequence

members*

Clip[]

(Metaclips only) The items in the metaclip

sourceMediaID

Integer

Unique ID of the source media associated with this clip

media*

SourceMedia

The associated SourceMedia Object – if present

mediaStart

Timecode

Timecode of the start of the associated source media

mediaEnd

Timecode

Timecode of the start of the associated source media

importSourceID

Integer

Unique ID of the import source associated with this clip

importSource*

ImportSource

The associated ImportSourceObject – if present

tapeInfo*

TapeInfo

fields*

Object

An object that represents the custom field values for this clip. The property names are the FieldDefinition

identifiers for each field. Only non-blank values are present.

permissions

Permission

X

Set of permissions for this clip (Pegasus only – control via ACL rules)

parentID

Integer

Specifies the ID of the containing metaclip. This is a write-only property used to add/remove clips from a metaclip. See the “Metaclip Operations” section below.

* This field is only populated when explicitly requested in the include parameter of a clip request..

ImportSource Object

The Import Source represents the file that was originally imported. For single media files this will be the same as the SourceMedia, but for XML batch files this will be the path of the XML file itself. Each ImportSource object contains the following fields

Field

Type

R/O

Description

ID

Integer

Unique ID of source media

file

String

Path of originally imported file

size

Integer

Size of the original files

modifiedDate

JSDate

X

Modification date of the original file

importedDate

JSDate

Date file imported

fields

Object

An object holding arbitrary metadata about this import source object.

SequenceItem Object

Each SequenceItem object contains the following fields

Field

Type

Description

catalogID

Int

Id of the catalog to which the containing sequence belongs.

seqID

Int

Id of the sequence (Clip) to which this item belongs.

seqIn

Timecode

Timecode of position in sequence timeline where this item starts.

seqOut

Timecode

Timecode of position in sequence timeline where this item ends.

clipID

Int

Id of the source clip that this item comes from.

clipName

String

Name of the source clip that this item comes from.

clipTape

String

Tape that the source clip that this item comes from is on.

clipIn

Timecode

Timecode of start of this item in the source clip.

clipOut

Timecode

Timecode of end of this item in the source clip.

track

Int

Sequence track that this item is on.

clipMediaID

Int

Id of the source media associate with the source clip.

mediaStart

Timecode

Timecode of start of source media associate with the source clip.

mediaEnd

Timecode

Timecode of start of source media associate with the source clip.

mediaAspectRatio

Float

Aspect ratio of source media associate with the source clip.

mediaFPS

Float

Media frame-rate in frames-per-second

TapeInfo Object

Each TapeInfo object contains the following fields

Field

Type

Description

tapeName

String

Tape name.

description

String

Tape content description.

notes

String

Notes.

Location

String

Location description.

history

String

Tape history.

reelNumber

String

Tape reel number.

format

String

Tape format.

videographer

String

Tape videographer.

project

String

Tape project.

subject

String

Tape subject.

media

String

Tape media.

loggedDate

JSDate

Date tape logged.

createdDate

JSDate

Date tape created.

modifiedDate

JSDate

Date tape modified.

Marker Object

Each Marker object contains the following fields

Field

Type

Description

name

String

Name of event marker

category

String

Name of user defined category marker belongs to.

in

Timecode

Timecode of marker, or start of marker if marker is a range

out

Timecode

Timecode of end of marker if marker is a range

description

String

Textual description associated with marker.

fields

Object

An object holding arbitrary metadata about this marker as key/value pair. The keys are the FieldDefinition identifier for the relevant field

History Object

Each History object contains the following fields

Field

Type

Description

date

JSDate

Date of action

user

String

User who performed the action

action

String

Description of action performed.

Operations

GET /clips[?query=<query>][&include=<include>]…

Returns a PartialResultSet containing the clips that match the criteria specified by the URL parameters. If no other criteria are provided the most recently modified clips are returned.

URL Parameter

Type

Description

query

Query

Retrieve clips that match the provided query. For more information about the syntax of the query parameter see section “Query Filter Syntax”.

catalogID

Integer

Retrieve clips contained in the specified Catalog

smartFolderID

Integer

Retrieve clips contained in the specified Smart Folder

clipListID

Integer

Retrieve clips contained in the specified Clip List

filters

Query

maxResults

Integer

Override the default maxResults value.

masterClipsOnly

Boolean

Only return master clips (not subclips, sequences etc.)

include

String

Specifies which clip data to include in the result set. Possible values are:

catalog – include the containing catalog clip.fields – include user-defined clip fields history – include status history thumbnails – include thumbnail IDs markers – include event markers media – include associated source media importSource – include import source metadata – include source media fields tapeinfo – include related tape info events – include containing event

members – include metaclip members (metaclips only) seqitems – include sequence items (sequences only) proxyPath – include calculated proxy path altPaths – include all possible proxy paths

Multiple values can be passed as a comma separated list.

fetchRelated

String

If set also return related data (see below)

sortBy

String

Field the results should be sorted by

sortDir

String

Direction of sort (asc or desc)

skip

Integer

For paging – offset to start of page in result set

take

Integer

For paging – number of items to fetch in this page

Fetch Related Data

The ‘fetchRelated’ parameter tells the server to include in the result set clips that are related to the clips that match the query. The possible values of fetchRelated are:

Value

Meaning

true

Return the component clips of any sequences in the result set and any members of any metaclips. These value is implied if any of the other fetchRelated values listed below are specified.

sameTape

Include all clips that are from the same tape as any of the matching clips.

sameCatalog

Include all clips that are in the same catalog as any of the matching clips.

similarDate(d)

Include all clips with a date within ‘d’ days of the matching clips.

similarTimecode(f)

Include all clips with an in or out point within ‘f’ frames of the matching clips.

sameFields(f1,f2,..)

Include all clips with where all the specified fields match the same field of the matching clips. (see Field Specifiers above for format of

f1, f2, etc.)

GET /clips/<id>

Returns the clip with the specified id

POST/clips

Add a new clip. The POST data should include a JSON Clip object that must include, as a minimum a name and the catalogID of a valid, accessible catalog that the clip will be added to.

PUT /clips/<id>

Update selected fields of the clip with the specified id. HTTP POST data should contain a partially populated clip object. Only the fields that are populated will be updated.

PUT /clips

Update multiple clips. There are two variants:

HTTP POST data contains a single JSON Clip object but the ID field contains an array of IDs. In this case the same updates will applied to all the Clips specified by the list of IDs.

HTTP POST data contains an array of JSON Clip objects, each containing an ID and any other fields to update, and the each update is applied in turn.

Metaclip Operations

A “metaclip” is a container for other clips. They can used to represent:

1. Complex Media - such as op-atom - where a single asset might comprise multiple separate video and audio essence files.

2. Multi-cam - where the same event has been captured by multiple cameras.

3. Playlists – where a set of clips should be played back to back in order.

4. Folders – a simple, non-structured container of related media assets (aka a bin).

5. Version Sets – multiple versions of the same media asset.

The members of a metaclip can be retrieved using the REST API by adding the relevant includes parameter to the GET call:

GET /clips/1234?include=members

Metaclips can be managed through the REST API using the ‘parentID’ property of the Clip object. The parentID property is write-only – it is never returned by the REST API – it is only used in POST and PUT methods to specify the parent relationship of the clip being created or updated.

For example, the following PUT payload would add an existing clip whose id is 1234 to an existing metaclip, whose id is 2345:

{ ID: 1234, parentID: 2345

}

This will add the clip to the end of the list of metaclip members. To specify, or update the position of a metaclip member within the metaclip’s member collection, the request should include a value for the ‘pos’ property:

{ ID: 1234, parentID: 2345,

pos: 7

}

The exact value of the ‘pos’ field doesn’t matter, only its relative value with respect to the other members of the containing metaclip.

A metaclip member can be removed from its containing metaclip by setting parentID to ‘null’:

{ ID: 1234, parentID: null

}

NOTE: including a parentID property set to ‘null’ is not the same as not including a parentID property at all. If no parentID property is present in the payload then no metaclip operations are performed. If the parentID property is present then a metaclip operation is performed, and if the value of parentID is ‘null’ then the member is removed from its metaclip.

Endpoint: /sourcemedia

Represents the collection of SourceMedia objects. Generally manipulation of Source Media objects occurs through the /clips endpoint, when the parent clip is modified. However sometimes it is useful to manipulate the Source Media object directly.

Also this endpoint gives access to the thumbnail objects associated with each source media object, whereas the /thumbnails endpoint itself gives access to the thumbnail images.

Object Definitions

SourceMedia Object

Each SourceMedia object contains the following fields

Field

Type

R/O

Description

ID

Integer

Unique ID of source media

filePath

String

Path of original media file

fileSize

Integer

Size of original media file in bytes

tape

String

Tape name for this media

videoFormat

String

Human readable description of video format

audioFormat

String

Human readable description of audio format

tracks

String

Media track information

aspectRatio

Float

Aspect ratio (width/height) of the media

modifiedDate

JSDate

X

Date of last modification

start

Timecode

Media start timecode

end

Timecode

Media end timecode

tcFmt

Integer

Timecode format. One of a fixed set of known values, but based on the frame rate e.g. 24, 25, 2997

importer

String

Import component used to import file

still

Boolean

True if the media represents a still image

dataRate

Integer

Encodng data reate

archiveStatus

String

Human readable description of media’s current archive status

omRef

String

OMF Reference

qttc

Integer

Quicktime Timecode

movieStart

Integer

Movie start

movieDuration

Integer

Movie duration

movieFrames

Integer

Movie frames

startFrame

Integer

Start frame

geotag

String

EXIF GeoTag information

proxyPath

String

Path of the matching proxy for this media file if one is available.

altPaths

String[]

Result of applying all server-side path mappings. used when paths are not accessible to the server so only the client can

determine which mapping is correct.

fields

Object

An object holding arbitrary metadata about this media object.

Thumbnail Object

Each thumbnail object contains the following fields

Field

Type

R/O

Description

ID

Integer

Unique ID of source media

time

Float

Time in seconds from start of media

orientation

Integer

Orientation of the thumbnail image

timecode

Timecode

Timecode of the location in the media that this thumbnail is taken from

mediaFrame

Integer

Frame number of this thumbnail

image

String

Base64 encoded JPEG image data.

Operations

GET /sourcemedia/<id>

Returns the SourceMedia object with the specified id.

GET /sourcemedia/<id>/thumbnails

Returns data about the thumbnails associated with the specified SourceMedia object (rather than the actual images).

GET /sourcemedia/<id>/thumbnails/<thumbnail_id>

Returns data about the specified thumbnail associated with the specified SourceMedia object (rather than the actual image).

POST /sourcemedia/<sourceMediaID>/thumbnails

Add a new thumbnail to the specified source media object.

PUT /sourcemedia[?fromDirectory=< path >][&toDirectory=<path>]

Special support for bulk moving files from one directory to another. This operation updates the paths of all Source Media objects whose folder path matches ‘fromDirectory’ by replacing fromDirectory’ with toDirectory.

PUT /sourcemedia/matching-mediapaths

Special support for bulk updating metadata on all source media objects with matching media path. The POST data should contain a partially populated JSON Source Media object, which must include a valid ‘filePath’ property. The other populated fields will be updated in all Source Media objects that have that filePath. This feature is typically used to update the metadata fields that represent an assets archive status.

PUT /sourcemedia/<sourceMediaID>

Updates the specified Source Media object. POST data should contain a partially populated JSON Source Media object. Only fields that are present in the JSON object will be updated.

PUT /sourcemedia/<sourceMediaID>[/thumbnails/<thumbnailID>]

Updates the specified thumbnail object. POST data should contain a partially populated JSON Thumbnail object. Only fields that are present in the JSON object will be updated.

Endpoint: /thumbnail

Gives access to individual thumbnail images stored on the server. To access the thumbnail data objects use the /sourcemedia endpoint):

Operations

GET /thumbnail/<id>[?width=<width>][&height=<height>]…

Returns the actual image data for the thumbnail with the specified id. The reply will have an appropriate MIME type such as image/jpeg.

URL Parameter

Type

Description

width

Integer

Scale the thumbnail image to the specified width (in pixels)

height

Integer

Scale the thumbnail image to the specified height (in pixels)

fmt

String

Image format to return (jpg or png)

bgcolor

Color

If aspect ratio of thumbnail does not match the given width/height then the remaining space is filled with the specified color.

assetType

Query

If the thumbnail ID is <=0 then the assetType (essentially file extension) is used to draw an appropriate icon.

Endpoint: /media

Gives access to the media file data stored on the server. To access the Source Media data objects use the /sourcemedia endpoint):

Operations

GET /media/<id>[?type=orig&download=true]

Returns the actual media data for the source media with the specified id. The reply will have an appropriate MIME type and can often be displayed directly by a browser. However, for video files it is usually necessary to create a specific media plug-in such as the QuickTime Player, and pass this URL of this endpoint to that.

URL Parameter

Type

Description

type

proxy/orig

Specifies whether to serve the original media (type=orig) or

the proxy media (type=proxy). Defaults to proxy if not specified

download

true/false

If download=true then the endpoint serves the media with a MIME type of ‘application/octet-stream’ and a Content- Disposition of ‘attachment’. This will cause most browsers to prompt the user to save the content to a local file, rather than

displaying the media itself.

NOTE: to access the media the caller must be in an authenticated session. If the media player being used does not inherit the browser’s cookies then it will be necessary to explicitly pass the JSessionID in the URL. This is done by appending the JSessionID to the URL separated with a semi-colon. For example

http://<catdv>/catdv/api/1/media/1234;jsessionid=CB2E8C4D09142DFFA416E7522

Endpoint: /smartfolders

Represents the collection of smart folders defined on the server

Object Definitions

SmartFolder Object

Each SmartFolder object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of smart folder

groupID

Integer

ID of the production group this folder belongs to.

userID

Integer

ID of the user this folder belongs to.

name

String

Name of this smart folder

notes

String

Notes

modifiedDate

JSDate

Last modified data

query

QueryDefinition

The query that defines the contents of this smart folder.

Operations

GET /smartfolders

Return the list of all the smart folders defined on the server.

GET /smartfolders/<id>

Return the specified smart folder.

POST /smartfolders

Add a new smart folder to the system. The POST data must contain a JSON string representing the smart folder.

PUT /smartfolders/<id>

Update an existing, specified smart folder to the system. The POST data must contain a JSON string representing the updates to the smart folder. Only the fields that are to be changed need to be included.

DELETE /smartfolders/<id>

Remove the specified smart folder from the system.

Endpoint: /cliplists

Represents the collection of Clip Lists defined on the server

Object Definitions

ClipList Object

Each ClipList object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of clip list

groupID

Integer

ID of the production group this folder belongs to.

userID

Integer

ID of the user this folder belongs to.

name

String

Name of this clip list

notes

String

Notes

modified

JSDate

Last modified data

clipIDs

Integer[]

Array of IDs of the clips contained in this list

Fields

Object

Custom clip list fields as name/value pairs

Operations

GET /cliplists

Return the list of all the clip lists defined on the server.

GET /cliplists/<id>

Return the specified clip list.

POST /cliplists

Add a new clip list to the system. The POST data must contain a JSON string representing the clip list.

PUT /cliplists/<id>

Update an existing, specified clip list to the system. The POST data must contain a JSON string representing the updates to the clip list. Only the fields that are to be changed need to be included.

DELETE /cliplists/<id>

Remove the specified clip list from the system.

Endpoint: /suggest

Exposes search suggestions

Operations

GET / suggest[?prefix=<prefix>]

Return the list of suggested search words that start with the specified prefix. Suggestions are derived from picklists and full-text index.

Endpoint: /uploads

Provides access to CatDV Server’s HTTP-based file upload mechanism. The client creates a new upload session using the POST operation, and receives a upload session ‘ticket’. It then calls PUT with chunks of binary data, tagged with the ticket, which are assembled on the server to form the uploaded file.

Object Definitions

FileUploadSession Object

Each FileUploadSession object contains the following fields

Field

Type

R/O

Description

ticket

String

X

Unique ID of this upload session

filePath

String

Path of file being uploaded

fileSize

Integer

Size, in bytes, of file being uploaded

batchID

String

When uploading multiple files the client can provide a batchID that the server will use to place all the files in the batch into a single upload sub-folder. It will also preserve the relative paths of the uploaded files within that folder, making it possible to upload complete folder trees – for example a camera card.

metadata

Object

Used to build a sidecar file, so that when the uploaded clip is ingested into CatDV, the specified fields and user fields will be set to the specified values. The schema of the metadata should match the schema for a Clip object (e.g. user-field values should be placed in a sub-key called ‘fields’)

status

String

X

Current status of this session:

· new

· in-progress

· complete

· failed

bytesUploaded

Integer

X

Number of bytes uploaded so far

errorMessage

String

X

If status is ‘failed’ then an error message describing the failure.

Operations

POST /uploads

Create a new upload session. The POST data must contain a partially populated JSON FileUploadSession object that includes ‘filePath’, ‘fileSize’ and optionally ‘batchID’ field values. The server returns the created FileUploadSession object, with the ‘ticket’ field filled in and status set appropriately.

PUT / uploads /<ticket>

Upload a binary chunk to the session identified by the upload ticket. Returns a FileUploadSession object containing the current status and bytesUploaded set.

Endpoint /chat

The chat endpoint allows the client to send and receive ‘chat messages’ to and from users or ‘channels’.

A user may subscribe to a number of ‘channels’ and may be involved in conversations with a number of other users. To keep track of these conversations each user has a number of chat message boxes. A single message box tracks the messages between a single user and either a single channel or a single other user. The message box keeps of which messages in each conversation a user has read and when new messages arrive or are sent.

Object Definitions

Chat Message

Each chat message object contains the following fields

Field

Type

Description

fromUserID

Integer

ID of sending user

toUserID

Integer

ID of message recipient if this is a person to person message otherwise null

toChannelID

Integer

ID of message channel if this is channel message otherwise null

replyToMessageID

Integer

ID of message this message is a reply to (or null)

postedDate

Date

Date message was sent

messageType

String

text – message is simple

clips – message contains a JSON Clip object clipList – message contains a JSON Array of Clip Objects

event – message contains an event marker

message

Object

Message payload, either text or a JSON object depending on messageType

fromUserName

String

Sender user’s name

fromUserInitials

String

Send user’s initials

Chat Channel

Each chat message object contains the following fields

Field

Type

Description

name

String

Name of this channel

createdByUserID

Integer

ID of user who created the channell

createdDate

Date

When the channel was created

lastModifiedDate

Date

Last modified date

message

String

Initial message someone subscribing to the channel will see.

isPrivate

Boolean

If true channel is invitation only

visibility

String

Visibility rules

Chat MessageBox

Each chat message object contains the following fields

Field

Type

Description

userID

Integer

ID of user who owns this message box

type

String

channel – message box is associated with a channel

direct – message box is associated with a person to person chat

name

String

Name of the channel or user this message box is associated with

chatChannelID

Integer

ID of channel for type=channel (or null)

chatUserID

Integer

ID of user for type=direct (or null)

lastUpdated

Date

Date last message processed

unread

Integer

Number of unread messages in box. Messages are assumed to be read in sequence

Operations

GET: /chat/channels

Returns a list of the available channels.

POST: /chat/channels

Create a new channel. POST data contains Chat Channel object.

GET: /chat/channels/<channel_id>

Returns the channel with the given id.

PUT: /chat/channels/<channel_id>

Update the specified channel. POST data contains Chat Channel object.

DELETE: /chat/channels/<channel_id>

Delete the specified channel. All associated messages and message boxes will also be deleted.

GET: /chat/boxes

Returns a list of the available chat message boxes

POST: /chat/boxes

Create a new chat message box. POST data contains Chat Message Box object.

GET: /chat/boxes/<messageBoxID>

Returns the specified chat message boxes

GET: /chat/boxes/<messageBoxID>/messages

Returns a list messages in the specified chat message box

POST: /chat/boxes/<messageBoxID>/messages

Send a message to the specified message box. If the message box is associated with a channel then the message will be delivered to the message boxes of all users subscribed to that channel. If the message box is associated with direct person-to-person chat then the message will be delivered the recipient user’s message box specific to this person to person conversation. If required a new message box will be created.

A ‘chat.message’ notification is also sent to trigger clients to re-read any associated message boxes.

PUT: /chat/boxes/<messageBoxID>/messages

Returns a list messages in the specified chat message box

Query Filter Syntax

The CatDV REST API supports a rich set of queries that can be applied to the collection of clips, catalogs and custom objects on the server. The query is passed as the ‘query’ URL parameter in the GET method of the ‘clips’, ‘catalogs’ and ‘objects’ endpoints.

Because of the requirement to pass the query as a URL parameter many of the symbols that might normally be used to represent a query (such as space, ‘=’ ,‘&’ and ‘”’) are not available. It would be possible to escape these symbols, but this would make it cumbersome to manually type queries, which is very useful for testing. Therefore the syntax chosen uses textual representations for all operators and encloses every element in round brackets.

A query consists of one or more conditional expressions, which can be combined with boolean operators. Each conditional expression takes the following form:

((<field_specifier>)<operator>(<value>))

These conditional expressions can be combined with the Boolean operators ‘and’ or ‘or’ to form a complete query expression. e.g.

((clip.name)contains(car))and((catalog.name)eq(Race Day))

Field Specifier

The field specifier determines the field that the query clause will test.

The field specifier consists of two parts – the object name (clip, catalog, media etc.) and the field identifier. The format of the field identifier depends on whether the field is a built-in or user defined field. Built-in fields are specified using the dot notation e.g:

clip.name media.filePath

Whereas user-defined fields are specified by enclosing the field identifier in square brackets e.g:

clip[my.user.field]

For objects other than ‘clip’ the name refers to the objects associated with a given clip. In the above example ‘media refers to the Source Media object associated with a particular clip.

Not all Clip fields can be included in queries. The following table lists the supported built-in fields:

Object

Field

Type

clip

ID

INT

clip

name

STRING

clip

tape

STRING

clip

notes

TEXT

clip

in

INT_FRAMES

clip

out

INT_FRAMES

clip

duration

INT_FRAMES

clip

in2

INT_FRAMES

clip

out2

INT_FRAMES

clip

duration2

INT_FRAMES

clip

bin

STRING

clip

good

CHAR

clip

recordedDate

DATETIME

clip

importNotes

TEXT

clip

typeID

INT

clip

seq

INT

clip

transition

STRING

clip

modifiedDate

DATETIME

clip

gmtDate

DATETIME

clip

marked

BOOL

clip

hidden

BOOL

clip

format

STRING

clip

tcFmt

INT

clip

clockAdjust

STRING

clip

tapeName

STRING

clip

clipref

STRING

clip

status

STRING

clip

history

TEXT

clip

events

TEXT

clip

bigNotes

TEXT

clip

rating

INT

clip

userFields

(see notes below)

media

ID

INT

media

meatadata

TEXT

media

mediaDate

INT

media

audioFormat

STRING

media

videoFormat

STRING

media

importer

STRING

media

technical

STRING

media

fileDir

STRING

media

fileName

STRING

media

filePath

STRING

media

archiveStatus

STRING

media

aspectRatio

FLOAT

media

fileSize

INT

catalog

ID

INT

catalog

userID

INT

catalog

groupID

INT

catalog

name

STRING

catalog

notes

TEXT

catalog

createdDate

DATETIME

catalog

extendedDate

DATETIME

catalog

savedDate

DATETIME

catalog

publishedDate

DATETIME

tape

name

STRING

tape

description

TEXT

tape

notes

TEXT

tape

location

STRING

tape

format

STRING

tape

history

TEXT

tape

reel

STRING

tape

videographer

STRING

tape

project

STRING

tape

status

STRING

tape

subject

STRING

tape

media

STRING

tape

createdDate

DATETIME

tape

loggedDate

DATETIME

tape

modifiedDate

DATETIME

importSource

ID

INT

importSource

metadata

TEXT

importSource

filename

STRING

importSource

importDate

DATETIME

event

name

INT

event

description

TEXT

event

metadata

TEXT

event

history

TEXT

event

startDate

DATETIME

event

endDate

DATETIME

Multi-field Search Specifiers

Additionally there are a special set of field specifiers that allow searching against multiple fields. These are

Object

Field

Type

Searches

clip

nameOrNotes

STRING

Search clip.name and clip.notes fields.

clip

anyBuiltin

STRING

Search any built-in logging field on clip or media.

clip

anyUserDefined

STRING

Search any user-defined logging field on clip.

clip

any

STRING

Search all standard logging fields (ie. clip name, notes, etc. and any user-defined clip field)

clip

anyPlusMedia

STRING

Search all standard logging fields (as above) plus media path, media metadata, markers, and tape

Operators

The ‘operator’ part of the conditional clause specifies a comparison operator to be applied between the field and the value. Supported operations are:

Operator

Field Types

Meaning

Parameter

eq

Any

The field is equal to value

Single value

isBlank

Any

The field is blank. NOTE: Takes empty parameter e.g. ((notes)isBlank())

n/a

le

Number

The field is less than or equal to the value

Number

ge

Number

The field is greater than or equal to the value

Number

contains

Text

The field contains the value

Text

startsWith

Text

The field starts with the value

Text

endsWith

Text

The field end with the value

Text

Includes

Multi-Value

One of the values in the multi-value field equals the specified value.

Text

includesAll

Multi-Value

The values in the multi-value field include all the specified values.

Text[,Text] [,Text]

isOneOf

Text/Number

The field equals one of the specified values

Text[,Text] [,Text]

hasOneOf

Text

The field contains one of the specified values

Text[,Text] [,Text]

hasAll

Text

The field contains all of the specified values

Text[,Text] [,Text]

before

Timecode

Timecode value is before than specified timecode

TcFmt, Frame

after

Timecode

Timecode value is after than specified timecode

TcFmt, Frame

between

Timecode

Timecode is between the two specified timecodes

TcFmt, Frame, Frame

before

Date

Date value is before than specified date

Date*

after

Date

Date value is after than specified date

Date*

between

Date

The date is between the two separated dates

Date, Date

older

Date

The date is older than the specified length of time

Seconds

newer

Date

The date is newer than the specified length of time

Seconds

*Date – dates are specified as a long integer that represents the number of milliseconds since 1/1/1970

Negating Operators (not)

The comparison operator may be prefixed with an exclamation mark (!) to negate the comparison. For example the query:

((clip.name)!contains(test))

Would return all clips whose name did not contain the string “test”.

Escaping Values

The value part of the clause contains the literal value enclosed in round brackets.

Strings do not have quotation marks around them. Strings that contain bracket characters should have the following substitutions applied:

Character

Escaped value

(

~28

)

~29

~

~7E

Password Encryption

The CatDV REST API uses RSA encryption to secure the transmission of passwords over the wire. For additional security a new public/private key pair is created for every session, with the private key being retained by the server and the public key being sent to the client. The client should encrypt the plain text password with the public key and send the encrypted value to the server, which then uses its private key to retrieve the original value.

RSA Encryption

For detailed information about the RSA algorithm please refer to RSA (algorithm) – Wikipedia. The core of the algorithm for encryption is

c = powMod(m, e, n);

Where:

e,n - the two large integer components of the public RSA key.

m - the message converted to a large integer.

C - the encrypted message as a large integer.

The values for ‘e’ and ‘n’ are extracted from the public key that is returned by:

GET /session/key

The public key is returned as two base36 encoded strings representing ‘n’ and ‘e’ separated by a ‘:’. For example:

The value of m is calculated by taking the UTF-8 encoded string that represents the password and treating it as a large integer where the first byte is the most significant.

nnux4mb561sc6o0gai3z5cvh051n8zwfktgjhzf1t5d2ihzh57t 89kq47lu3pgx93uwkbj5cdtbyyo82bar4iyd3e3swdjb2dhz:1ekh

The encrypted value ‘c’ is converted to base36 to give a string used as the encrypted password.