BROWSE CATDV SUPPORT MANUALS

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

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:

Reply Object

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.

Payload Objects

Payload objects carry the actual data associated with a given endpoint method. As stated in the previous section, whenever the API returns data it is wrapped in a Reply object, and possibly a PartialResultSet object. However when data is sent to the server, as POST/PUT data in the HTTP request, no wrapper object is used, the message consists solely of the payload objects.

Catalog Object

Each catalog object contains the following fields

Field Type Description
ID Integer Unique ID of catalog
seq Integer Internal
userID Integer Unique ID of user that created this catalog
groupID Integer Unque ID of the production group this catalog belongs to
name String Catalog’s name
whoCreated String Name of creator
whoSaved String Name of person who last updated this catlog
owner String Name of catalog’s owner
comment String Free text comment field
whenCreated JSDate When this catalog was created
whenExtended JSDate When additional clips were last added to this catalog
whenSaved JSDate When this catalog was last saved
whenPublished JSDate 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

Clip Object

Each clip object contains the following fields

Field Type Description
ID Integer Unique ID of clip
catalogID Integer Unique ID  the catalog this clip belongs to
catalog Catalog(Partial) Information about the Catalog this clip belongs  (Read Only)
userID Integer Unique ID of user that created this clip
userName String Name of user that created this clip (Read Only)
clipref String User-settable external reference for this clip
type ClipType clip – standard (master) clip
sublcip – clip that represents a part of a master clip.
metaclip – complex clip that contains multiple component clips (e.g. P2).
still – a still image
imgseq – a sequence of still images
audio – an audio only clip.
seq
 – a rough-cut sequence
other – some other, non-media asset (e.g. PDF)
underlyingType String Detailed type description
name String Clip’s name
notes String Clip notes
bigNotes String Extended clip notes
importNotes String 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 Date of last modification
recordedDate JSDate 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 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
posterID Integer ID of thumbnail that acts as the poster for this clip
thumbnailIds* Integer[] 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 meteclip
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
userFields* Object An object that represents the customer metadata field values for this clip. The property names are the FieldDefinition identifiers for each field. Only non-blank values are present.

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

SourceMedia Object

Each SourceMedia object contains the following fields

Field Type 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 ration (width/height) of the media
modifiedDate JSDate 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
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.
metadata Object An object holding arbitrary metadata about this media object.

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 Description
ID Integer Unique ID of source media
file String Path of originally imported file
size Integer Size of the original files
modifiedDate JSDate Modification date of the original file
importedDate JSDate Date file imported
metadata 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.

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.
format String Tape format.
history String Tape history.
reelNumber String Tape reel number.
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.
userFields Object An object holding arbitrary metadata about this marker as key/value pair.
The keys are the FieldDefinition identifier for the relevant field

Timecode Object

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

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.

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.

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)