---
title: Overview
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/custom-metadata-overview
---

## Custom Metadata Overview

The Custom Metadata API lets you define XSD-based schemas (metadata profiles) and attach structured XML data to entries, categories, users, partners, or user-entry records. Schemas support typed fields with annotations that control KMC rendering, eSearch indexing, and UI behavior. An optional XSLT pipeline transforms metadata on every add/update.

**Base URL:** `https://www.kaltura.com/api_v3` (may differ by region/deployment)  
**Auth:** KS passed as `ks` parameter in POST form data (see [Session Guide](/docs/getting-started/authentication/ks-overview))  
**Format:** Form-encoded POST, `format=1` for JSON responses  
**Services:** `metadata_metadataProfile` (10 actions), `metadata_metadata` (9 actions)  

**Important:** These are plugin services. The service names use underscore-prefixed compound names: `metadata_metadataProfile`, `metadata_metadata`.

### When to Use


- **Content classification systems** attach domain-specific fields (department, project code, sensitivity level) to entries for structured filtering and reporting.  
- **Regulatory compliance workflows** store audit metadata such as retention dates, legal hold flags, and approval status directly on content objects.  
- **Custom search and discovery** extend eSearch with business-specific filterable fields so users can find content by custom taxonomies and tags.  
- **Automated content pipelines** use metadata profiles with XSLT transformations to normalize, enrich, or validate metadata on every add or update.



### Prerequisites


- **Kaltura Session (KS):** ADMIN KS (type=2) with `METADATA_PLUGIN_PERMISSION` for profile management and `CONTENT_MANAGE_METADATA` for attaching metadata instances. See [Session Guide](/docs/getting-started/authentication/ks-overview) for generation methods.  
- **Metadata plugin enabled:** The metadata plugin (`metadata_metadataProfile`, `metadata_metadata` services) is enabled by default on all Kaltura accounts.  
- **Service URL:** Set `$KALTURA_SERVICE_URL` to your account's regional endpoint (default: `https://www.kaltura.com/api_v3`).  
- **XSD schema knowledge:** Metadata profiles are defined using XSD (XML Schema Definition). Familiarity with XSD element types and annotations is helpful for schema design.



### Authentication


All endpoints require an ADMIN KS (type=2) with appropriate permissions:

- **Metadata profiles:** `METADATA_PLUGIN_PERMISSION` + `ADMIN_BASE`
- **Metadata CRUD:** `METADATA_PLUGIN_PERMISSION` + `CONTENT_MANAGE_METADATA`

Generate an ADMIN KS via `session.start` (see [Session Guide](/docs/getting-started/authentication/ks-overview)) or `appToken.startSession` (see [AppTokens Guide](/docs/getting-started/authentication/app-tokens-overview)).


```bash
# Set up environment
export KALTURA_SERVICE_URL="https://www.kaltura.com/api_v3"
```