Cattura CaptureCast HTTP API v1 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:
Clients
The CaptureCast API Plugin automatically generates small client libraries for a handful of languages:
At the moment these bindings are single-file and not very well documented.
Methods
capture
Start a capture session
Stop a capture session
Pause a capture session
Resume a paused capture session
Device capture is available if at least one device capture plugin is installed.
Whether concurrent captures is enabled.
Returns the list of templates on this capture unit.
Returns a single template on this capture unit.
Performs a 10-second test of a capture template.
Creates or updates a template.
Returns a list of media packages on this unit.
Returns a single media package on this capture unit.
Attaches an output element to a media package.
Deletes a media package.
Publish a media package.
Test a publishing configuration.
Get tested configurations.
Update a configuration.
Update a configuration.
status
Obtain general information about the current state of the unit.
Get basic information about the unit.
Gets information about the network connectivity of the unit.
Gets the amount of free, usable, and total disk space.
Returns the current capture's state (idle, capturing, processing, etc)
Returns a listing of audio and video devices connected to this unit.
Returns all the scheduled captures for today.
graphBuilder
Returns a friendly wrapper for the graph builder API.
Return a list of all saved graphs.
Saves the current graph in memory to the filesystem.
Create a copy of an existing graph with a new root.
Construct a processor node and attach it to a graph.
Start a session at this graph location.
Stops a session at this graph location, if there is one.
Attach a node to one or more parents and/or children.
Retrieve the options for this node.
Configure the specified node.
Invokes a service of this Processor.
Get a single node from the graph.
Remove a node from the graph.
Get the complete JSON text of a graph.
Create an new graph with a root node.
settings
Returns a single setting for this unit.
Update a single setting on this unit.
Returns all settings for the unit.
Update multiple settings on the unit. Will not erase other settings
users
List out all users registered on this box.
maintenance
Perform a reboot of this capture unit.
Perform a restart of CaptureCast Pro.
Restarts only the media processing components
plugins
Returns a list of all plugins installed on the agent.
Retrieve user settings for a plugin.
Retrieve user settings for a plugin.
Invoke a service provided by a plugin
devices
Returns a listing of known audio devices.
Returns a listing of known video devices.
Redetect all devices on the unit.
Redetect all devices on the unit.
sessionStatus
Get the current status of each node in a capture session.
sessionOutput
For this specific node, get all files that it produced.
For this specific node, get a specific file it produced.
For each node, get all files that it produced.
scheduler
Schedule a capture
Update a scheduled capture
Get information about a scheduled capture. The return value resembles that returned from getEvents but with more details.
Get a set of scheduled captures matching certain criteria
Delete the event at the given id.
Schedule a group of captures
Update a group of captures
Get information about a group
Get a set of scheduled captures in the specified event group.
Delete group of captures, and all events it contains
speakers
List all speakers registered on the unit
Create a new speaker in the system
Update an existing speaker
Delete a speaker
liveStreamViewer
Get the preview for the current running recording.
Get the preview for a video device.
Get the preview for an audio device.
Create a preview for a video device.
Create a preview for an audio device.