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/knowledge-base/categories/{correlationId}

Request Headers

Path Parameters

Query Parameters

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)

{
  "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 Detailed information about API limits and optimization strategies.

Error Response Examples

400 Bad Request - Missing Correlation ID

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

400 Bad Request - Category Contains Articles

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

401 Unauthorized

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

404 Not Found

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

500 Internal Server Error

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

Examples

Example 1: Delete Empty Category

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

Response:

{
  "message": "Category deleted successfully"
}

Example 2: Delete Category and Move Articles to Root

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

Response:

{
  "message": "Category deleted successfully"
}

Example 3: Delete Category by Internal ID

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

Response:

{
  "message": "Category deleted successfully"
}

Example 4: Error Handling Example

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

Response (400 Bad Request):

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