Cattura CaptureCast HTTP API Documentation


 


Introduction


The Cattura CaptureCast HTTP API allows you to control CaptureCast programatically. This can be used for example to integrate it with third-party platforms.


 


Authentication


Some API methods require authentication. At the moment, authentication to the API is performed using HTTP Basic Authentication, supplying the username and password of a user with the required permissions. In the future, we will support API token authentication.


If the documentation for the method does not state that it requires "any valid user" or that it requires specific permissions, then the method does not require any authentication.


Authorization and Permissions


Some API methods, in addition to requiring authentication, also require that the user has the correct permission to use the method. The user roles, and their associated permissions, are:



  • Administrator: all permissions

  • Scheduler: view, manage schedule

  • Content manager: view, manage media

  • Status viewer: view

  • Presenter: view

  •  


API URLs


URLs exposed by the API generally represent resources (such as templates or media packages) or actions (such as start capture or stop capture). API URLs sometimes require parameters such as {id}; these URLs follow the URI Templates format (see also RFC 6570).


Resource URLs


For a type of "thing" (for example "template," "mediaPackage," "speaker," etc.), URLs generally take the following forms:



  • /api/things


    • GET results in a listing of things.

    • POST results in a new thing being created.


  • /api/things/{id}


    • GET returns the thing indicated by id.

    • POST updates the thing indicated by id.

    • DELETE deletes the thing indicated by id.

    •  



Request Data


Request data is sent as Content-Type: application/x-www-form-urlencoded, which is the same data serialization used in HTML forms. Values for invididual parameters may either be primitive values or JSON-encoded objects.


 


Object Types


In addition to JSON data types such as string, number, array, and object, the CaptureCast platform also has types of objects specific to it. These include:



  • CaptureRequest

  • MediaPackage

  • Template

  • Speaker

  • User

  • PublishRequest

  • Event

  • Element and related types

  • Graph

  •  


Clients


The CaptureCast API Plugin automatically generates small client libraries for a handful of languages:



  • Java (note: The default serializer implementation uses Jackson ObjectMapper, but can be swapped with a different JSON implementation)

  • Python


At the moment these bindings are single-file and not very well documented.


 


Methods


 


capture


startCapture


Start a capture session


stopCapture


Stop a capture session


pauseCapture


Pause a capture session


resumeCapture


Resume a paused capture session


getTemplates


Returns the list of templates on this capture unit.


getTemplate


Returns a single template on this capture unit.


testTemplate


Performs a 10-second test of a capture template.


createTemplate


Creates or updates a template.


getMediaPackages


Returns a list of media packages on this unit.


getMediaPackage


Returns a single media package on this capture unit.


attachToMediaPackage


Attaches an output element to a media package.


publishMediaPackage


Publish a media package.


testPublisherConfiguration


Test a publishing configuration.


getSavedConfigurations


Get tested configurations.


updateSavedConfiguration


Update a configuration.


deleteSavedConfiguration


Update a configuration.


 


graphBuilder


listGraphs


Return a list of all saved graphs.


save


Saves the current graph in memory to the filesystem.


copy


Create a copy of an existing graph with a new root.


createNode


Construct a processor node and attach it to a graph.


startCapture


Start a session at this graph location.


stopCapture


Stops a session at this graph location, if there is one.


linkNode


Attach a node to one or more parents and/or children.


nodeOptions


Retrieve the options for this node.


configureNode


Configure the specified node.


invokeService


Invokes a service of this Processor.


getNode


Get a single node from the graph.


removeNode


Remove a node from the graph.


getGraph


Get the complete JSON text of a graph.


make


Create an new graph with a root node.


 


status


getUnitStatus


Obtain general information about the current state of the unit.


getUnitInfo


Get basic information about the unit.


getNetworkInfo


Gets information about the network connectivity of the unit.


getDiskSpaceInfo


Gets the amount of free, usable, and total disk space.


getCaptureState


Returns the current capture's state (idle, capturing, processing, etc)


getConnectedDevices


Returns a listing of audio and video devices connected to this unit.


getTodaysSchedule


Returns all the scheduled captures for today.


 


scheduler


createEvent


Schedule a capture


createEventGroup


Schedule a group of captures


updateEvent


Update a scheduled capture


getEvent


Get information about a scheduled capture. The return value resembles that returned from getEvents but with more details.


getEvents


Get a set of scheduled captures matching certain criteria


 


settings


getSetting


Returns a single setting for this unit.


setSetting


Update a single setting on this unit.


getSettings


Returns all settings for the unit.


setSettings


Update multiple settings on the unit. Will not erase other settings


speakers


getSpeakers


List all speakers registered on the unit


createSpeaker


Create a new speaker in the system


updateSpeaker


Update an existing speaker


deleteSpeaker


Delete a speaker


 


users


getUsers


List out all users registered on this box.


 


maintenance


reboot


Perform a restart of this capture unit.


 


plugins


getPlugins


Returns a list of all plugins installed on the agent.


getSettingsForPlugin


Retrieve user settings for a plugin.


setSettingsForPlugin


Retrieve user settings for a plugin.


callPluginService


Invoke a service provided by a plugin


 


sessionStatus


allNodes


Get the current status of each node in a capture session.


 


devices


getAudioDevices


Returns a listing of known audio devices.


getVideoDevices


Returns a listing of known video devices.


redetect


Redetect all devices on the unit.


redetectProgress


Redetect all devices on the unit.


 


sessionOutput


forNode


For this specific node, get all files that it produced.


getFile


For this specific node, get a specific file it produced.


forAllNodes


For each node, get all files that it produced.