REST API Reference

The REST API consists of a set of ‘endpoints’ (URLs such as /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>/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.