API Documentation

This document covers the API endpoints most commonly used when interacting with Flow Capture over REST.

You should read this document in conjunction with:

  1. The latest API documentation available here: moxion-api.html
  2. moxion_api_sample.py: a sample Python file that demonstrates calling the common Flow capture API endpoints and a full (although simple) implementation of uploading an asset to Flow Capture.

Important terminology note: "Projects" in the API refers to "Folders" in the UI, whilst "Groups" refer to "Productions" in the UI

API Integration

The following are our key API calls.


/authenticate/api Authenticate against the API, returning security token for subsequent calls.
/get/groups Get a (detailed) list of Productions from Flow Capture
/get/projects Get a (detailed) list of Projects from Flow Capture
/get/assets Get a (detailed) list of Assets from Flow Capture
/get/comments Load the comments for a Flow Capture Asset
/create/comment Create a new comment against a Flow Capture Asset
/delete/comment Remove a comment from a Flow Capture Asset
/upload/asset/init Initialize an upload process
/upload/asset/part Describe a file part to upload, and retrieve a URL to upload it to
/upload/asset/abort Aborts a multipart asset upload
/upload/asset/complete Complete the S3 upload process once all file parts have been uploaded
/complete/upload Final step to let Flow Capture know that there are no more new files coming in this upload session so that MFlow Capture oxion can complete the processing and trigger appropriate upload notifications
/update/asset Upload asset metadata

Authentication

The Flow Capture REST integration requires a Flow Capture user to be set up and configured, with permissions established. Contact Flow Capture support to have an appropriate user created. 

Calls to the REST/HTTPS API will "act as" this user. Note that the permissions of this user control the visibility response objects in the API calls (in Flow Capture , Project and Asset permissions are stored per-user). Therefore, it may be advisable to set up a dedicated Flow Capture API user for each integration, in order to properly control access to Flow Capture .

In order to get started with the HTTPS API, you will need to know:

  • The email address of the API user.
  • The API key of the API user. To get this, please follow the instructions found here


All API calls require a security token. To get this, call /authenticate/api.

Basic Asset Operations

Before you begin:

  • Authenticate with the API through the /authenticate/api endpoint, as previously discussed.

Browsing the Hierarchy

Assets live within Projects, which live within Productions. In order to upload an asset, a Project ID must be ascertained. 

To load the hierarchy and find an appropriate project:

  • Productions may be browsed through the /get/groups API call. All productions visible to the authenticated API user will be returned.
  • Projects within a production may be browsed through the /get/projects endpoint. Again, the permissions of the user control which projects are returned.Projects may be nested within other projects (in this case the parent_project_id field will be set to a value to indicate the ID of the parent project)

Working with Assets in a Project

  • Assets visible within a project may be browsed through the /get/assets endpoint. 
  • The /get/comments, /create/comment and /delete/comment endpoints are used to view, create and remove comments against an asset.

Identifying Assets

The endpoint calls accept either an Asset ID or an Asset UUID to uniquely identify an Asset.

  • Asset IDs are automatically generated when the Asset is created. Each Asset has its own unique Asset ID, generated by the server. This value will be different from the Asset UUID.
  • Asset UUIDs are specified at upload time by the software controlling the upload. Asset UUIDs must follow the format d0e07781-da0f-4d86-9f99-9ebaca8002ef and must include the dashes. 

All the asset- or comment-related endpoints mentioned in this document will transparently accept either an Asset ID (ie a unique ID generated by the server) or an Asset UUID (a unique ID generated by the uploader).

For integration uses, it is typical that an Asset UUID is specified at upload time, and that Asset UUID is used in subsequent calls to the API.

Uploading Assets

Add assets to Flow Capture .

Upload API Overview

To perform a multi-part S3 upload to a new Flow Capture Asset, complete the following steps:

  1. Call /upload/asset/init to initialize a file upload into a designated project
  2. Split your file into parts and retrieve upload URLs by calling /upload/asset/part for each part
  3. Upload the data to the given URLs, retaining the ETags from each PUT request
  4. Complete the S3 upload process by calling /upload/asset/complete
  5. After triggering ingest processing for all the files call /complete/upload as a final step to let Flow Capture know that there are no more new files coming in this upload session. Flow Capture will complete the processing and trigger appropriate upload notifications

The upload consists of:

For an example of a valid S3 multipart upload, see the accompanying Python script.  

Upload Caveats

For an overview of the S3 multipart upload used by Flow Capture , see https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html

When uploading file parts via PUT requests, these requests must be accompanied by a content-md5header with the corresponding MD5 in base-64 format. The value in this header must also match the value of the content_md5 parameter in the call to /upload/asset/part.

The Python script has a simple reference implementation which follows the above steps, uploads a file to S3 and creates a Flow Capture Asset from the upload.

Upload API Details

Upload init

In order to begin uploading to S3 you will need to initiate the upload by calling /upload/asset/init with the name of the file to upload, and the project_id that was returned in the authentication phase. This call will return details that you need to persist throughout the upload process: upload_id and key.

Call this process once, at the beginning of the upload flow.

Request Parameters:

Name Description Required Comments
project_id The ID of the Flow Capture folder ("project") to upload the asset to.  No Typically obtained via the auth process. Can also be extracted easily from the URL of the Flow Capture Webapp when in the Viewer tab. Your user must have upload rights to this folder. This parameter is not required if the user is authenticated via an immediates connection (such as that created by a call to /create/connection/immediates). In this case, the project_id will be extracted from the auth token. In all other usages, the project_id must be specified here as a request parameter.
filename Name of the file to be uploaded Yes Display name, as shown in Flow Capture .

Response Parameters:

Name Description Comments
upload_id Opaque ID of the upload, as issued by S3. Retain this ID, as it will be used by the other calls in this upload flow.
key Opaque key of the upload, as issued by Flow Capture . Retain this ID, as it will be used by the other calls in this upload flow.
Upload part
Split the file into parts of at least 5MiB each (maximum 10,000 chunks). For each chunk, call /upload/asset/part with the details of the upload_id, key and part number. This call will return a presigned url for you to use to PUT the file to S3. You will be required to send an additonal header with the PUT request: content-md5
Call this endpoint for each part. You may upload multiple concurrent parts at once.  

Request Parameters:

Name Description Required Comments
upload_id Upload ID, as returned by the /upload/asset/init call. Yes
key Upload key, as returned by the /upload/asset/init call. Yes
part_number The part number, starting from 1. Yes Indicates which part you're uploading. Part numbers are sequential from 1 to 10,000.
content_md5 Base-64 encoded MD5 has generated from this part's data. Yes Used to verify that the file being arrived unmodified and uncorrupted.

Response Parameters:

Name Description Comments
presigned_url The URL to put the data to.

Use your HTTP library of choice to PUT the part to the given URL. cURL will be fine.

This URL is only valid for five minutes from issue, so do not let too much time elapse between calling the endpoint and actually putting the data.
Retain the ETags from the PUT requests. You will need them for the next step. 
Each PUT request must include a content-md5 header, which contains the base-64 MD5 hash of the part's data. This is the same value as passed to the endpoint.
Upload complete
After all parts have been successfully PUT, call /upload/asset/complete to complete the S3 upload

Request Parameters:

Name Description Required Comments
upload_id Upload ID, as returned by the /upload/asset/init call. Yes
key Upload key, as returned by the /upload/asset/init call. Yes
etags An array of ETags, captured from the PUT requests.  Yes ETags must appear in this array in the part_number order, part 1 first.
filename Display name of the file. Yes Must match the filename provided in the /upload/asset/init call.
project_id Folder ("project ID") No Must match the project_id provided in the /upload/asset/init call. This parameter is not required if the user is authenticated via an immediates connection (such as that created by a call to /create/connection/immediates). In this case, the project_id will be extracted from the auth token. In all other usages, the project_id must be specified here as a request parameter.
batch_name The name of the Flow Capture batch to upload to. No Batches are named groups of assets within a folder. You may optionally provide a batch name. If you do not provide one, assets will appear in the "Untitled Batch".

Response Parameters:

Name Description Comments
asset_id The (preallocated) Flow Capture Asset ID of the asset which will be processed and created. This Asset will not be available via the API or UI until the final step has been run.
Abort upload
An upload can be aborted during the process by calling /upload/asset/abort.

Request Parameters:

Name Description Required Comments
upload_id Upload ID, as returned by the /upload/asset/init call. Yes
key Upload key, as returned by the /upload/asset/init call. Yes




Ingest the Uploaded file and create the Flow Capture Asset
Once the S3 upload has completed, call /complete/upload. This tells Flow Capture to ingest the uploaded asset(s), transcode/process them as appropriate and make them available to users. Depending on the size of the file and current loading on the server this can take anywhere from a few seconds to a minute for typical length immediates.

Request Parameters:

Name Description Required Comments
project_id Folder ("project ID") No Must match the project_id provided in the /upload/asset/complete call. This parameter is not required if the user is authenticated via an immediates connection (such as that created by a call to /create/connection/immediates). In this case, the project_id will be extracted from the auth token. In all other usages, the project_id must be specified here as a request parameter.
batch_name The name of the Flow Capture batch to upload to. No Must match the batch provided in the /upload/asset/complete call
keys Array of keys corresponding the files to be processed Yes The key field from the /upload/asset/complete call. This call does not require an upload_id at this stage.

Response Parameters:

Name Description Comments
ok boolean True if the file has been queued for ingestion.

Update Metadata

Update asset with tags and metadata.

/update/asset

Parameters:


id The asset ID or UUID
tags Set the tags for the asset
* Will accept any key->value data to be applied to the assets metadata

The response consists of a JSON structure containing the following:

updated True if the asset was updated

Get Comments

Fetch the comments against an asset.

Request:


asset_id The asset ID or UUID

The response consists of an array in the following format, one JSON object per comment. The array is sorted in time order, earliest first. 

id The comment ID
description Text of the comment (plain text, no HTML markup)
color Color of the comment marker on the transport control. In the format #ff00ee
has_marker Is this comment associated with a marker on the timeline?
marker_time Time of the comment, in seconds. Floating point.
has_drawing Does this comment have an associated drawing?
is_reply Is this a reply?
parent_id If this is a reply comment, the ID of the parent comment.
has_reply Does this comment have any child replies?
asset_id ID of the parent asset
project_id ID of the parent project
type COMMENT: plain text commentIO_POINT: these should be ignored
user_first_name First name of the commenter
user_last_name Last name of the commenter

Create Comment

Add a text comment against an asset.


asset_id The asset ID or UUID
description Text of the comment (plain text, no HTML markup)
color Color of the comment on the transport control. In the format #ff00ee
is_reply True if this comment is a reply to another comment. Comments may be nested indefinitely.
parent_comment_id If this is a reply, the ID of the parent comment
has_marker Is this comment associated with a marker on the timeline?
marker_time Time of the comment, in seconds. Floating point

Returns a single object, following the same format as that returned by the /get/comments endpoint.

Update Comment

Modify an existing comment.

id ID of the comment to modify
description Text of the comment (plain text, no HTML markup)
color Color of the comment on the timeline. In the format #ff00ee
is_reply True if this comment is a reply to another comment. Comments may be nested indefinitely.
parent_comment_id If this is a reply, the ID of the parent comment
has_marker Is this comment associated with a marker on the timeline?
marker_time Time of the comment, in seconds. Floating point.

Returns a single object, following the same format as that returned by the /get/comments endpoint.

Delete Comment

Remove a comment.

id ID of the comment to remove

Returns a JSON object in the following format:

deleted Was this asset successfully removed

Download Assets

Assets and their proxies can be made available for download via HTTPS.
The basic steps are:

  • Determine the Asset IDs for the assets you wish to download
  • Obtain the categories (categories represent different proxies for the asset, for example 480p, 720p, 1080p, ORIGINAL) (/get/asset/file/categories)
  • Start the processing step for the assets and the set of categories that you want to download (/download/assets/direct)
  • Receive a list of download tasks. Note some processing may be required to ready the files for download, e.g. to watermark the file. (response from /download/assets/direct)
  • Monitor the tasks until they stop processing and download URL is provided (ready). (/get/tasks/message)
  • Do an https download of each URL as it becomes ready.

Key Endpoints

  • /get/asset/file/categories
  • /download/assets/direct
  • /get/tasks/message

Endpoint Definitions

Endpoint: /get/asset/file/categories

Get list of unique asset file categories for the provided assets from either the list of assets or the playlink id

Token Required: Yes

Array Response: NoRequest Parameters

Parameter Required Type Description Constraints
assets No IdArray
Array of asset IDs
Valid IdArray
playlink_id No Id
Playlink ID of the assets
Valid Id

Response Parameters

Parameter Type Description
file_category StringArray
List of unique file categories
file_count Object
File counts by file types
group Object
Group of category, to be shown on the front end.
non_watermarked Boolean
User can download non watermarked files
non_watermarked_file_sizes Object
File size by file types (bytes). Used when non-watermarked is selected in the UI.
sort_order Object
Sort order by file type.
watermarked_count Object
Number of files for each category that can be watermarked
watermarked_file_sizes Object
File size by file types for watermarked files (bytes). Watermarked files are assumed to be slightly larger than non-watermarked files.

Endpoint: /download/assets/direct

Download assets directly without ZIP when there are multiple files to download

Token Required: Yes

Array Response: YesRequest Parameters

Parameter Required Type Description Constraints
assets No IdArray
Array of asset IDs
Valid IdArray
file_categories No StringArray
Array of categories to download
Valid StringArray
non_watermarked No Boolean
Download a non watermarked version of these files (requires appropriate permission)
Valid Boolean

Response Parameters

Parameter Type Description
errors json array
List of errored assets that could not begin processing.
successful_processes json array List of tasks ready or processing for file downloads.

The errors array is a json array of objects with the following fields:

Parameter Type Description
asset_id Id
Asset Id for this entry
error_message String Description of the error that occurred (e.g. Permissions error)
The task array is a json array of objects with the following fields:

Parameter Type Description
asset_id Id
Asset Id for this entry
filename String
filename for this entry
path String
The file path
processing Boolean
True if file is being generated, progress information provided by task_id
task_id String
The processing task related to this batch of assets

url



 String
Link to download the file if not processing

Endpoint: /get/tasks/messages

Get the most recent task status message for the specified tasks.

Token Required: Yes

Array Response: YesRequest Parameters

Parameter Required Type Description Constraints
task_ids Yes IdArray
Array of task IDs
Valid IdArray

Response Parameters

The response is an array of json objects with the following fields

Parameter Type Description
task_id Id
Processing task Id for this entry
message json object

object with the following fields:

  • progress     String representing the processing progress
  • direct_url.   String download URL provided when processing is complete