Skip to main content

​
Categories

Categories help you organize listings in your directory into logical groups. Categories support hierarchical structures with parent-child relationships, allowing you to create nested category trees (e.g., “Web Development” > “Frontend” > “React”).

​
Get Directory Categories

Retrieve all active categories for a specific directory. 
GET /api/directories/{directory_id}/categories
Parameters:
  • directory_id (integer, required): The ID of the directory
Response: 
{
  "data": [
    {
      "id": 1,
      "title": "Web Development",
      "slug": "web-development",
      "description": "Tools and resources for web development",
      "icon": "code",
      "content": null,
      "custom_icon_url": null,
      "parent_id": null,
      "parent_title": null,
      "is_active": true,
      "show_on_sidebar": true,
      "order": 0,
      "seo_title": null,
      "seo_description": null,
      "head_html": null,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "id": 2,
      "title": "Frontend",
      "slug": "frontend",
      "description": "Frontend frameworks and libraries",
      "content": null,
      "icon": "browser",
      "custom_icon_url": null,
      "parent_id": 1,
      "parent_title": "Web Development",
      "is_active": true,
      "show_on_sidebar": true,
      "order": 1,
      "seo_title": null,
      "seo_description": null,
      "head_html": null,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "id": 3,
      "title": "Backend",
      "slug": "backend",
      "description": "Backend frameworks and tools",
      "content": null,
      "icon": "server",
      "custom_icon_url": null,
      "parent_id": 1,
      "parent_title": "Web Development",
      "is_active": true,
      "show_on_sidebar": true,
      "order": 2,
      "seo_title": null,
      "seo_description": null,
      "head_html": null,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ]
}

​
Get Single Category

Retrieve a specific category by ID. 
GET /api/directories/{directory_id}/categories/{category_id}
Parameters:
  • directory_id (integer, required): The ID of the directory
  • category_id (integer, required): The ID of the category
Response: 
{
  "data": {
    "id": 2,
    "title": "Frontend",
    "slug": "frontend",
    "description": "Frontend frameworks and libraries",
    "content": null,
    "icon": "browser",
    "custom_icon_url": null,
    "parent_id": 1,
    "parent_title": "Web Development",
    "is_active": true,
    "show_on_sidebar": true,
    "order": 1,
    "seo_title": null,
    "seo_description": null,
    "head_html": null,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

​
Create Category

Create a new category in the directory. 
POST /api/directories/{directory_id}/categories
Parameters:
  • directory_id (integer, required): The ID of the directory
Request Body: 
{
  "title": "DevOps",
  "slug": "devops",
  "description": "DevOps tools, CI/CD, and infrastructure",
  "content": "Markdown content for the category page...",
  "icon": "gear",
  "custom_icon_url": "https://example.com/icons/devops.png",
  "parent_id": null,
  "is_active": true,
  "show_on_sidebar": true,
  "order": 3,
  "seo_title": "DevOps Tools & Infrastructure",
  "seo_description": "Browse the best DevOps tools, CI/CD pipelines, and cloud infrastructure resources.",
  "head_html": "<link rel=\"alternate\" hreflang=\"es\" href=\"https://es.example.com/categories/devops\">"
}
Request Body Fields:
  • title (string, required): The category title (max 255 characters)
  • slug (string, optional): URL-safe slug (lowercase letters, numbers, hyphens only). Auto-generated from title if not provided
  • description (string, optional): Category description
  • content (string, optional): Markdown content displayed on the category page
  • icon (string, optional): Icon identifier (max 255 characters)
  • custom_icon_url (url, optional): URL to a custom icon image (max 2048 characters)
  • parent_id (integer, optional): ID of the parent category for nested hierarchies. Must reference an existing category
  • is_active (boolean, optional): Whether the category is active (default: true)
  • show_on_sidebar (boolean, optional): Whether to display in the sidebar navigation (default: true)
  • order (integer, optional): Sort order for display (min: 0)
  • seo_title (string, optional): SEO meta title (max 255 characters)
  • seo_description (string, optional): SEO meta description (max 500 characters)
  • head_html (string, optional): Custom HTML injected into the page <head> section, e.g. hreflang tags (max 10000 characters)
Response: 
{
  "data": {
    "id": 4,
    "title": "DevOps",
    "slug": "devops",
    "description": "DevOps tools, CI/CD, and infrastructure",
    "content": "Markdown content for the category page...",
    "icon": "gear",
    "custom_icon_url": "https://example.com/icons/devops.png",
    "parent_id": null,
    "parent_title": null,
    "is_active": true,
    "show_on_sidebar": true,
    "order": 3,
    "seo_title": "DevOps Tools & Infrastructure",
    "seo_description": "Browse the best DevOps tools, CI/CD pipelines, and cloud infrastructure resources.",
    "head_html": "<link rel=\"alternate\" hreflang=\"es\" href=\"https://es.example.com/categories/devops\">",
    "created_at": "2024-01-16T09:00:00.000000Z",
    "updated_at": "2024-01-16T09:00:00.000000Z"
  }
}

​
Update Category

Update an existing category. 
PUT /api/directories/{directory_id}/categories/{category_id}
Parameters:
  • directory_id (integer, required): The ID of the directory
  • category_id (integer, required): The ID of the category
Request Body: 
{
  "title": "DevOps & Infrastructure",
  "description": "DevOps tools, CI/CD pipelines, and cloud infrastructure",
  "order": 2
}
Request Body Fields:
  • title (string, optional): The category title (max 255 characters)
  • slug (string, optional): URL-safe slug (lowercase letters, numbers, hyphens only)
  • description (string, optional): Category description
  • content (string, optional): Markdown content displayed on the category page
  • icon (string, optional): Icon identifier (max 255 characters)
  • custom_icon_url (url, optional): URL to a custom icon image (max 2048 characters)
  • parent_id (integer, optional): ID of the parent category. Must reference an existing category
  • is_active (boolean, optional): Whether the category is active
  • show_on_sidebar (boolean, optional): Whether to display in the sidebar navigation
  • order (integer, optional): Sort order for display (min: 0)
  • seo_title (string, optional): SEO meta title (max 255 characters)
  • seo_description (string, optional): SEO meta description (max 500 characters)
  • head_html (string, optional): Custom HTML injected into the page <head> section (max 10000 characters)
Response: 
{
  "data": {
    "id": 4,
    "title": "DevOps & Infrastructure",
    "slug": "devops",
    "description": "DevOps tools, CI/CD pipelines, and cloud infrastructure",
    "content": "Markdown content for the category page...",
    "icon": "gear",
    "custom_icon_url": "https://example.com/icons/devops.png",
    "parent_id": null,
    "parent_title": null,
    "is_active": true,
    "show_on_sidebar": true,
    "order": 2,
    "seo_title": "DevOps Tools & Infrastructure",
    "seo_description": "Browse the best DevOps tools, CI/CD pipelines, and cloud infrastructure resources.",
    "head_html": null,
    "created_at": "2024-01-16T09:00:00.000000Z",
    "updated_at": "2024-01-16T10:15:00.000000Z"
  }
}

​
Delete Category

Delete a category from the directory. When a parent category is deleted, its child categories will have their parent_id set to null (they become top-level categories). 
DELETE /api/directories/{directory_id}/categories/{category_id}
Parameters:
  • directory_id (integer, required): The ID of the directory
  • category_id (integer, required): The ID of the category
Response: 
{
  "message": "Category deleted successfully"
}

​
Key Features

​
Hierarchical Categories

  • Categories support parent-child relationships via the parent_id field
  • You can create multi-level category trees for organizing listings
  • When a parent category is deleted, child categories are automatically promoted to top-level

​
Slug Generation

  • Slugs are automatically generated from the category title if not provided
  • Slugs must be URL-safe (lowercase letters, numbers, and hyphens only)
  • Use show_on_sidebar to control whether a category appears in the directory’s sidebar navigation
  • Use order to control the display order of categories in the sidebar

​
SEO & Custom Head HTML

  • Use seo_title and seo_description to set per-category meta tags for search engines
  • Use head_html to inject custom HTML into the <head> section of category pages (e.g., hreflang tags for multi-language directories)
  • Use content to add rich markdown content displayed on the category page

​
Custom Icon

  • Use custom_icon_url to set a custom icon image URL for the category (displayed in category grids and navigation)