Skip to main content

​
Introduction

The Categories API enables you to create, manage, and organize content categories for your blog posts. Categories support hierarchical structures with parent-child relationships, display ordering, and active/inactive states. Each category includes visual customization options like colors and icons to enhance content organization.

​
Base Endpoint

GET /categorias

​
Category Object

The category object represents a content classification with the following structure:

​
Frontend Format (camelCase)

​
id
number
required
Unique identifier for the category
​
name
string
required
Display name of the category
​
slug
string
required
URL-friendly identifier (auto-generated from name)
​
description
string
required
Detailed description of the category’s purpose
​
color
string
required
Hex color code for visual identification (e.g., #3B82F6)
​
icon
string
required
Icon identifier for the category display
​
postsCount
number
required
Total number of posts assigned to this category
​
isActive
boolean
required
Whether the category is currently active and visible
​
createdAt
string
required
ISO 8601 timestamp of category creation
​
updatedAt
string
required
ISO 8601 timestamp of last update
​
createdBy
number | null
required
User ID of the category creator
​
parentId
number | null
Parent category ID for hierarchical organization (null for root categories)
​
displayOrder
number
Sort order for category display

​
Backend Format (snake_case)

The API communicates using snake_case notation:
​
id
number
required
Unique identifier
​
nombre
string
required
Category name
​
slug
string
required
URL slug
​
descripcion
string
required
Category description
​
color
string
required
Hex color code
​
icono
string
required
Icon identifier
​
posts_count
number
required
Number of posts in category
​
is_active
boolean
required
Active status
​
created_by
number | null
required
Creator user ID
​
parent_id
number | null
Parent category ID
​
display_order
number
Display order
​
created_at
string
required
Creation timestamp
​
updated_at
string
required
Last update timestamp

​
List All Categories

Retrieve all categories with their metadata. 
GET /categorias

const response = await fetch('https://api.example.com/categorias', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const categories = await response.json();

​
Response

[
  {
    "id": 1,
    "nombre": "SEO",
    "slug": "seo",
    "descripcion": "Optimización para motores de búsqueda",
    "color": "#10B981",
    "icono": "Search",
    "posts_count": 24,
    "is_active": true,
    "created_by": 1,
    "parent_id": null,
    "display_order": 1,
    "created_at": "2023-06-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "nombre": "Content Marketing",
    "slug": "content-marketing",
    "descripcion": "Estrategias de marketing de contenidos",
    "color": "#EF4444",
    "icono": "PenTool",
    "posts_count": 19,
    "is_active": true,
    "created_by": 1,
    "parent_id": null,
    "display_order": 2,
    "created_at": "2023-08-01T00:00:00Z",
    "updated_at": "2024-01-14T16:30:00Z"
  }
]

​
Get Hierarchical Categories

Retrieve categories organized in a hierarchical structure with parent-child relationships. 
GET /categorias/stats/jerarquicas

const response = await fetch('https://api.example.com/categorias/stats/jerarquicas', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const hierarchicalCategories = await response.json();

​
Response

Returns categories with nested children based on parent_id relationships: 
[
  {
    "id": 1,
    "nombre": "Marketing Digital",
    "slug": "marketing-digital",
    "children": [
      {
        "id": 2,
        "nombre": "SEO",
        "slug": "seo",
        "parent_id": 1,
        "children": []
      },
      {
        "id": 3,
        "nombre": "SEM",
        "slug": "sem",
        "parent_id": 1,
        "children": []
      }
    ]
  }
]

​
Get Active Categories

Filter and retrieve only active categories (client-side filtering).
This operation filters the categories array on the client side based on the isActive property. For server-side filtering, use query parameters with the main categories endpoint if supported.
const allCategories = await getAllCategories();
const activeCategories = allCategories.filter(c => c.isActive);

​
Category Icons

Categories support visual icons for better UX. Common icon identifiers include:
  • Search - Search/SEO related
  • Target - Advertising/SEM
  • Mail - Email marketing
  • Share2 - Social media
  • PenTool - Content creation
  • BarChart3 - Analytics
  • ShoppingCart - E-commerce
  • Tool - Tools and utilities
  • FileText - General content

​
Hierarchical Structure

Categories support unlimited nesting levels through the parentId field: 
// Root category
{
  id: 1,
  name: "Marketing",
  parentId: null,
  displayOrder: 1
}

// Child category
{
  id: 2,
  name: "Digital Marketing",
  parentId: 1,
  displayOrder: 1
}

// Grandchild category
{
  id: 3,
  name: "SEO",
  parentId: 2,
  displayOrder: 1
}

​
Best Practices

Slug Generation: Slugs are automatically generated from category names by converting to lowercase and replacing spaces with hyphens.
Delete Protection: Categories with posts cannot be deleted (postsCount > 0). Reassign or delete posts first.
Color Consistency: Use consistent color schemes across related categories for better visual organization.
Hierarchy Depth: While unlimited nesting is supported, limit depth to 3-4 levels for optimal user experience.

​
Error Handling

The Categories API returns standard HTTP status codes:
  • 200 OK - Successful request
  • 201 Created - Category successfully created
  • 400 Bad Request - Invalid parameters
  • 404 Not Found - Category not found
  • 409 Conflict - Category with slug already exists
  • 500 Internal Server Error - Server error
{
  "error": "Category with slug 'seo' already exists",
  "status": 409
}

​
Next Steps

Category Management

Learn about CRUD operations, status toggling, and statistics

Posts API

Associate posts with categories

Build docs developers (and LLMs) love

Get started for freeTalk to us