Update Category

Update an existing category

Endpoint

PUT /api/categories/:id

Updates an existing category. All fields are optional, allowing partial updates.

Authentication

This endpoint requires authentication via Bearer token and CSRF protection.

Path Parameters

id · string · required

The UUID of the category to update.

Request Body

All fields are optional. Only include fields you want to update.

name · string

The new category name. Must be between 3 and 23 characters if provided.

name_encrypted · string

Updated encrypted version of the category name.

color · string

Updated hex color code (e.g., #10B981). Must be a valid 6-digit hex color or empty string.

icon · string

Updated icon identifier. Maximum 50 characters.

Response

success · boolean

Indicates whether the request was successful.

category · object

The updated category object.

Show Category Object

id · string

The unique UUID of the category.

account_id · string

The UUID of the account this category belongs to.

name · string

The updated category name.

color · string

The updated hex color code.

icon · string | null

The updated icon identifier, or null.

created_at · string

ISO 8601 timestamp of when the category was created.

updated_at · string | null

ISO 8601 timestamp of when the category was last updated.

Example Request

curl -X PUT https://api.yourapp.com/api/categories/987fcdeb-51a2-43e7-9abc-123456789def \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -d '{
    "name": "Food & Groceries",
    "color": "#059669"
  }'

Example Response

{
  "success": true,
  "category": {
    "id": "987fcdeb-51a2-43e7-9abc-123456789def",
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Food & Groceries",
    "color": "#059669",
    "icon": "shopping-cart",
    "created_at": "2026-03-01T10:00:00.000Z",
    "updated_at": "2026-03-05T15:30:00.000Z"
  }
}

Partial Update Example

You can update just the color:

curl -X PUT https://api.yourapp.com/api/categories/987fcdeb-51a2-43e7-9abc-123456789def \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -d '{
    "color": "#EF4444"
  }'

Error Responses

400 · error

Bad Request - Invalid input data.

{
  "success": false,
  "message": "El color debe ser un código hexadecimal válido"
}

404 · error

Not Found - Category does not exist or user does not have access.

{
  "success": false,
  "message": "Categoría no encontrada"
}

409 · error

Conflict - Category with this name already exists.

{
  "success": false,
  "message": "Category with this name already exists"
}

Notes

• All request body fields are optional
• Only the fields included in the request will be updated
• The name field is automatically sanitized for storage
• The user must own the category or have access to the associated account
• Category names must be unique within an account
• If no fields are provided, the category is returned unchanged