Introduction

The Cubix API provides access to both the orchestration and asset management layers of the Cubix platform - allowing you to query all elements of metadata stored within Cubix - as well as trigger processes, etc.

All operations return data in JSON format - with operations allowing you to specify an XML response if required. This data may, of course, be parsed into other formats (XML, HTML, Plain Text) or mapped to an object.

The API calls support URL routing so calls can be made using the following example;

Where action is subject of your request (Metadata, Item, etc.) and param1 is the first parameter passed and paramN can be any number of extra parameters that can be passed.


Examples:

  • http://api.cubix.tv/api/1/Item/12345
  • http://api.cubix.tv/api/1/Metadata/Date/10-11-2014/Episode
  • http://api.cubix.tv/api/1/Items

If a more conventional approach is required, query strings also work.

Examples:

  • http://api.cubix.tv/api/1/Item?id=12345
  • http://api.cubix.tv/api/1/Metadata?name=Date&value=10-112014&level=Episode
  • http://api.cubix.tv/api/1/Items

The Three Layers

Asset Management Layer

This is where all the digital and physical assets are managed, including all of their technical metadata (such as timecodes, file sizes, video codecs, audio codecs, etc.) as well as their editorial metadata. From an asset perspective, it knows where the assets are based on locations (and so can resolve path information) – and also contains information about any video proxies available. In addition to this, it also has a fully configurable hierarchical schema – allowing for configurable hierarchies on a per client basis (bearing in mind the Cubix stack is entirely multi-tenanted). The concept is that a hierarchy can be created (e.g. an episodic hierarchy would be normally 3 tiers – Product / Series / Episode) – and then metadata fields can be configured off the different tiers.


With the schema created, Mezzanine Files are then tagged under the final tier of the schema. Daughter files are associated with the mezzanine file, and so as such follow with the mezzanine file as it is tagged. Ancillary Files (e.g. images, subtitles, PDF, office documents, etc.) can be associated at any tier of the hierarchy and as such are inheritable down the nodes. The mezzanine file then inherits the metadata as soon as it is tagged – making it possible to have asynchronous workflows between media and metadata.

The metadata schema is configurable based around the Tiers of the hierarchy – with fields definable at each layer. These metadata fields can be strings, date ranges, key value pairs (e.g. actor name and character name), tables, dropdowns and more. The fields can also be offered in multiple languages. The metadata then by default inherits down the hierarchy – so that when an asset is tagged under the final tier – it effectively “looks up” through the hierarchy to see all the metadata relevant to them. A key benefit to this system is that metadata is only entered once – something which provides dividends when working with products that have 100s of episodes. Metadata can also override – so at a lower level, if a value needs to be overridden for that specific node and any subsequent child nodes – it can be. The hierarchies in Cubix are defined on a client basis – as they relate to the media. The associated metadata is created on a company basis – which means different companies (and the users therein) working with the content can see different schemas or scopes of schema. This provides natural flexibility for limiting what companies can see what metadata.


Automation Layer

This layer is where action take place with the different devices that Cubix supports (e.g. transcoders, storage devices, file based QC engines, etc.). The “node” based approach is that for every device we are controlling – a “harness” runs connecting in to the core system (either direct to the DB or via web service) and polls for jobs to complete. By design this layer has no decision logic – it simply looks for jobs, executes them – reporting back the progress of the job, as well as any errors and metadata. These jobs relate normally to an asset or set of assets, but there is no direct visibility given to these jobs via the API.


Orchestration Layer

In Cubix, we finally then have the orchestration layer, the element of Cubix that works with the asset management layer and other sources to drives actions within the automation layer to occur. We have two elements to the Orchestration layer – the first is “Media Rules”, and the second is “Taskflow”. Media Rules – are based around short process chains (e.g. if this, do that) – and allow for the system to be configured with the “common sense” of the facility. So knowing automatically when to archive a file, create a proxy, etc. This means that in any workflow design, these steps can be assumed rather than stated implicitly within the workflow. Taskflow – is our BPM system, in which tasks are spawned and then pass down fully configurable journeys. These journeys can then drive a wide range of activities, working with all of the automation layer, but also human stages such as QC and metadata capture, and then notifications, etc. Validation points can also be configured as part of the journey to check assets or metadata against configured rules. A task can contain as much payload data as required, and often makes reference to assets, the metadata schema and the automation jobs that it has requested. The task itself often contains payload data that are only used in a “pass-thru” sense (e.g. data that needs to be queried externally, but is not used as part of the taskflow itself). Via the API we provide access to the taskflow layer, but not the media rules layer.


Authentication Method

The API follows the same authentication methods as the Cubix portals, and so a set of valid authorised credentials are required to work with the API.


No calls can made to an action without proper authentication, you can use the username and password parameters for authentication.

Usage

The Cubix REST API supports JSON requests, and can return either JSON or XML responses


Questions

If you have any questions or need support involving the REST API, please contact support@ortana.tv for assistance.


About

GET - About

Gets information about the current version of Cubix API

GET http://< cubix-api-url>/api/1/about/
  • No parameters available for this command.

Ancillary File


Used for accessing Ancillary File data within Cubix

GET Ancillary File by (id)

Actions used for accessing Ancillary File data within Cubix

GET http://< cubix-api-url>/1/AncillaryFile/id
  • id Integer The identifier of the file

GET Ancillary File - By (id) (width) (height) (format)

Formats the image (the id) by the width and height provided. The images is then converted to the format required.

GET http://< cubix-api-url>/api/AncillaryFile/{id}/{width}/{height}/{format}
  • id Integer The identifier of the image
  • width Integer The width of the image
  • height Integer The height of the image
  • format String The new format of the image

Item


Used to process and retrieve specific Items within Cubix

GET Item - by (id) - more accurate when returning responses in JSON formats

Gets an asset from Cubix and Returns a single object with all available data

GET http://< cubix-api-url>/api/1/Item/{id}
  • id Integer The KVID of the clip

GET Item - by (id) - more accurate when returning responses in XML formats

Gets an asset from Cubix and Returns a single object with all available data

GET http://< cubix-api-url>/api/1/Item/{id}
  • id Integer The KVID of the clip.

Items


Used to retrieve Item collections from Cubix

GET Items - all

Used to retrieve Item collections from Cubix and get all available objects. Only core details are populated

GET http://< cubix-api-url>/api/1/Items/
  • No Parameters

GET Items by (Title)

Gets an Item by its Title. Returns the required Item, or null, if not available

GET http://< cubix-api-url>/api/1/Items/{title}
  • title String The Title of the Item to retrieve

GET items by (level)

Gets all Item objects belonging to requested level. Returns a collection of Item objects pertaining to the specified level

GET http://< cubix-api-url>/api/1/Items/{level}
  • level String The level of the expected Items (episode, series or product).

POST Items

Allows you to search on as many task data items as you wish to return a list of items. Multiple body values are accepted. Returns a collection of items objects

POST http://< cubix-api-url>/api/1/Items/search
  • metadataField Collection of strings expected to put field names in array format["ChannelName"].
  • metdataOperator Collection of strings expected to put operators in array format["="] .
  • metadataValue Collection of strings expected to put values in array format ["Endemol"].
  • output_MetadataField Collection of strings expected to put output fields in array format ["James"].

Metadata


Used to access the metadata associated at various tier levels within cubix

GET Metadata - by (key) (value) (level) (fullitems)

Gets all KVIDs for Item objects with the matching parameters or full item description if fullItems is set to true. Returns a List of KVIDs if fullItems parameter is set to false or list of items if fullItems parameter is set to true

GET http://< cubix-api-url>/api/1/metadata/{key}/{value}/{level}/{fullItems}
  • key String The key of the metadata item required.
  • value String The value stored in the named metadata item is required.
  • level Integer The level (Product = 1, Series = 2 or Episode = 3) that the item is attached to is required.
  • fullitems Boolean Boolean value true = all values associated with items, false = only IDs.

GET Metadata - by (Key)

Gets the options available to a metadata item. Used for items where a dropdown list may occur. All options available to a metadata item

GET http://< cubix-api-url>/api/1/metadata/{key}
  • key String The key of the metadata item required.

GET Metadata- by (Key) (Level)

Get all values for metadata key at a specific level (Product = 1, Series = 2, Episode = 3). Return Collection of key/value pairs where the key is item id and value is the associated value

GET http://< cubix-api-url>/api/1/Metadata/{key}/{level}
  • key String The key of the metadata item.
  • level Integer The level (Product = 1, Series = 2 or Episode = 3) that the item is attached to.

Metadata by (Key) (Value)

Get all options that depend on a metadata key and its possible value. A typical use case could be where a metadata key depends on the value stored in another metadata item. Return a collection of values that relate to the key and it's corresponding value

GET http://< cubix-api-url>/api/1/Metadata/{key}/{value}
  • key string The key of the metadata item .
  • value string The value stored in the key.

Taskflow


Used to retrieve Taskflow collections from Cubix

GET Tasks - by (taskid)

Used to retrieve Taskflow collections from Cubix. Returns all task data associated, or null, if not available

GET http://< cubix-api-url>/api/1/Task/{TaskId}
  • task_id Integer The keyword used to search by.

POST Task - more accurate when returning responses in JSON formats

Used to retrieve Taskflow collections from Cubix. Gets taskflow filter by using a generic filter Multiple values are accepted

POST http://< cubix-api-url>/api/1/Task/
  • TaskDataName String expected to put field names in array format["ChannelName"].
  • TaskDataOperator String expected to put operators in array format["="].
  • Taskdata_Value Integer expected to put values in array format ["Endemol"].
  • Output_TaskData_Name String expected to put output fields in array format ["James"].

POST Task/CreateTask by (TaskFlowID) (TaskTitle) (TaskNote) (StartDate) (RequiredDate) (FLE_ID)

Create a new Task

POST http://< cubix-api-url>/api/1/Task/CreateTask
  • TaskFlowID Integer
  • TaskTitle String
  • TaskNote String
  • StartDate String
  • RequiredDate String
  • FLE_ID Integer

POST Task/DeleteTask - by (TaskID) (TaskData_Name) (TaskData_Index)

Remove Task Data.

POST http://< cubix-api-url>/api/1/Task/DeleteTask
  • TaskID Integer
  • TaskData_Name String
  • TaskData_Index Integer

POST Task/AddEditTask by (TaskID) (TaskData_Name) (TaskData_Value) (mode) (TaskData_Index)

Used to Add or Edit Task Data.

POST http://< cubix-api-url>/api/1/Task/AddEditTask
  • TaskID Integer
  • TaskData_Name String
  • TaskData_Value Integer
  • mode Integer
  • TaskData_Index Integer

POST Task/Search by (TaskDataName) (TaskDataOperator) (Taskdata_Value) (mode) (Output_TaskData_Name)

Used to Search Taskflow Data

POST http://< cubix-api-url>/api/1/Task/{TaskId}
  • TaskDataName String expected to put field names in array format["ChannelName"].
  • TaskDataOperator String expected to put operators in array format["="].
  • Taskdata_Value Integer expected to put values in array format ["Endemol"].
  • Output_TaskData_Name String expected to put output fields in array format ["James"].

POST Task/Nextstep

Used to retrieve Taskflow collections from Cubix. Gets taskflow filter by using a generic filter Multiple values are accepted

POST http://< cubix-api-url>/api/1/Task/Nextstep
  • TaskID String The unique identifier for the task.
  • SuccessFail String values should be either "Success" or "Fail".
  • username String username
  • IPAddress String IPAddress
  • Notes String Notes
  • Dropdown_StepOrder Integer Dropdown_StepOrder
  • Dropdown_TST_ID Integer Dropdown_TST_ID

Search


Used to search for Item objects within Cubix

Search - by (keyword) (fullitems) (pageNumber) (pagesize) (orderby) (meta)

Gets all unique identifiers or all full items for the keyword for the current user

GET http://< cubix-api-url>/api/1/Search/{keyword}/{fullItems}/{pageNumber}/{pageSize}/{orderBy}/{meta}
  • keyword String The keyword used to search by.
  • fullItems Boolean true to return values associated with items, false returns IDs only
  • pageNumber Integer The number of the page to return.
  • pageSize Integer The number of results on the page to return.
  • orderBy String Item parameter by which items to be sorted in ascending order .
  • meta String Metadata key to by sorted by.

XML Packet


Used to receive a XML document (no specific structure required) for onward parsing and processing by Taskflow,

XML Packet

Post an order request or similar to our https endpoint, and will respond back in our standard schema confirming the order’s been received

POST 1/DigitalRiver
  • xmlPost String