Container API

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 dotCLI — or WebDav on older versions — 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 PUT method instead of POST.
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=='

Container API

Retrieving a Container#

Adding a Container#

Updating a Container#

Publishing or Unpublishing a Container#