openapi: 3.2.0 info: title: dotCMS REST Containers API version: '3' description: Endpoints for managing Container objects and their content servers: - url: / description: dotCMS Server tags: - name: Containers description: Endpoints for managing Container objects and their content paths: /api/v1/containers/_archive: put: tags: - Containers summary: Archives a container description: Archives the specified container. The user must have Edit permissions on the container. operationId: archiveContainer parameters: - name: containerId in: query description: Container identifier to archive schema: type: string responses: '200': description: Container archived successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Container ID is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks edit permissions '404': description: Container not found /api/v1/containers/_bulkarchive: put: tags: - Containers summary: Archives multiple containers description: Archives a list of containers by their identifiers. Returns a summary of successful and failed archive operations. The user must have Edit permissions on each container. operationId: bulkArchiveContainers requestBody: description: List of container identifiers to archive content: '*/*': schema: type: array items: type: string required: true responses: '200': description: Bulk archive results with success and failure counts content: application/json: schema: $ref: '#/components/schemas/ResponseEntityBulkResultView' '400': description: Bad request - Container identifiers list is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks edit permissions /api/v1/containers/_bulkdelete: delete: tags: - Containers summary: Deletes multiple containers description: Deletes a list of containers by their identifiers. Returns a summary of successful and failed deletions. The user must have Edit permissions on each container. operationId: bulkDeleteContainers requestBody: description: List of container identifiers to delete content: '*/*': schema: type: array items: type: string required: true responses: '200': description: Bulk delete results with success and failure counts content: application/json: schema: $ref: '#/components/schemas/ResponseEntityBulkResultView' '400': description: Bad request - Container identifiers list is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions /api/v1/containers/_bulkpublish: put: tags: - Containers summary: Publishes multiple containers description: Publishes a list of containers by their identifiers. Returns a summary of successful and failed publish operations. The user must have Publish permissions on each container. operationId: bulkPublishContainers requestBody: description: List of container identifiers to publish content: '*/*': schema: type: array items: type: string required: true responses: '200': description: Bulk publish results with success and failure counts content: application/json: schema: $ref: '#/components/schemas/ResponseEntityBulkResultView' '400': description: Bad request - Container identifiers list is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks publish permissions /api/v1/containers/_bulkunarchive: put: tags: - Containers summary: Unarchives multiple containers description: Unarchives a list of containers by their identifiers. Returns a summary of successful and failed unarchive operations. The user must have Edit permissions on each container. operationId: bulkUnarchiveContainers requestBody: description: List of container identifiers to unarchive content: '*/*': schema: type: array items: type: string required: true responses: '200': description: Bulk unarchive results with success and failure counts content: application/json: schema: $ref: '#/components/schemas/ResponseEntityBulkResultView' '400': description: Bad request - Container identifiers list is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks edit permissions /api/v1/containers/_bulkunpublish: put: tags: - Containers summary: Unpublishes multiple containers description: Unpublishes a list of containers by their identifiers. Returns a summary of successful and failed unpublish operations. The user must have Publish permissions on each container. operationId: bulkUnpublishContainers requestBody: description: List of container identifiers to unpublish content: '*/*': schema: type: array items: type: string required: true responses: '200': description: Bulk unpublish results with success and failure counts content: application/json: schema: $ref: '#/components/schemas/ResponseEntityBulkResultView' '400': description: Bad request - Container identifiers list is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks publish permissions /api/v1/containers/{containerId}/content/{contentletId}: get: tags: - Containers summary: Renders content HTML within a container description: Generates the rendered HTML for a specific contentlet within a container. The container ID is provided as a path parameter. operationId: getContainerContentById parameters: - name: containerId in: path description: Container identifier (UUID or path) required: true schema: type: string - name: contentletId in: path description: Contentlet identifier required: true schema: type: string - name: pageInode in: query description: Page inode for context rendering schema: type: string responses: '200': description: Content rendered successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityContainerObjectMapView' '400': description: Bad request - Invalid parameters '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Container or contentlet not found /api/v1/containers/content/{contentletId}: get: tags: - Containers summary: Renders content HTML with container ID as query param description: Generates the rendered HTML for a specific contentlet within a container. The container ID is passed as a query parameter, which is useful for file-asset containers where the container ID is a path. operationId: getContainerContentByQueryParam parameters: - name: containerId in: query description: Container identifier (UUID or file-asset path) schema: type: string - name: pageInode in: query description: Page inode for context rendering schema: type: string - name: contentletId in: path description: Contentlet identifier required: true schema: type: string responses: '200': description: Content rendered successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityContainerObjectMapView' '400': description: Bad request - Invalid parameters '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Container or contentlet not found /api/v1/containers/{containerId}/form/{formId}: get: tags: - Containers summary: Renders a form within a container description: Returns HTML content for a form rendered within the specified container. This is used to display forms with container styling and layout. operationId: containerForm parameters: - name: containerId in: path description: Container identifier (UUID or path) required: true schema: type: string - name: formId in: path description: Form identifier required: true schema: type: string responses: '200': description: Form rendered successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityContainerObjectMapView' '400': description: Bad request - Invalid container or form ID '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Container or form not found '500': description: Internal server error /api/v1/containers/form/{formId}: get: tags: - Containers summary: Renders a form with container ID as query param description: Returns HTML content for a form rendered within the specified container. The container ID is passed as a query parameter, which is useful for file-asset containers where the container ID is a path. operationId: getContainerFormByQueryParam parameters: - name: containerId in: query description: Container identifier (UUID or file-asset path) schema: type: string - name: formId in: path description: Form identifier required: true schema: type: string responses: '200': description: Form rendered successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityContainerObjectMapView' '400': description: Bad request - Invalid parameters '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Container or form not found /api/v1/containers/{id}/_copy: post: tags: - Containers summary: Copies a container to the current host description: Creates a copy of the specified container on the current host. The user must have backend access and appropriate permissions. operationId: copyContainer parameters: - name: id in: path description: Container identifier to copy required: true schema: type: string responses: '200': description: Container copied successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityContainerView' '400': description: Bad request - Container ID is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Container not found /api/v1/containers: get: tags: - Containers summary: Retrieves a paginated list of Containers description: Returns a list of Container objects based on filtering and pagination parameters. Containers are layout components that define how content is displayed on pages. operationId: getContainers parameters: - name: filter in: query description: Filter containers by title pattern schema: type: string - name: page in: query description: Page number for pagination (starting from 1) 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: title - name: direction in: query description: 'Sort direction: ASC or DESC' schema: type: string default: ASC - name: host in: query description: Filter containers by host ID schema: type: string - name: system in: query description: Include system containers in results schema: type: boolean - name: archive in: query description: Include archived containers in results schema: type: boolean - name: content_type in: query description: Filter containers by content type ID or variable name schema: type: string responses: '200': description: Containers retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityPaginatedArrayListMapView' '400': description: Bad request - Invalid parameters '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '500': description: Internal server error put: tags: - Containers summary: Updates an existing container description: Updates a container's working version with the provided configuration. The container must exist and the user must have edit permissions. operationId: updateContainer requestBody: description: Updated container configuration data including identifier and modified properties content: application/json: schema: $ref: '#/components/schemas/ContainerForm' required: true responses: '200': description: Container updated successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Invalid container data '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks edit permissions '404': description: Container not found '500': description: Internal server error post: tags: - Containers summary: Creates a new container description: Creates and publishes a new container with the provided configuration. The container will be saved as both working and live versions. operationId: saveContainer requestBody: description: Container configuration data including title, code, content type structures, and display settings content: application/json: schema: $ref: '#/components/schemas/ContainerForm' required: true responses: '200': description: Container created successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Invalid container data '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks create permissions '500': description: Internal server error delete: tags: - Containers summary: Deletes a container description: Permanently deletes the specified container. The user must have Edit permissions on the container. operationId: deleteContainer parameters: - name: containerId in: query description: Container identifier to delete schema: type: string responses: '200': description: Container deletion result (true if deleted, false otherwise) content: application/json: schema: $ref: '#/components/schemas/ResponseEntityBooleanView' '400': description: Bad request - Container ID is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks edit permissions '404': description: Container not found /api/v1/containers/live: get: tags: - Containers summary: Retrieves a live container by ID description: Returns the live (published) version of a container. Optionally includes associated content type information. operationId: getLiveContainer parameters: - name: containerId in: query description: Container identifier schema: type: string - name: includeContentType in: query description: Include associated content type information schema: type: boolean responses: '200': description: Live container retrieved successfully. Returns ContainerView by default, or ContainerWithContentTypesView if includeContentType=true. content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Invalid container ID '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Live container not found '500': description: Internal server error /api/v1/containers/working: get: tags: - Containers summary: Retrieves a working container by ID description: Returns the working (draft) version of a container. Optionally includes associated content type information. operationId: getWorkingContainer parameters: - name: containerId in: query description: Container identifier schema: type: string - name: includeContentType in: query description: Include associated content type information schema: type: boolean responses: '200': description: Working container retrieved successfully. Returns ContainerView by default, or ContainerWithContentTypesView if includeContentType=true. content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Invalid container ID '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Working container not found '500': description: Internal server error /api/v1/containers/_publish: put: tags: - Containers summary: Publishes a container description: Makes a container live by publishing it. The container must exist and the user must have publish permissions. operationId: publishContainer parameters: - name: containerId in: query description: Container identifier to publish schema: type: string responses: '200': description: Container published successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Container ID is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks publish permissions '404': description: Container not found '500': description: Internal server error /api/v1/containers/delete/{containerId}/content/{contentletId}/uid/{uid}: delete: tags: - Containers summary: Removes content from a container description: Removes a specific contentlet from a container at a particular position. This affects the container's content layout and rendering. operationId: removeContentletFromContainer parameters: - name: containerId in: path description: Container identifier required: true schema: type: string - name: contentletId in: path description: Contentlet identifier required: true schema: type: string - name: order in: query description: Order position of the content schema: type: integer format: int64 - name: uid in: path description: Unique identifier for the content instance required: true schema: type: string responses: '200': description: Content removed successfully content: application/json: schema: type: string description: Confirmation string 'ok' '400': description: Bad request - Invalid parameters '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks required permissions '404': description: Container, content, or UID not found '500': description: Internal server error /api/v1/containers/_unarchive: put: tags: - Containers summary: Unarchives a container description: Unarchives the specified container, restoring it to active status. The user must have Edit permissions on the container. operationId: unarchiveContainer parameters: - name: containerId in: query description: Container identifier to unarchive schema: type: string responses: '200': description: Container unarchived successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Container ID is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks edit permissions '404': description: Container not found /api/v1/containers/_unpublish: put: tags: - Containers summary: Unpublishes a container description: Removes a container from live status by unpublishing it. The container must exist and the user must have unpublish permissions. operationId: unpublishContainer parameters: - name: containerId in: query description: Container identifier to unpublish schema: type: string responses: '200': description: Container unpublished successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntitySingleContainerView' '400': description: Bad request - Container ID is required '401': description: Unauthorized - User not authenticated '403': description: Forbidden - User lacks unpublish permissions '404': description: Container not found '500': description: Internal server error components: schemas: 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' Container: type: object properties: getiDate: type: string format: date-time type: type: string owner: type: string inode: type: string identifier: type: string source: type: string enum: - UNKNOWN - DB - FILE title: type: string friendlyName: type: string modDate: type: string format: date-time modUser: type: string sortOrder: type: integer format: int32 showOnMenu: type: boolean code: type: string maxContentlets: type: integer format: int32 useDiv: type: boolean preLoop: type: string postLoop: type: string notes: type: string hostName: type: string hostId: type: string variant: type: string archived: type: boolean versionType: type: string permissionId: type: string deleted: type: boolean working: type: boolean versionId: type: string live: type: boolean name: type: string locked: type: boolean permissionType: type: string idate: type: string format: date-time categoryId: type: string parents: type: array writeOnly: true items: type: object new: type: boolean ResponseEntityBooleanView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: type: boolean 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' FailedResultView: type: object properties: element: type: string errorMessage: type: string ContainerView: type: object properties: container: $ref: '#/components/schemas/Container' path: type: string BulkResultView: type: object properties: successCount: type: integer format: int64 skippedCount: type: integer format: int64 fails: type: array items: $ref: '#/components/schemas/FailedResultView' ResponseEntityContainerObjectMapView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: type: object additionalProperties: type: object 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' MessageEntity: type: object properties: message: type: string ResponseEntitySingleContainerView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: $ref: '#/components/schemas/ContainerView' 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' ResponseEntityContainerView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: type: array items: $ref: '#/components/schemas/Container' 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' ContainerStructure: type: object properties: id: type: string structureId: type: string containerInode: type: string containerId: type: string code: type: string contentTypeVar: type: string ResponseEntityPaginatedArrayListMapView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: type: array properties: totalResults: type: integer format: int64 query: type: string empty: type: boolean first: type: object additionalProperties: type: object last: type: object additionalProperties: type: object items: type: object additionalProperties: type: object 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' ContainerForm: required: - title type: object properties: identifier: type: string description: Identifier of the container. Required for updates, ignored on creation. title: type: string description: Title of the container friendlyName: type: string description: Description of the container (displayed as 'Description' in the UI). Also accepts 'description' as an alias field name in JSON. maxContentlets: type: integer description: Maximum number of contentlets this container can hold. Set to 0 for no limit. format: int32 code: type: string description: Velocity/code used to render the container's content. Used when maxContentlets is 0. notes: type: string description: Internal notes about this container (not displayed to end users) preLoop: type: string description: Velocity code executed before the content loop postLoop: type: string description: Velocity code executed after the content loop showOnMenu: type: boolean description: Whether this container should appear in navigation menus sortOrder: type: integer description: Sort order for display purposes format: int32 sortContentletsBy: type: string description: Field name used to sort contentlets within this container structureInode: type: string description: Inode of the content type (structure) associated with this container. This is a legacy field; prefer using containerStructures for multiple content type associations. containerStructures: type: array description: List of content type associations for this container. Each entry maps a content type to rendering code. The 'id' field is ignored on input and auto-generated server-side. Only 'structureId' and 'code' are required. items: $ref: '#/components/schemas/ContainerStructure' owner: type: string description: Owner user ID of the container hostId: type: string description: Identifier of the site (host) where this container should be created or moved to. If not provided, the container is assigned to the site resolved from the current HTTP request context. staticify: type: boolean description: Whether the container output should be staticified (cached as static HTML) useDiv: type: boolean description: Whether to wrap content in a div element dynamic: type: boolean description: Whether this container uses dynamic content type resolution description: Form used to create or update a Container in dotCMS ErrorEntity: type: object properties: errorCode: type: string message: type: string fieldName: type: string