This section gives details of each API endpoint and details the methods supported, the parameters supported and the results that will be returned.
Endpoint: /session
Gives access to the current HTTP session.
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:
Property | Type | Description |
username | String | Username of authenticating user |
password | String | Plain text password |
encryptedPassword | String | RSA Encrypted password |
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:
GET /catalogs
Returns an array of all the catalogs on the server.
GET /catalogs/<id>
Returns the catalog with the specified id
Endpoint: /clips
Represents the collection of all catalogs on the server:
GET /clips?filter=<filter>[&fetchRelated=<fetch_related>&include=<include>&skip=<skip>&take=<take>]
Returns a PartialResultSet of the clips that match the filter criteria. For details of the formats of the filter, fetch_related and include parameters see section “Clip Query Filter Syntax” for more details.
GET /clips?smartfolderID=<id>[&include=<include>&skip=<skip>&take=<take>]
Returns a PartialResultSet of the clips contained within the specified smart folder.
GET /clips?catalogID=<id>[&include=<include>&skip=<skip>&take=<take>]
Returns a PartialResultSet of the clips contained within the specified catalog.
GET /clips/<id>
Returns the clip with the specified id
PUT /clips/<id>
Update selected fields of the clip with the specified id. HTTP POST data should contain a partially populated clip object.
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.
POST/clips
Add a new clip. The new clip must specify the catalogID for a valid, accessible catalog that the clip will be added to.
Writeable Clip Fields
The following clip fields can be set/updated:
- catalogID
- name
- typeID
- tape
- notes
- bin
- status
- marked
- rating
- clipRef
- sourceMediaID
- importSourceID
- posterID
- in/out and in2/out2
- markers
- user fields
In future versions of the API this set may be expanded.
Endpoint: /sourcemedia
Represents the collection of SourceMedia objects
GET /sourcemedia/<id>
Returns the SourceMedia object with the specified id.
GET /sourcemedia/<id>/thumbnails
Returns the thumbnails associated with the specified SourceMedia object.
Endpoint: /thumbnail
Gives access to individual thumbnails stored on the server:
GET /thumbnail/<id>
Returns the actual image data for the thumbnail with the specified id. The reply will have an appropriate MIME type such as image/jpeg.
Endpoint: /media
Gives access to the actual media stored on the server.
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.
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
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.