Endpoint
Creates a new category within a specific account. Categories are used to organize and classify transactions.
Authentication
This endpoint requires authentication via Bearer token and CSRF protection.
Request Body
The UUID of the account where the category will be created. Must be a valid UUID format.
The category name. Must be between 3 and 23 characters.
Optional encrypted version of the category name for end-to-end encryption.
Hex color code for the category (e.g., #6B7280). Must be a valid 6-digit hex color. Defaults to #6B7280 if not provided.
Optional icon identifier for the category. Maximum 50 characters.
Response
Indicates whether the request was successful.
The created category object.
The unique UUID of the category.
The UUID of the account this category belongs to.
The sanitized category name.
The encrypted category name, if provided.
The hex color code for the category.
The icon identifier, or null if not set.
ISO 8601 timestamp of when the category was created.
Example Request
curl -X POST https://api.yourapp.com/api/categories \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
-d '{
"account_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Groceries",
"color": "#10B981",
"icon": "shopping-cart"
}'
Example Response
{
"success": true,
"category": {
"id": "987fcdeb-51a2-43e7-9abc-123456789def",
"account_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Groceries",
"name_encrypted": null,
"color": "#10B981",
"icon": "shopping-cart",
"created_at": "2026-03-05T10:30:00.000Z"
}
}
Error Responses
Bad Request - Invalid input data.{
"success": false,
"message": "El nombre debe tener al menos 3 caracteres"
}
Forbidden - User does not have access to the specified account.{
"success": false,
"message": "You do not have access to this account"
}
Conflict - Category with this name already exists.{
"success": false,
"message": "Category with this name already exists"
}
Notes
- The
name field is automatically sanitized for storage
- If
color is not provided, it defaults to #6B7280 (gray)
- The user must have access to the specified account
- Category names must be unique within an account
