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) |