dotCMS

dotCMS Categories API

Content categorization and taxonomy

GitHub OpenAPI

Operations 10

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v1/categories List categories · Get paginated list of categories #
Ask an LLM
“What top-level categories are set up in dotCMS?”
“Can I see how many child categories each category has?”
Tell an agent
List all categories.
List categories matching {filter} with child counts.
PUT /api/v1/categories Update an existing category · Update an existing category #
Ask an LLM
“How do I rename an existing category?”
“Can I change a category's key or keywords after it's created?”
Tell an agent
Rename category {inode} to {categoryName}.
Update category {inode} named {categoryName} with keywords {keywords}.
POST /api/v1/categories Create a new category · Create a new category #
Ask an LLM
“How do I add a new category to use for tagging content?”
“Can I create a subcategory under an existing parent?”
Tell an agent
Create a category called {categoryName}.
Create subcategory {categoryName} under parent {parent} with key {key}.
DELETE /api/v1/categories Delete categories and their descendants · Delete categories by inodes #
Ask an LLM
“Does deleting a category also delete all of its subcategories?”
“What happens when I lack permission on one child of a category I delete?”
Tell an agent destructive · confirm first
Delete these categories and everything beneath them.
Remove the selected categories by inode and report any that failed.
GET /api/v1/categories/_export Export categories to CSV · Export categories as CSV #
Ask an LLM
“Can I download my category tree as a CSV?”
“Is it possible to export just the children of one parent category?”
Tell an agent
Export all categories to CSV.
Export categories under parent {contextInode} matching {filter}.
GET /api/v1/categories/{idOrKey} Get a category by ID or key · Get a category by ID or key #
Ask an LLM
“How do I look up a single category by its key?”
“Can I fetch one category and see how many children it has?”
Tell an agent
Get category {idOrKey}.
Show category {idOrKey} with its child count.
GET /api/v1/categories/children List the children of a category · Get children of a category #
Ask an LLM
“What subcategories sit under a given parent category?”
“Can I get every descendant at all levels, not just direct children?”
Tell an agent
List the child categories of {inode}.
List all descendants of category {inode} at every level.
POST /api/v1/categories/hierarchy Get parent chains for several categories · Get category hierarchy for multiple categories #
Ask an LLM
“Which parent categories sit above each of these category keys?”
“Can I get the breadcrumb path for multiple categories in one call?”
Tell an agent
Get the parent hierarchy for category keys {keys}.
Show the breadcrumb from top level down for categories {keys}.
POST /api/v1/categories/_import Import categories from a CSV file · Import categories from a CSV file #
Ask an LLM
“Can I import categories from a CSV and replace the existing ones?”
“What's the difference between merge and replace when importing categories?”
Tell an agent
Import categories from {file} using the {exportType} strategy.
Merge categories from {file} under parent {contextInode}.
PUT /api/v1/categories/_sort Change the sort order of categories · Update category sort order #
Ask an LLM
“How do I reorder categories so they appear in a specific sequence?”
“Can I change the sort order of several subcategories at once?”
Tell an agent
Update the sort order of categories under {parentInode} to {categoryData}.
Apply new sort positions {categoryData} to these categories.

Documentation

📖
Documentation
https://dev.dotcms.com/docs/build/apis/api-basics/rest-apis
📖
APIReference
https://dev.dotcms.com/docs/build/apis/rest-apis/api-playground

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/openapi/dotcms-categories-api-openapi.yml

Other Resources

🔗
DeveloperPortal
https://dev.dotcms.com/
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/errors/dotcms-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/data-model/dotcms-data-model.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/conventions/dotcms-conventions.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/dotcms:dotcms-categories-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

dotcms-categories-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: dotCMS REST Categories API
  version: '3'
  description: Content categorization and taxonomy
servers:
- url: /
  description: dotCMS Server
tags:
- name: Categories
  description: Content categorization and taxonomy
paths:
  /api/v1/categories:
    get:
      tags:
      - Categories
      summary: Get paginated list of categories
      description: Returns a paginated list of categories. Supports filtering by name, sorting, and optionally including the count of child categories for each result.
      operationId: getCategories
      parameters:
      - name: filter
        in: query
        description: Filter string to match against category names
        schema:
          type: string
      - name: page
        in: query
        description: Page number (zero-based)
        schema:
          type: integer
          format: int32
      - name: per_page
        in: query
        description: Number of items per page
        schema:
          type: integer
          format: int32
      - name: orderby
        in: query
        description: Field to order results by
        schema:
          type: string
          default: category_name
      - name: direction
        in: query
        description: 'Sort direction: ASC or DESC'
        schema:
          type: string
          default: ASC
      - name: showChildrenCount
        in: query
        description: Whether to include children count for each category
        schema:
          type: boolean
      responses:
        '200':
          description: Paginated categories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryView'
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
    put:
      tags:
      - Categories
      summary: Update an existing category
      description: Updates a working version of an existing category. The form must contain the inode of the category to update.
      operationId: updateCategory
      requestBody:
        description: Category form with updated properties including inode
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryForm'
        required: true
      responses:
        '200':
          description: Category updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryView'
        '400':
          description: Bad request
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions to update categories
        '404':
          description: Category not found
    post:
      tags:
      - Categories
      summary: Create a new category
      description: Creates a new category using the provided form data. The category name is required.
      operationId: createCategory
      requestBody:
        description: Category form with name and properties
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryForm'
        required: true
      responses:
        '200':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryView'
        '400':
          description: Bad request — category name is required
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
    delete:
      tags:
      - Categories
      summary: Delete categories by inodes
      description: Deletes one or more categories and all their descendants at every depth. EDIT permission is validated on each selected category and every descendant before anything is deleted; a category that fails validation is skipped whole. Accepts a JSON array of category inodes. Inodes that could not be deleted are reported in the `fails` list of the result with the failure reason (category does not exist, insufficient permissions, or a permission-protected descendant). `successCount` counts the requested inodes that were deleted, while `deletedCount` counts every category actually removed, descendants included.
      operationId: deleteCategories
      requestBody:
        description: JSON payload containing a list of the inodes of categories to delete.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        '200':
          description: Bulk delete result returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryBulkDeleteResultView'
        '400':
          description: Bad request
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
  /api/v1/categories/_export:
    get:
      tags:
      - Categories
      summary: Export categories as CSV
      description: Exports categories to a CSV file. Optionally filter by name and scope to a parent category inode.
      operationId: exportCategories
      parameters:
      - name: contextInode
        in: query
        description: Context category inode to export from
        schema:
          type: string
      - name: filter
        in: query
        description: Filter pattern to match category names
        schema:
          type: string
      responses:
        '200':
          description: CSV file streamed successfully
          content:
            text/csv: {}
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
        '404':
          description: Context category not found
  /api/v1/categories/{idOrKey}:
    get:
      tags:
      - Categories
      summary: Get a category by ID or key
      description: Retrieves a single category by either its inode (ID) or its unique key. First attempts to find by inode; if not found, searches by key.
      operationId: getCategoryByIdOrKey
      parameters:
      - name: idOrKey
        in: path
        description: Category ID (inode) or key
        required: true
        schema:
          type: string
      - name: showChildrenCount
        in: query
        description: Whether to include children count
        schema:
          type: boolean
      responses:
        '200':
          description: Category retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryView'
        '400':
          description: Bad request — idOrKey is required
        '401':
          description: Authentication required
        '404':
          description: Category not found
  /api/v1/categories/children:
    get:
      tags:
      - Categories
      summary: Get children of a category
      description: Returns a paginated list of child categories for the specified parent category inode. When 'allLevels' is true, returns categories at any depth; otherwise only immediate children.
      operationId: getCategoryChildren
      parameters:
      - name: filter
        in: query
        description: Filter text to search child categories
        schema:
          type: string
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
          format: int32
      - name: per_page
        in: query
        description: Number of items per page
        schema:
          type: integer
          format: int32
      - name: orderby
        in: query
        description: Field to order results by
        schema:
          type: string
          default: category_name
      - name: direction
        in: query
        description: Sort direction (ASC or DESC)
        schema:
          type: string
          default: ASC
      - name: inode
        in: query
        description: Parent category inode to get children for
        schema:
          type: string
      - name: showChildrenCount
        in: query
        description: Whether to include children count for each category
        schema:
          type: boolean
      - name: allLevels
        in: query
        description: Whether to include all nested levels
        schema:
          type: boolean
      - name: parentList
        in: query
        description: Whether to include parent list hierarchy
        schema:
          type: boolean
      responses:
        '200':
          description: Children categories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryWithChildCountView'
        '400':
          description: Bad request
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
        '404':
          description: Parent category not found
  /api/v1/categories/hierarchy:
    post:
      tags:
      - Categories
      summary: Get category hierarchy for multiple categories
      description: Retrieves the parent hierarchy for a set of categories specified by their keys. Returns parent lists for each category, starting from the top-level parent down to the direct parent. Categories that don't exist are ignored.
      operationId: getCategoryHierarchy
      requestBody:
        description: Category keys form containing array of category keys
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryKeysForm'
        required: true
      responses:
        '200':
          description: Category hierarchies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HierarchyShortCategoriesResponseView'
        '400':
          description: Bad request - invalid category keys form
        '401':
          description: Unauthorized - user authentication required
  /api/v1/categories/_import:
    post:
      tags:
      - Categories
      summary: Import categories from a CSV file
      description: 'Imports categories from an uploaded CSV file. The ''exportType'' parameter controls the import strategy: ''replace'' deletes existing categories before importing, ''merge'' adds or updates without removing existing ones.'
      operationId: importCategories
      requestBody:
        description: CSV file containing categories to be imported.
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CategoryImportFormSchema'
        required: true
      responses:
        '200':
          description: Import result returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityBulkResultView'
        '400':
          description: Bad request or invalid file
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
  /api/v1/categories/_sort:
    put:
      tags:
      - Categories
      summary: Update category sort order
      description: Updates the sort order of one or more existing categories.
      operationId: updateCategorySortOrder
      requestBody:
        description: List of category inodes to delete
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryEditForm'
        required: true
      responses:
        '200':
          description: Sort order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityCategoryView'
        '400':
          description: Bad request
        '403':
          description: Insufficient permissions
        '401':
          description: Authentication required
components:
  schemas:
    HierarchyShortCategory:
      type: object
      properties:
        inode:
          type: string
        name:
          type: string
        key:
          type: string
        parentList:
          type: array
          items:
            $ref: '#/components/schemas/ShortCategory'
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          format: int32
        perPage:
          type: integer
          format: int32
        totalEntries:
          type: integer
          format: int64
    ResponseEntityBulkResultView:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
        entity:
          $ref: '#/components/schemas/BulkResultView'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageEntity'
        i18nMessagesMap:
          type: object
          additionalProperties:
            type: string
        permissions:
          type: array
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    ResponseEntityCategoryView:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
        entity:
          $ref: '#/components/schemas/CategoryView'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageEntity'
        i18nMessagesMap:
          type: object
          additionalProperties:
            type: string
        permissions:
          type: array
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    ErrorEntity:
      type: object
      properties:
        errorCode:
          type: string
        message:
          type: string
        fieldName:
          type: string
    CategoryKeysForm:
      type: object
      properties:
        keys:
          type: array
          items:
            type: string
    HierarchyShortCategoriesResponseView:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
        entity:
          type: array
          items:
            $ref: '#/components/schemas/HierarchyShortCategory'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageEntity'
        i18nMessagesMap:
          type: object
          additionalProperties:
            type: string
        permissions:
          type: array
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    ShortCategory:
      type: object
      properties:
        name:
          type: string
        inode:
          type: string
        key:
          type: string
    MessageEntity:
      type: object
      properties:
        message:
          type: string
    BulkResultView:
      type: object
      properties:
        successCount:
          type: integer
          format: int64
        skippedCount:
          type: integer
          format: int64
        fails:
          type: array
          items:
            $ref: '#/components/schemas/FailedResultView'
    CategoryView:
      type: object
      properties:
        inode:
          type: string
        parent:
          type: string
        description:
          type: string
        keywords:
          type: string
        key:
          type: string
        categoryName:
          type: string
        active:
          type: boolean
        sortOrder:
          type: integer
          format: int32
        categoryVelocityVarName:
          type: string
        modDate:
          type: string
          format: date-time
    CategoryImportFormSchema:
      type: object
      properties:
        filter:
          type: string
          description: Filter pattern for categories
        exportType:
          type: string
          description: Import behavior
          enum:
          - replace
          - merge
        contextInode:
          type: string
          description: Context category inode to import into
        file:
          type: string
          description: CSV file containing categories to import
          format: binary
      description: Category import form data with CSV file and processing parameters
    ResponseEntityCategoryBulkDeleteResultView:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
        entity:
          $ref: '#/components/schemas/CategoryBulkDeleteResultView'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageEntity'
        i18nMessagesMap:
          type: object
          additionalProperties:
            type: string
        permissions:
          type: array
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    CategoryBulkDeleteResultView:
      type: object
      properties:
        successCount:
          type: integer
          format: int64
        skippedCount:
          type: integer
          format: int64
        fails:
          type: array
          items:
            $ref: '#/components/schemas/FailedResultView'
        deletedCount:
          type: integer
          format: int64
    FailedResultView:
      type: object
      properties:
        element:
          type: string
        errorMessage:
          type: string
    ResponseEntityCategoryWithChildCountView:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
        entity:
          $ref: '#/components/schemas/CategoryWithChildCountView'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageEntity'
        i18nMessagesMap:
          type: object
          additionalProperties:
            type: string
        permissions:
          type: array
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    CategoryWithChildCountView:
      type: object
      properties:
        inode:
          type: string
        parent:
          type: string
        description:
          type: string
        keywords:
          type: string
        key:
          type: string
        categoryName:
          type: string
        active:
          type: boolean
        sortOrder:
          type: integer
          format: int32
        categoryVelocityVarName:
          type: string
        modDate:
          type: string
          format: date-time
        childrenCount:
          type: integer
          format: int32
    CategoryForm:
      required:
      - categoryName
      type: object
      properties:
        siteId:
          type: string
        inode:
          type: string
        parent:
          type: string
        description:
          type: string
        keywords:
          type: string
        key:
          type: string
        categoryName:
          type: string
        active:
          type: boolean
        sortOrder:
          type: integer
          format: int32
        categoryVelocityVarName:
          type: string
    CategoryEditForm:
      type: object
      properties:
        filter:
          type: string
        page:
          type: integer
          format: int32
        perPage:
          type: integer
          format: int32
        direction:
          type: string
        orderBy:
          type: string
        siteId:
          type: string
        parentInode:
          type: string
        categoryData:
          type: object
          additionalProperties:
            type: integer
            format: int32