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 |
| userID | Integer | Unique ID of user that created this clip |
| thumbnailIds* | Integer[] | Array of unique IDs of all the thumbnails associated with this clip |
| posterID | Integer | Unique ID of thumbnail that acts as the poster 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) |
| name | String | Clip’s name |
| notes | String | Clip notes |
| tape | String | Tape name |
| status | String | User defined status of this clip |
| format | String | Human readable description of media format |
| in | Timecode | Timecode of start of clip |
| out | Timecode | Timecode of end of clip |
| in2 | Timecode | Timecode of start of selection within the clip |
| out2 | Timecode | Timecode of end of selection within the clip |
| duration | Timecode | Timecode representing total duration of the clip |
| mediaStart | Timecode | Timecode of the start of the associated source media |
| mediaEnd | Timecode | Timecode of the start of the associated source media |
| clipref | String | Unique reference number of this clip |
| bin | String | Name of bin this clip is in |
| fps | Float | Frames per second |
| modifiedDate | JSDate | Date of last modification |
| recordedDate | JSDate | Date when this clip was recorded |
| sourceMediaID | Integer | Unique ID of the source media associated with this clip |
| media | SourceMedia | The associated SourceMedia Object – if present |
| markers* | EventMarker[] | Array of event markers defined on this clip. |
| history* | History[] | History of changes made to this clip. |
| userFields* | Object | An object that represents the User Field values set for this clip. The property names are in the for U1, U2 etc. Only non-blank values are present. |
| seqItems* | SequenceItem[] | (Sequences only) The items in the sequence |
* This field is only populated when an individual clip is retrieved – or when explicitly requested in the include parameter of a clip query..
SourceMedia Object
Each SourceMedia object contains the following fields
| Field | Type | Description |
|---|---|---|
| ID | Integer | Unique ID of source media |
| start | Integer | Start frame number |
| end | Integer | End frame number |
| tcFmt | Integer | Timecode format. One of a fixed set of known values, but based on the frame rate e.g. 24, 25, 2997 |
| filePath | String | Path of original media file |
| fileSize | Integer | Size of original media file in bytes |
| videoFormat | String | Human readable description of video format |
| audioFormat | String | Human readable description of audio format |
| tapeInfo | String | Descriptive information about the source tape |
| metadata | Object | An object holding arbitrary metadata about this media 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. |
EventMarker Object
Each EventMarker 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. |
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. |
| 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) |