- For list of APIs and documentation of api_v3 - api_v3 API documentation.
- api_v2 is deprecated, please make use of api_v3 client libraries.
Overview
Kaltura API documentation provides information to web developers who wish to implement a direct usage of Kaltura's Application Programming Interfaces (APIs).
For gaining a wider understanding of Kaltura open source video platform, please review the Introduction to Kaltura Platform document.
Kaltura open source video platform exposes its Server API to be available, via a web services, layer, to web applications by implementing a standard HTTP POST/GET URL encoded requests structure.
Kaltura server API's, also named Kaltura Partner Services, are designed to follow REST principles. It consists of several service actions for querying/setting/updating/listing entities and for activating processes within Kaltura open source video Platform. Service actions are grouped according to the entity type they apply on, and provide all actions relevant to the specific entity.
This API documentation provides specific information on:
- Kaltura Services and their related actions
- Kaltura Objects and their related properties
- Kaltura Enumerated Types and their values.
A prerequisite for using Kaltura APIs is obtaining Kaltura partner identifiers, such as Partner ID. Learn more about obtaining Kaltura partner identifiers.
In addition to this documentation, Kaltura provides an API test console application, allowing developers to experience an actual usage of Kaltura API.
For additional support, please visit Kaltura Community Forum - APIs.
Request/Response structure
Request Structure
Kaltura API requests are standard HTTP POST/GET, URL encoded requests targeted to a specific API method. Each API method location is concatenated out of base URI, service and action identifiers strings, according to the following format:
where [SERVICENAME] represents the specific service and [ACTIONNAME] represent an action to be applied on the specific service.
For example, a request to activate the "list" action of the “media” service should be posted to the following URL:
Request Input Parameters
Each API method receives a different set of input parameters. For all request types:
- Input parameters should be sent as a standard URL encoded key-value string.
- When input parameter is an object, it must be flattened to pairs of ObjectName:Param keys.
- When date value is being passed as input parameter it should be passed as a standard timestamp integer.
Example:
Within this example the following parameters are being URL encoded and passed as API input parameters:
name = "name with spaces"
entry {
tag = "mytag",
description = "mydesc"
}
cdate = 1248086094 (timestamp representation)
Response Structure
Kaltura API response content is gziped by default (assuming client specifies it supports gzip).
Every response’s content is wrapped in an XML formatted container object, holding a
Successful Response
When Kaltura server executes an API request successfully, the
Example of Successful Response:
<xml>
<result>
<ResultProperty1>myValue1</ResultProperty1>
<ResultProperty2>myValue2</ResultProperty2>
</result>
<executionTime>0.28957796096802</executionTime>
</xml>
Error Response
When Kaltura server fails to execute a specific API request, an <error> element will be nested within response’s <result> element. The <error> element will hold information on response error code and the equivalent error message (The Errors are defined in the APIErrors class).
The following table lists few common general API error codes and their equivalent messages:
| Error Code | Error message |
|---|---|
| MISSING_KS | Missing KS. Session not established |
| INTERNAL_SERVERL_ERROR | Internal server error - An unexpected server error was encountered, refer to the kaltura log files (under logs folder) and apache logs files |
| INTERNAL_SERVERL_ERROR | Server error [%ERROR_DESCRIPTION%] |
| INVALID_KS | Invalid KS [%KS%]. Error [%KS_ERROR_CODE%,%KS_ERROR_DESCRIPTION%] |
| MANDATORY_PARAMETER_MISSING | Mandatory parameter missing [%PARAMETER_NAME%] |
Example of an error Response:
<result>
<error>
<code>MISSING_KS</code>
<message>Missing KS. Session not established</message>
</error>
</result>
<executionTime>0.28957796096802</executionTime>
</xml>
Notifications
Kaltura implements a set of HTTP POST notifications that could be sent upon specific media events to a URL on partners host servers.
The following notifications modes are supported and could be configured by partners at their account settings page within Kaltura Management console:
-
Server notifications
Notifications that are being sent, asynchronously, to a partner hosted URL, directly from Kaltura servers.
-
Client notifications
Notifications that are being sent to a partner hosted URL from Kaltura client components (kaltura widget) and are synchronized with widgets internal steps control.
Kaltura notifications provide partners with the following functionality:
- Ability to integrate with Kaltura technology in a way that is synchronized with media events occurring on Kaltura’s servers and/or with the internal steps control of Kaltura client components, when applicable.
- Ability to implement a synchronized local management instance of media related metadata and thumbnails for improving website performance. This may include local media searching and caching capabilities.
The API notifications table summarizes the different notification types and the parameters that are being included within each notification. For more information on the possible types of notifications is please review the KalturaNotificationType documentation page.
Additional Information
- Learn about the differences between api_v2 and api_v3, and learn how to use the TestMe Console - read the Kaltura API and TestMe Console Introduction.
- For further information on the API calls for Partner Services 2 (api_v2), please refer to the old wiki - Please note that api_v3 is deprecated and should be avoided.
- For further information on the API calls for Partner Services 3 (api_v3), please refer to the api_v3 API documentation.
- When you are ready for deployment, you can use one of the client libraries to easily perform the API callbacks in your programming language of choice - Refer to the Kaltura API Client Libraries Guide for more.
- If you use a CMS like Drupal, WordPress or MediaWiki... make sure to check the projects page for a relevant extension to your CMS of choice.
