---
title: Category CRUD
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/categories-category-crud
---

## Category CRUD


### Create a Category


```
POST /service/category/action/add
```



```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "category[objectType]=KalturaCategory" \
  -d "category[name]=Training" \
  -d "category[description]=Training materials" \
  -d "category[tags]=training,onboarding"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category[objectType]` | string | Yes | Always `KalturaCategory` |
| `category[name]` | string | Yes | Category display name |
| `category[parentId]` | integer | No | Parent category ID (omit or `0` for root-level) |
| `category[description]` | string | No | Description text |
| `category[tags]` | string | No | Comma-separated tags |
| `category[referenceId]` | string | No | External reference ID |
| `category[privacy]` | integer | No | Privacy level (1=ALL, 2=AUTHENTICATED, 3=MEMBERS_ONLY) |
| `category[privacyContext]` | string | No | Privacy context label for entitlement |
| `category[appearInList]` | integer | No | Visibility in listings (1=PARTNER_ONLY, 3=CATEGORY_MEMBERS_ONLY) |
| `category[contributionPolicy]` | integer | No | Who can assign content (1=ALL, 2=MEMBERS_WITH_CONTRIBUTION_PERMISSION) |
| `category[moderation]` | integer | No | `1` to require entry approval before activation |
| `category[userJoinPolicy]` | integer | No | How users join (1=AUTO, 2=REQUEST, 3=NOT_ALLOWED) |

**Response:**


```json
{
  "id": 12345,
  "name": "Training",
  "fullName": "Training",
  "fullIds": "12345",
  "parentId": 0,
  "depth": 0,
  "status": 2,
  "privacy": 1,
  "entriesCount": 0,
  "directEntriesCount": 0,
  "directSubCategoriesCount": 0,
  "membersCount": 0,
  "description": "Training materials",
  "tags": "training,onboarding",
  "createdAt": 1718467200,
  "updatedAt": 1718467200,
  "objectType": "KalturaCategory"
}
```


#### Creating a Child Category


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "category[objectType]=KalturaCategory" \
  -d "category[name]=Onboarding" \
  -d "category[parentId]=$PARENT_CATEGORY_ID" \
  -d "category[description]=Onboarding materials"
```


The response includes the computed `fullName` (e.g., `"Training>Onboarding"`) and `fullIds` (e.g., `"12345>67890"`).

### Get a Category


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/get" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CATEGORY_ID"
```


Returns the full `KalturaCategory` object. Returns `CATEGORY_NOT_FOUND` if the ID is invalid.

### List Categories


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[objectType]=KalturaCategoryFilter" \
  -d "filter[parentIdEqual]=0" \
  -d "filter[orderBy]=-createdAt" \
  -d "pager[pageSize]=50" \
  -d "pager[pageIndex]=1"
```


**Filter fields (`KalturaCategoryFilter`):**

| Field | Description |
|-------|-------------|
| `idEqual` | Exact category ID |
| `idIn` | Comma-separated category IDs |
| `parentIdEqual` | Filter by parent category (`0` for root categories) |
| `parentIdIn` | Comma-separated parent IDs |
| `nameEqual` | Exact category name match (case-sensitive, returns first match when duplicates exist) |
| `fullNameStartsWithIn` | Full path prefix match (e.g., `"Training>"`) |
| `ancestorIdIn` | Categories under any of these ancestor IDs |
| `freeText` | Free-text search across name, description, tags |
| `tagsLike` | Tags match (OR) |
| `referenceIdEqual` | Exact reference ID match |
| `statusEqual` | Filter by status (1=UPDATING, 2=ACTIVE, 3=DELETED) |
| `privacyEqual` | Filter by privacy level |
| `privacyIn` | Comma-separated privacy levels |
| `orderBy` | `+createdAt`, `-createdAt`, `+updatedAt`, `-updatedAt`, `+name`, `-name`, `+depth`, `-depth` |

**Response:**


```json
{
  "totalCount": 5,
  "objects": [
    {
      "id": 12345,
      "name": "Training",
      "fullName": "Training",
      "parentId": 0,
      "status": 2,
      "objectType": "KalturaCategory"
    }
  ],
  "objectType": "KalturaCategoryListResponse"
}
```


### Update a Category


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/update" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CATEGORY_ID" \
  -d "category[objectType]=KalturaCategory" \
  -d "category[description]=Updated training materials" \
  -d "category[tags]=training,updated"
```


Fields not included remain unchanged. Response: Full updated `KalturaCategory` object.

### Delete a Category


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CATEGORY_ID"
```


Deletes the category. Child categories are also deleted. Entries assigned to the category are unlinked (not deleted).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Category ID to delete |
| `moveEntriesToParentCategory` | integer | No | `1` to move entries to parent before deleting |

### Clone a Category Branch


```
POST /service/category/action/clone
```



```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/clone" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CATEGORY_ID" \
  -d "cloneOptions[objectType]=KalturaCategoryClone"
```


Duplicates the category and its entire subtree under the same parent as the source. Cloned categories receive new IDs while preserving hierarchy structure, names, and settings.