dotCMS templates are built out of containers, which define display behaviors for different Content Types in the context of different page layouts. This document details the endpoints of a REST API for manipulating containers with create, read, update, and delete (CRUD) operations, utilizing and returning JSON objects.
+Containers can exist either as database entities or as file system entities — directories containing VTL files. The latter case offers advantages such as easy storage on remote repositories, synchronization through WebDav or command-line interface, or other similar conveniences. By the same measure, there are also some Container API calls that can only be performed on the database-entity type of Container.
+All examples use the dotCMS demo site as their target. Used on another host, the Authentication header must change accordingly: For Basic authorization, use base64 encoding of a username:password string; for more secure Bearer authorization, use an API token.
Retrieving a Container
+The endpoint offers several methods to retrieve containers, individually or collectively. Please note:
+-
+
- Containers located in the database must be requested by identifier. +
- Containers located in the file system must be referenced by path. +
To retrieve the working version of a container, use /working:
curl --location --request GET 'https://demo.dotcms.com/api/v1/containers/working?containerId=REPLACE_THIS_UUID' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+To retrieve the live version of a container, call /live:
curl --location --request GET 'https://demo.dotcms.com/api/v1/containers/live?containerId=/application/containers/system' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg==' \
+
+Finally, to retrieve all containers:
+curl --location --request GET 'https://demo.dotcms.com/api/v1/containers/' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+To adjust the displayed results, the Container API uses standard pagination parameters such as per_page, filter, etc.
A successful call returns containers as JSON objects, which may look, in part, like the following data:
+{
+ "entity": {
+ "archived": false,
+ "categoryId": "27d80ebe-c9f1-4dd9-8cae-f15e644df708",
+ "deleted": false,
+ "friendlyName": "TestContainer description",
+ "iDate": 1647630014297,
+ "idate": 1647630014297,
+ "identifier": "567416cee048a876d4c60172421832ba",
+ "inode": "27d80ebe-c9f1-4dd9-8cae-f15e644df708",
+ "live": false,
+ "locked": false,
+ "map": {
+ "deleted": false,
+ "friendlyName": "TestContainer description",
+ "hasLiveVersion": false,
+ "iDate": 1647630014297,
+ "identifier": "567416cee048a876d4c60172421832ba",
+ "inode": "27d80ebe-c9f1-4dd9-8cae-f15e644df708",
+ "live": false,
+ "locked": false,
+ "modDate": 1647630014309,
+ "modUser": "dotcms.org.1",
+ "modUserName": "Admin User",
+ "showOnMenu": false,
+ "sortOrder": 0,
+ "title": "TestContainer",
+ "type": "containers",
+ "working": true
+ }
+ ...
+ }
+}
+
+Adding a Container
+Adding a container by API call is only possible with a database-style container. A container that exists in the file system must instead be created by adding a folder containing the necessary VTL files within the application/containers folder, either manually or by one of the methods detailed at the top of the page.
To add a container, make a POST call with the Container as a JSON payload:
curl --location --request POST 'https://demo.dotcms.com/api/v1/containers' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg==' \
+--data-raw '{
+ "title":"TestContainer",
+ "friendlyName":"TestContainer description",
+ "maxContentlets":1,
+ "notes":"Notes",
+ "preLoop":"<h1>Some Title</h1>",
+ "postLoop":"<span>Some Footer</span>",
+ "containerStructures":[
+ {
+ "structureId":"webPageContent",
+ "code":"<div> $!{body} </div>"
+ },
+ {
+ "structureId":"DotAsset",
+ "code":" <img src ='\''./contentAsset/image/${ContentIdentifier}/asset'\'' />"
+ }
+ ]
+}'
+
+Updating a Container
+The call to update a container is similar to creating one; it only functioning with database containers, and it has a very similar structure. However, there are two key differences:
+-
+
- It uses the
PUTmethod instead ofPOST.
+ - It includes the container's identifier in the payload data. +
curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg==' \
+--data-raw '{
+ "identifier":"567416cee048a876d4c60172421832ba",
+ "title":"TestContainer",
+ "friendlyName":"TestContainer description",
+ "maxContentlets":1,
+ "notes":"Notes 1",
+ "preLoop":"preLoop xxxx",
+ "postLoop":"postLoop xxxx",
+ "containerStructures":[
+ {
+ "structureId":"webPageContent",
+ "code":" code xxxx"
+ },
+ {
+ "structureId":"DotAsset",
+ "code":" tags: $!{tags}"
+ }
+ ]
+}'
+
+Publishing or Unpublishing a Container
+Publishing or unpublishing a container are similar PUT operations, distinguished by the use of /_publish or /_unpublish. Both operations take either a path or an identifier.
Publishing:
+curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_publish?containerId=567416cee048a876d4c60172421832ba' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+Unpublishing:
+curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_unpublish?containerId=567416cee048a876d4c60172421832ba' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+Archiving or Unarchiving a Container
+Archiving and unarchiving works similarly to publishing or unpublishing. Note: Before archiving, containers should be unpublished.
+To archive:
+curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_archive?containerId=/application/containers/system' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+To unarchive an archived container:
+curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_unarchive?containerId=/application/containers/system' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+Deleting a Container
+Finally, you can use the call below to delete a container. Note: A container should be archived (see above) before deletion.
+curl --location --request DELETE 'https://demo.dotcms.com/api/v1/containers?containerId=567416cee048a876d4c60172421832ba' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='
+
+
+