About

The Categories CSV is handy for creating, updating, or deleting numerous categories at once. It's useful for tasks like:

• Setting up multiple categories for Video Portal galleries and channels.
• Regularly syncing Kaltura categories with an external structure, like Video Portal group channels with organization-managed groups.
• Automatically syncing Kaltura categories with an external CMS taxonomy.

General guidelines

• Lines starting with # are ignored.
• The first line (fields definition) must start with * and list field names; include all mandatory fields.
• Each data row is a comma-separated list of values, in the same order as the header (fields definition line).
• Each row applies an action to one category.
• Submit via KMC (Upload menu) or by script using the API.
• The file is validated before processing; missing required fields cause the job to fail.
• Track jobs and download the original CSV and logs in Upload Control → Bulk Upload Log.
• Email notifications (status + log link) can be enabled by request.
• No line limit, but larger files take longer.
• Allowed special characters for text fields: - _ % ? . : ; & > @ ! $ ^ ~ = [ ] { } | <.
• See each schema for exceptions.

Schema description

Parameter	Mandatory / Optional	Description
action	Optional	Numeric value of the action to apply on a category. Supported values: 1 = Add, 2 = Update, 3 = Delete, 6 = Add or Update. You can mix different actions in one CSV. Only fields relevant to each action are applied.
name	Mandatory in add actions	Category name (text, max 60 characters). If the name includes the > character, it is automatically replaced with _.
relativePath	Optional	Category tree path where the category is located or should be created. Levels must be separated by >. Note: The path must already exist, or be created in an earlier CSV line, for processing to succeed.
categoryId	Optional	Kaltura’s internal, unique ID for the category. Used to identify a category for update or delete actions. Ignored for add actions.
referenceId	Optional	Identifier from an external system (text, max 512 characters). In update/delete actions, either categoryId or referenceId must be provided. In add actions, the value is stored in the new category. Note: Kaltura does not enforce uniqueness. To avoid conflicts, you should maintain unique values. If multiple categories share the same referenceId, update/delete will apply to only one.
tags	Optional	Comma-separated list of tags for the category, wrapped in quotes (e.g., "tag1, tag2"). Tags cannot include commas. Note: If you create the CSV in a text editor, you must add the quotes manually. Spreadsheet editors (like Excel) add them automatically.
description	Optional	Category description (unlimited text length). Recommended to wrap in quotes if it includes commas.
Custom Data	Optional	Custom fields can be populated using the format: metadata::schemaSystemName::fieldName. Multiple schemas/fields can be included. For multi-value fields, separate values with ` Note: Updating custom data creates a new metadata XML. To avoid overwriting values, include all custom data fields for the user in the update CSV.
privacy	Optional	Content privacy setting for the category. This option is available only if your account supports entitlements and the category is set with entitlement settings. Values: 1 = No Restriction, 2 = Requires Authentication, 3 = Private.
appearInList	Optional	Controls whether the category appears in lists. Available only if your account supports entitlements and the category is set with entitlement settings. Values: 1 = No Restriction, 3 = Private.
contributionPolicy	Optional	Defines who can add content to the category. Available only if your account supports entitlements and the category is set with entitlement settings. Values: 1 = No Restriction, 2 = Private.
inheritanceType	Optional	Determines whether end-user permissions are inherited from the parent category. Available only if your account supports entitlements and the category is set with entitlement settings. Values: 1 = Yes, inherit, 3 = No.
owner	Optional	User ID of the category owner (3–100 characters). Allowed special characters: . _ @ -.
defaultPermissionLevel	Optional	Default permission level granted to end users in the category, unless otherwise specified. Values: 0 = Manager, 1 = Moderator, 2 = Contributor, 3 = Member (default).
moderation	Optional	Indicates whether content must be moderated before being added to the category. Values: 0 = Moderation not required, 1 = Moderation required.

Examples

Bulk creation of categories (basic metadata only)

Updating existing categories with a few entitlement settings

This example uses the referenceId as the category identifier.