---
title: "Update Specific Category"
url: "https://help.productfruits.com/en/article/knowledge-base-api-update-specific-category"
language: "en"
last_updated: "2025-12-22T12:35:56.605Z"
---

# Update Specific Category

## PUT /categories/{correlationId} - Update Category

Update a specific category by its correlation ID. This endpoint allows you to modify category properties and content while preserving existing data not included in the request.

## Endpoint

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

## Request Headers

| Header | Value | Required |
| --- | --- | --- |
| `Authorization` | `Bearer YOUR_API_TOKEN` | Yes |
| `Content-Type` | `application/json` | 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\_' |

### 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"`)

## Request Body

### CategoryUpdateRequest

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `parentCategoryId` | `number` | No | Parent category ID (null for root categories) | `null` |
| `order` | `number` | No | Display order within parent category | `1` |
| `isFeatured` | `boolean` | No | Whether category is featured | `true` |
| `icon` | `string` | No | Category icon (CDN image GUID) | `"image-guid-123"` |
| `contents` | `array` | No | Category content in different languages | See Content Object below |

### CategoryContentUpdateItem (`contents[]`)

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `lang` | `string` | Yes | Language code (ISO 639-1) | `"en"` |
| `title` | `string` | No | Category title | `"Documentation"` |
| `description` | `string` | No | Category description | `"All documentation and guides"` |
| `slug` | `string` | No | URL slug (required if slug\_state is "manual") | `"docs"` |
| `slug_state` | `string` | No | Slug generation mode: "auto" or "manual" | `"manual"` |

## Response Format

### Success Response (200 OK)

```json
{
  "id": 123,
  "correlationId": "docs-category",
  "parentCategoryId": null,
  "order": 1,
  "isFeatured": true,
  "icon": "image-guid-123",
  "contents": [
    {
      "lang": "en",
      "title": "Documentation Hub",
      "description": "Updated documentation and guides",
      "slug": "docs",
      "slug_state": "manual"
    }
  ]
}
```

### Response Fields

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `id` | `number` | Internal database ID of the category | `123` |
| `correlationId` | `string` | Custom correlation ID | `"docs-category"` |
| `parentCategoryId` | `number` | Parent category ID (null for root) | `null` |
| `order` | `number` | Display order within parent | `1` |
| `isFeatured` | `boolean` | Whether category is featured | `true` |
| `icon` | `string` | Category icon (CDN image GUID) | `"image-guid-123"` |
| `contents` | `array` | Updated category content | See Content Object below |

#### Content Object (`contents[]`)

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `lang` | `string` | Language code | `"en"` |
| `title` | `string` | Category title | `"Documentation Hub"` |
| `description` | `string` | Category description | `"Updated documentation and guides"` |
| `slug` | `string` | URL slug | `"docs"` |
| `slug_state` | `string` | Slug generation mode | `"manual"` |

## Examples

### Example 1: Update Category Properties

```bash
curl -X PUT "https://api.productfruits.com/v1/knowledgebase/categories/docs-category" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isFeatured": true,
    "icon": "📖",
    "order": 2
  }'
```

**Response:**

```json
{
  "id": 123,
  "correlationId": "docs-category",
  "parentCategoryId": null,
  "order": 2,
  "isFeatured": true,
  "icon": "📖",
  "contents": [
    {
      "lang": "en",
      "title": "Documentation",
      "description": "All documentation and guides",
      "slug": "docs",
      "slug_state": "manual"
    }
  ]
}
```

### Example 2: Update Category Content

```bash
curl -X PUT "https://api.productfruits.com/v1/knowledgebase/categories/docs-category" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "lang": "en",
        "title": "Documentation Hub",
        "description": "Comprehensive documentation and user guides"
      },
      {
        "lang": "es",
        "title": "Centro de Documentación",
        "description": "Documentación completa y guías de usuario",
        "slug_state": "auto"
      }
    ]
  }'
```

**Response:**

```json
{
  "id": 123,
  "correlationId": "docs-category",
  "parentCategoryId": null,
  "order": 1,
  "isFeatured": false,
  "icon": "image-guid-123",
  "contents": [
    {
      "lang": "en",
      "title": "Documentation Hub",
      "description": "Comprehensive documentation and user guides",
      "slug": "docs",
      "slug_state": "manual"
    },
    {
      "lang": "es",
      "title": "Centro de Documentación",
      "description": "Documentación completa y guías de usuario",
      "slug": "centro-de-documentacion",
      "slug_state": "auto"
    }
  ]
}
```

### Example 3: Move Category to Different Parent

```bash
curl -X PUT "https://api.productfruits.com/v1/knowledgebase/categories/tutorials-category" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentCategoryId": 123,
    "order": 1
  }'
```

### Example 4: Error Handling Example

```bash
curl -X PUT "https://api.productfruits.com/v1/knowledgebase/categories/non-existent-category" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isFeatured": true
  }'
```

**Response (404 Not Found):**

```json
{
  "error": "Category with correlation ID 'non-existent-category' not found"
}
```

## Update Behavior

### Partial Updates

Only fields included in the request are updated:

-   **Included fields**: Updated with provided values
-   **Omitted fields**: Retain their current values
-   **Content languages**: Only specified languages are updated

### Content Language Handling

When updating category content:

-   **Existing languages**: Updated if included in request
-   **New languages**: Added to the category
-   **Omitted languages**: Remain unchanged (not deleted)

### Slug Management

-   **Manual slugs** (`slug_state: "manual"`): Use provided slug exactly
-   **Auto slugs** (`slug_state: "auto"`): Generate from title
-   **Existing slugs**: Preserved if not explicitly changed

## Common Use Cases

### Property Updates

Modify category settings without changing content:

-   Change featured status or display order
-   Update category icons or parent relationships
-   Reorganize category hierarchy

### Content Localization

Add or update category content in specific languages:

-   Add translations for existing categories
-   Update descriptions or titles for specific languages
-   Maintain different slug strategies per language

### Hierarchy Reorganization

Move categories within the hierarchy structure:

-   Change parent-child relationships
-   Reorder categories within parent groups
-   Restructure category organization

### Incremental Updates

Make small changes without full category replacement:

-   Update only changed properties
-   Preserve existing content and relationships
-   Maintain category history and references

## Best Practices

-   **Verify Category Exists**: Use `GET /categories/{correlationId}` before updating
-   **Partial Updates**: Only include fields you want to change
-   **Validate Hierarchies**: Ensure parent category IDs are valid
-   **Handle Slug Conflicts**: Be aware of potential slug conflicts when updating titles
-   **Test Updates**: Verify changes in test environment before production updates
-   **Backup Before Changes**: Export category data before major updates

## 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

### Invalid Parent Category

**Cause**: Referencing non-existent parent category ID  
**Solution**: Verify parent category exists or use null for root categories

### Slug Conflicts

**Cause**: Updated slug conflicts with existing category slug  
**Solution**: Use different slug or check existing slugs before updating

### Circular Dependencies

**Cause**: Creating circular parent-child relationships  
**Solution**: Validate hierarchy structure to prevent circular references

### Error Response Examples

#### 400 Bad Request - Validation Error

```json
{
  "error": "Invalid parent category ID: 999"
}
```

#### 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 updating category"
}
```

## Rate Limiting

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