---
title: "Delete Category"
url: "https://help.productfruits.com/en/article/knowledge-base-api-delete-category"
language: "en"
last_updated: "2025-12-22T12:36:23.528Z"
---

# Delete Category

## DELETE /categories/{correlationId} - Delete Category

Permanently delete a category from the knowledge base. This operation handles child categories and articles according to the specified configuration.

## Endpoint

```
DELETE /v1/knowledgebase/categories/{correlationId}
```

## Request Headers

| Header | Value | Required |
| --- | --- | --- |
| `Authorization` | `Bearer YOUR_API_TOKEN` | Yes |

## Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `correlationId` | `string` | Yes | The correlation ID of the category. Can be custom ID or internal ID prefixed with 'pf\_' |

## Query Parameters

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| `articleHandling` | `string` | No | How to handle articles in deleted categories: "error" or "move-to-root" | `"error"` |

### Correlation ID Format

-   **Custom IDs**: Use your own correlation ID as provided during import (e.g., `"docs-category"`)
-   **Internal IDs**: Use internal database ID prefixed with `"pf_"` (e.g., `"pf_123"`)

### Article Handling Options

-   **`error`** (default): Deletion fails if category contains articles
-   **`move-to-root`**: Moves all articles to root level (no category assignment)

## Response Format

### Success Response (200 OK)

```json
{
  "message": "Category deleted successfully"
}
```

## What Gets Deleted

When you delete a category, the following items are permanently removed:

### Category Data

-   Category metadata (title, description, properties)

### Child Categories

-   All child categories are deleted recursively
-   Entire category subtree structure

## What Happens to Articles

The handling of articles depends on the `articleHandling` parameter:

### With `articleHandling=error` (Default)

-   **Articles present**: Deletion fails with error
-   **No articles**: Category deleted successfully
-   **Use case**: Safe deletion that prevents accidental article loss

### With `articleHandling=move-to-root`

-   **Articles present**: Moved to root level (no category assignment)
-   **Child categories with articles**: All articles moved to root recursively
-   **Use case**: Category cleanup while preserving articles

## Deletion Behavior

### Recursive Deletion

When deleting a category:

-   **Child categories**: Deleted recursively (entire subtree)
-   **Articles**: Handled according to `articleHandling` parameter
-   **Parent relationships**: Updated for remaining categories

### Article Movement Process

With `articleHandling=move-to-root`:

-   **Identify articles**: Find all articles in category and child categories
-   **Update references**: Set `categoryId` to `null` for all affected articles
-   **Preserve content**: Article content and properties remain unchanged
-   **Delete categories**: Remove category structure after article movement

## Common Use Cases

### Category Cleanup

Remove obsolete or unused categories:

-   Delete empty categories that are no longer needed
-   Clean up test or development categories
-   Remove deprecated category structures

### Hierarchy Reorganization

Restructure category organization:

-   Remove intermediate categories while preserving articles
-   Flatten complex category hierarchies
-   Consolidate similar categories

### Content Migration

Prepare for category structure changes:

-   Move articles to root before implementing new structure
-   Remove categories before importing new hierarchy
-   Clean up before major reorganization

### Maintenance Operations

Regular knowledge base maintenance:

-   Remove categories with no content
-   Clean up after bulk operations
-   Maintain category structure integrity

## Common Error Scenarios

### Category Not Found

**Cause**: Using incorrect correlation ID or category doesn't exist  
**Solution**: Verify correlation ID using `GET /categories` endpoint first

### Category Contains Articles

**Cause**: Attempting to delete category with articles using default `articleHandling=error`  
**Solution**: Use `articleHandling=move-to-root` or remove articles first

### Invalid Article Handling

**Cause**: Using invalid value for `articleHandling` parameter  
**Solution**: Use "error" or "move-to-root" as valid values

### Permission Issues

**Cause**: API token lacks category deletion permissions  
**Solution**: Check API token permissions and user roles

## Rate Limiting

Check out this [article](https://help.productfruits.com/en/article/rest-api-rate-limiting) Detailed information about API limits and optimization strategies.

### Error Response Examples

#### 400 Bad Request - Missing Correlation ID

```json
{
  "error": "Correlation ID is required"
}
```

#### 400 Bad Request - Category Contains Articles

```json
{
  "error": "Category contains articles. Use articleHandling=move-to-root to move articles to root or remove articles first"
}
```

#### 401 Unauthorized

```json
{
  "error": "Authentication required or invalid API token"
}
```

#### 404 Not Found

```json
{
  "error": "Category with correlation ID 'invalid-id' not found"
}
```

#### 500 Internal Server Error

```json
{
  "error": "Internal server error occurred while deleting category"
}
```

## Examples

### Example 1: Delete Empty Category

```bash
curl -X DELETE "https://api.productfruits.com/v1/knowledgebase/categories/old-category" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response:**

```json
{
  "message": "Category deleted successfully"
}
```

### Example 2: Delete Category and Move Articles to Root

```bash
curl -X DELETE "https://api.productfruits.com/v1/knowledgebase/categories/docs-category?articleHandling=move-to-root" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response:**

```json
{
  "message": "Category deleted successfully"
}
```

### Example 3: Delete Category by Internal ID

```bash
curl -X DELETE "https://api.productfruits.com/v1/knowledgebase/categories/pf_123?articleHandling=move-to-root" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response:**

```json
{
  "message": "Category deleted successfully"
}
```

### Example 4: Error Handling Example

```bash
curl -X DELETE "https://api.productfruits.com/v1/knowledgebase/categories/category-with-articles" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response (400 Bad Request):**

```json
{
  "error": "Category contains articles. Use articleHandling=move-to-root to move articles to root or remove articles first"
}
```