Kaltura Workflows - Developer Guide

Every Kaltura API call used across the Async, Sync, and Taxonomy apps - with context, parameters, and gotchas - to help you build your own integrations on the same foundation.

Base URL: https://www.kaltura.com/api_v3 format=1 JSON Auth: ks= param
All API calls return HTTP 200 even on error. Always check the response body for objectType: "KalturaAPIException" before treating a call as successful.
Full Kaltura API Reference

Server

Authentication and playback manifest generation.

session/action/get

Validates the KS supplied by the user and extracts session metadata (partnerId, userId, expiry, privileges). The server gates all webhook processing on a valid activated session - no KS, no events buffered.

POST /service/session/action/get ks={ks}&format=1
Session (KS) Guide
session/action/startWidgetSession + appToken/action/startSession

Generates a scoped playback KS for a specific entry without exposing the admin secret. Required by Kaltura's App Token auth pattern - three steps:

# Step 1 - anonymous widget KS POST /service/session/action/startWidgetSession widgetId=_{partnerId}&expiry=999&format=1 # Step 2 - sign it (Node.js) crypto.createHash('sha256').update(widgetKs + APP_TOKEN).digest('hex') # Step 3 - scoped user KS POST /service/appToken/action/startSession ks={widgetKs}&id={appTokenId}&tokenHash={hash} &sessionPrivileges=sview:{entryId},disableentitlementforentry:{entryId} &format=1
AppTokens API

Async

The Async page makes no Kaltura API v3 calls at runtime. It displays webhook events received via webhooks. Two Kaltura URLs are constructed without an API call:

Thumbnail URL (CDN - no fetch)

Thumbnails are set as <img src> directly - no API call needed. The KS is appended to the URL path for accounts requiring session auth.

https://cdnapisec.kaltura.com/p/{partnerId}/thumbnail/entry_id/{entryId}/width/{width}/ks/{ks}

KMC deep-link (opened on thumbnail click):

https://kmc.kaltura.com/index.php/kmcng/content/entries/entry/{entryId}/metadata
Thumbnail & Image API
eventnotification_eventnotificationtemplate - setup only

These calls are used once to configure Kaltura to send webhooks to your server - not called at runtime.

ActionPurpose
listTemplatesBrowse system-provided templates to find the right event type
cloneCreate your own copy pointing at your server URL
updateStatusActivate the cloned template (status 2 = ACTIVE)
dispatchManually fire a webhook against a specific entry for testing
Webhook verification: Incoming requests include X-KALTURA-SIGNATURE. Verify as SHA256(signingSecret + rawBody) - plain string concat, not HMAC. Always return HTTP 200 immediately; Kaltura retries up to 10 times over ~24 hours on non-200 responses.
Event Notifications (Webhooks)

Sync

Entry loading, metadata profile selection, and custom metadata editing.

baseentry/action/list

Fetches the 10 most recently updated entries across all types to populate the quick-select entry picker sidebar.

POST /service/baseentry/action/list ks={ks}&format=1 &filter[orderBy]=-updatedAt &pager[pageSize]=10
Upload & Ingestion API
baseentry/action/get

Fetches the full entry object - title, description, owner, media type, status, duration, tags, thumbnail URL, created/updated dates. Called when the user loads an entry by ID or selects from the picker.

POST /service/baseentry/action/get ks={ks}&entryId={entryId}&format=1
metadata_metadataprofile/action/list

Fetches all metadata profiles for the partner to populate the profile dropdown. The xsd field on each profile is parsed client-side to determine field types and allowed values.

POST /service/metadata_metadataprofile/action/list ks={ks}&format=1

XSD parsing notes:

  • xs:enumeration children on a field listbox with fixed allowed values
  • maxOccurs="unbounded" repeating text field (multi-value)
  • xs:annotation > xs:documentation field description
Custom Metadata API
metadata_metadata/action/list

Fetches the existing metadata record for the selected entry + profile combination. Returns the xml field (current values) and the record id needed for updates.

POST /service/metadata_metadata/action/list ks={ks}&format=1 &filter[objectIdEqual]={entryId} &filter[metadataProfileIdEqual]={profileId} &filter[metadataObjectTypeEqual]=1
metadata_metadata/action/update

Saves the full updated XML back to an existing metadata record. Always send the complete <metadata>...</metadata> document - there is no partial update.

POST /service/metadata_metadata/action/update ks={ks}&format=1 &id={metadataRecordId} &xmlData={xmlString}
metadata_metadata/action/add

Creates a new metadata record when none exists yet for the entry + profile pair. Always call metadata_metadata/action/list first - use add only when the list returns empty.

POST /service/metadata_metadata/action/add ks={ks}&format=1 &metadataProfileId={profileId} &objectType=1 &objectId={entryId} &xmlData={xmlString}
Custom Metadata API

Taxonomy

Metadata profile browsing and taxonomy value management.

metadata_metadataprofile/action/list

Loads all metadata profiles on page load. Profiles are filtered to show only those containing at least one listbox field (a field with xs:enumeration values in its XSD).

POST /service/metadata_metadataprofile/action/list ks={ks}&format=1&pager[pageSize]=500
metadata_metadataprofile/action/get

Fetches a single profile including its full xsd immediately before any taxonomy edit (rename, add value, remove value) to ensure the XSD being modified is current.

POST /service/metadata_metadataprofile/action/get ks={ks}&format=1&id={profileId}
metadata_metadataprofile/action/update

Pushes the modified XSD back to the profile after a taxonomy edit (rename, add, or remove enumeration value). Requires both metadataProfile[objectType] and xsdData as separate parameters.

POST /service/metadata_metadataprofile/action/update ks={ks}&format=1&id={profileId} &metadataProfile[objectType]=KalturaMetadataProfile &xsdData={newXsdString}
Custom Metadata API
metadata_metadata/action/list

For each entry found by the search above, fetches its metadata record to get the current XML and record id before patching.

POST /service/metadata_metadata/action/list ks={ks}&format=1 &filter[objectIdEqual]={entryId} &filter[metadataProfileIdEqual]={profileId} &filter[metadataObjectTypeEqual]=1
metadata_metadata/action/update

Writes the patched XML back to each entry's metadata record. Processed sequentially - one entry at a time - to avoid rate limiting.

POST /service/metadata_metadata/action/update ks={ks}&format=1 &id={metadataRecordId} &xmlData={patchedXmlString}

Playback

playManifest (CDN endpoint)

Returns an HLS manifest for a given entry. This is a CDN endpoint, not an API v3 service - it returns the manifest stream directly. Requires a scoped KS with sview privilege on the entry (see App Token flow above).

GET https://cdnapisec.kaltura.com/p/{partnerId}/sp/{partnerId}00/ playManifest/entryId/{entryId}/format/applehttp/protocol/https/a.m3u8 ?ks={scopedKs}
Content Delivery API

Quick Reference

API Call Async Sync Taxonomy
session/action/get
session/action/startWidgetSession
appToken/action/startSession
baseentry/action/list
baseentry/action/get
metadata_metadataprofile/action/list
metadata_metadataprofile/action/get
metadata_metadataprofile/action/update
metadata_metadata/action/list
metadata_metadata/action/add
metadata_metadata/action/update
playManifest (CDN)