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.
objectType: "KalturaAPIException" before treating a call as successful.Server
Authentication and playback manifest generation.
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.
Generates a scoped playback KS for a specific entry without exposing the admin secret. Required by Kaltura's App Token auth pattern - three steps:
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:
Thumbnails are set as <img src> directly - no API call needed. The KS is appended to the URL path for accounts requiring session auth.
KMC deep-link (opened on thumbnail click):
These calls are used once to configure Kaltura to send webhooks to your server - not called at runtime.
| Action | Purpose |
|---|---|
| listTemplates | Browse system-provided templates to find the right event type |
| clone | Create your own copy pointing at your server URL |
| updateStatus | Activate the cloned template (status 2 = ACTIVE) |
| dispatch | Manually fire a webhook against a specific entry for testing |
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.
Sync
Entry loading, metadata profile selection, and custom metadata editing.
Fetches the 10 most recently updated entries across all types to populate the quick-select entry picker sidebar.
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.
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.
XSD parsing notes:
xs:enumerationchildren on a field listbox with fixed allowed valuesmaxOccurs="unbounded"repeating text field (multi-value)xs:annotation > xs:documentationfield description
Fetches the existing metadata record for the selected entry + profile combination. Returns the xml field (current values) and the record id needed for updates.
Saves the full updated XML back to an existing metadata record. Always send the complete <metadata>...</metadata> document - there is no partial update.
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.
Taxonomy
Metadata profile browsing and taxonomy value management.
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).
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.
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.
Finds all entries carrying a specific taxonomy value before a rename or remove operation. Uses KalturaMetadataSearchItem in advancedSearch - the correct pattern for metadata-based entry search.
metadata_metadata/action/list for this - it requires a specific objectIdEqual and cannot search across all entries.For each entry found by the search above, fetches its metadata record to get the current XML and record id before patching.
Writes the patched XML back to each entry's metadata record. Processed sequentially - one entry at a time - to avoid rate limiting.
Playback
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).
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) | ✓ |