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

Request Headers

Path 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")

Request Body

CategoryUpdateRequest

CategoryContentUpdateItem (contents[])

Response Format

Success Response (200 OK)

{
  "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

Content Object (contents[])

Examples

Example 1: Update Category Properties

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:

{
  "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

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:

{
  "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

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

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):

{
  "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

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

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

Rate Limiting

Consult this article for detailed information about API limits and optimization strategies.