> ## Documentation Index > Fetch the complete documentation index at: https://docs.directify.app/llms.txt > Use this file to discover all available pages before exploring further. # Categories > Manage categories for directories through the Directify API - create, read, update, and delete categories with full CRUD operations. ## 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. ```http theme={null} GET /api/directories/{directory_id}/categories ``` **Parameters:** * `directory_id` (integer, required): The ID of the directory **Response:** ```json theme={null} { "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. ```http theme={null} 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:** ```json theme={null} { "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. ```http theme={null} POST /api/directories/{directory_id}/categories ``` **Parameters:** * `directory_id` (integer, required): The ID of the directory **Request Body:** ```json theme={null} { "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": "" } ``` **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 `` section, e.g. hreflang tags (max 10000 characters) **Response:** ```json theme={null} { "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": "", "created_at": "2024-01-16T09:00:00.000000Z", "updated_at": "2024-01-16T09:00:00.000000Z" } } ``` ### Update Category Update an existing category. ```http theme={null} 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:** ```json theme={null} { "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 `` section (max 10000 characters) **Response:** ```json theme={null} { "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). ```http theme={null} 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:** ```json theme={null} { "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) ### Sidebar Visibility * 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 `` 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)