Create Category
Create a new category with custom properties.
Request Body
Detailed description of the category
Hex color code (defaults to #3B82F6 if not provided)
Icon identifier for visual representation
Active status (defaults to true)
Parent category ID for hierarchical organization
Sort order for category display
The slug field is automatically generated from the nombre field by converting to lowercase and replacing spaces with hyphens.
Request Example
const response = await fetch('https://api.example.com/categorias', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
},
body: JSON.stringify({
nombre: 'Email Marketing',
descripcion: 'Estrategias de email marketing y automatización',
color: '#8B5CF6',
icono: 'Mail',
is_active: true,
parent_id: null,
display_order: 5
})
});
const newCategory = await response.json();
Response
{
"id": 9,
"nombre": "Email Marketing",
"slug": "email-marketing",
"descripcion": "Estrategias de email marketing y automatización",
"color": "#8B5CF6",
"icono": "Mail",
"posts_count": 0,
"is_active": true,
"created_by": 1,
"parent_id": null,
"display_order": 5,
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
}
Update Category
Update an existing category’s properties.
Path Parameters
The unique identifier of the category to update
Request Body
All fields are optional. Only include fields you want to update:
Updated category name (slug will be regenerated)
Updated parent category ID
Request Example
const response = await fetch('https://api.example.com/categorias/9', {
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
},
body: JSON.stringify({
descripcion: 'Advanced email marketing strategies and automation',
color: '#7C3AED'
})
});
const updatedCategory = await response.json();
Response
{
"id": 9,
"nombre": "Email Marketing",
"slug": "email-marketing",
"descripcion": "Advanced email marketing strategies and automation",
"color": "#7C3AED",
"icono": "Mail",
"posts_count": 0,
"is_active": true,
"created_by": 1,
"parent_id": null,
"display_order": 5,
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T11:45:00Z"
}
Delete Category
Delete a category by ID.
Path Parameters
The unique identifier of the category to delete
Delete Protection: Categories with associated posts (posts_count > 0) cannot be deleted. You must first reassign or delete all posts in the category.
Request Example
const response = await fetch('https://api.example.com/categorias/9', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
if (response.ok) {
console.log('Category deleted successfully');
}
Response
{
"success": true,
"message": "Category deleted successfully"
}
Error Response
{
"success": false,
"error": "Cannot delete category with existing posts",
"posts_count": 15
}
Toggle Category Status
Toggle a category’s active status between active and inactive.
PATCH /categorias/:id/toggle
Path Parameters
The unique identifier of the category
This is a convenience endpoint that toggles the is_active field. You can also use the standard update endpoint with {"is_active": true/false}.
Request Example
const response = await fetch('https://api.example.com/categorias/5/toggle', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const result = await response.json();
Response
{
"success": true,
"is_active": false,
"message": "Category status toggled successfully"
}
Get Categories Statistics
Retrieve general statistics about all categories.
GET /categorias/stats/general
Request Example
const response = await fetch('https://api.example.com/categorias/stats/general', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const stats = await response.json();
Response
Total number of categories
Number of active categories
Number of inactive categories
Total posts across all categories
{
"total": 8,
"active": 7,
"inactive": 1,
"totalPosts": 123
}
Get Category Engagement
Retrieve engagement metrics for categories.
GET /categorias/stats/engagement
Request Example
const response = await fetch('https://api.example.com/categorias/stats/engagement', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const engagement = await response.json();
Response
Returns an array of engagement metrics per category:
[
{
"category_id": 1,
"category_name": "SEO",
"posts_count": 24,
"total_views": 15420,
"total_likes": 892,
"total_comments": 456,
"total_shares": 234,
"avg_views_per_post": 642.5,
"engagement_rate": 10.3
},
{
"category_id": 2,
"category_name": "Social Media",
"posts_count": 21,
"total_views": 12890,
"total_likes": 1024,
"total_comments": 567,
"total_shares": 345,
"avg_views_per_post": 613.8,
"engagement_rate": 15.0
}
]
Category unique identifier
Number of posts in the category
Cumulative views across all posts
Cumulative likes across all posts
Cumulative comments across all posts
Cumulative shares across all posts
Average views per post in the category
Percentage engagement rate (likes + comments + shares / views * 100)
GET /categorias/stats/mejor-rendimiento
Request Example
const response = await fetch('https://api.example.com/categorias/stats/mejor-rendimiento', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const topCategories = await response.json();
Response
Returns up to 10 best-performing categories sorted by posts count and engagement:
[
{
"id": 1,
"nombre": "SEO",
"slug": "seo",
"posts_count": 24,
"total_views": 15420,
"total_engagement": 1582,
"engagement_rate": 10.3,
"color": "#10B981"
},
{
"id": 4,
"nombre": "Social Media",
"slug": "social-media",
"posts_count": 21,
"total_views": 12890,
"total_engagement": 1936,
"engagement_rate": 15.0,
"color": "#F59E0B"
}
]
Usage Examples
Creating a Parent-Child Category Structure
// Create parent category
const parent = await fetch('https://api.example.com/categorias', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
},
body: JSON.stringify({
nombre: 'Marketing Digital',
descripcion: 'Estrategias de marketing digital',
color: '#3B82F6'
})
}).then(res => res.json());
// Create child category
const child = await fetch('https://api.example.com/categorias', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
},
body: JSON.stringify({
nombre: 'SEO Técnico',
descripcion: 'Optimización técnica para motores de búsqueda',
color: '#10B981',
parent_id: parent.id
})
}).then(res => res.json());
Bulk Status Update
// Deactivate multiple categories
const categoryIds = [5, 7, 9];
const results = await Promise.all(
categoryIds.map(id =>
fetch(`https://api.example.com/categorias/${id}`, {
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
},
body: JSON.stringify({ is_active: false })
}).then(res => res.json())
)
);
console.log(`Updated ${results.length} categories`);
Webhooks
Subscribe to category events to receive real-time notifications:
category.created - New category createdcategory.updated - Category updatedcategory.deleted - Category deletedcategory.status_changed - Category active status toggled
Webhook payload example:
{
"event": "category.created",
"timestamp": "2024-03-15T10:30:00Z",
"data": {
"id": 9,
"nombre": "Email Marketing",
"slug": "email-marketing",
"created_by": 1
}
}
Rate Limits
Category API endpoints are subject to the following rate limits:
- Read operations (GET): 1000 requests per hour
- Write operations (POST, PATCH, DELETE): 100 requests per hour
- Statistics endpoints: 500 requests per hour
Rate limit headers are included in responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1710504600
Next Steps
Categories Overview
Learn about category structure and hierarchies
Posts API
Associate posts with categories