Content Type API

Last Updated: Dec 9, 2022
documentation for the dotCMS Content Management System

You can use the dotCMS REST API to manage Content Types. Content Types can be created, updated, copied, and deleted via REST API. In addition, Content Type Fields and Content Type Field Variables can also be managed via REST API.

In the curl examples below, admin passwords are assumed to be admin, as on the demo site and starters prior to version 22.06. For versions 22.06 or later, this is no longer the default; now, admin passwords default to a random string generated on first startup and displayed in the server logs. This starter password can also be pre-configured through the DOT_INITIAL_ADMIN_PASSWORD environment variable.

Get All Content Types

Usage

GET /v1/contenttype/

Example

The following curl command retrieves all Content Types:

curl -v -u admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/contenttype/

Get a Specific Content Type

Usage

GET /v1/contenttype/id/{typeId}

Example

The following curl command retrieves a specific field by ID, and returns all the properties of the field:

curl -v -u admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/contenttype/id/4c441ada-944a-43af-a653-9bb4f3f0cb2b

Create a Content Type

Usage

POST /v1/contenttype

Note: The JSON object also needs to be defined - please see below.

Example

The following curl command creates a new Content Type, using the bodyCreate.json file, which includes all the properties required to create the new Content Type:

curl -v -u admin@dotcms.com:admin -XPOST http://localhost:8082/api/v1/contenttype -H "Content-Type: application/json" --data @bodyCreate.json

Payload

The command above passes a file called bodyCreate.json which contains the following new Content Type properties in order to create the specified Content Type. The contents of the bodyCreate.json file are shown below:

{
    "clazz": "com.dotcms.contenttype.model.type.ImmutableSimpleContentType", 
    "defaultType": false, 
    "name": "The Content Type 1", 
    "description": "THE DESCRIPTION", 
    "host": "48190c8c-42c4-46af-8d1a-0cd5db894797", 
    "owner": "dotcms.org.1", 
    "variable": "TheContentType1",
    "fixed": false, 
    "system": false, 
    "folder": "SYSTEM_FOLDER",
    "workflow":[
        "d61a59e1-a49c-46f2-a929-db2b4bfa88b2"
    ]
}

Note: The "workflow" property specifies the identifier of the Workflow to assign to the Content Type. If the "workflow" property is not supplied in the payload, the content type will be unassigned.

The json object properties of any new Content Type can be seen by examining the json view link when editing a Content Type.

Creating Content Types of Different Base Types: For examples of how to create a Content Type of other Base Content Types, please see the Create Content Types of each Base Type documentation.

Copy a Content Type

Usage

POST /v1/contenttype/{typeID}/_copy

Example

The following command creates a copy of the Content Type with the variable name exampleContentType:

curl -v -u admin@dotcms.com:admin -XPOST http://localhost:8082/api/v1/contenttype/exampleContentType/_copy -H "Content-Type: application/json" --data @ctCopy.json

Payload

The command above passes a file called ctCopy.json which contains from one to five properties; only "name" is required, while the others are optional:

{
    "name": "Copy of Example Content Type",
    "variable": "exampleContentType2",
    "folder": "SYSTEM_FOLDER",
    "host": "48190c8c-42c4-46af-8d1a-0cd5db894797",
    "icon": "text_snippet"
}

Update a Content Type

Usage

PUT /v1/contenttype/id/{typeId}

Note: The JSON object also needs to be defined - please see below.


Important

When updating a Content Type using the REST API, you must submit all fields for a Content Type each time you update it.

  • If you wish to update only a single field (while maintaining all other existing fields), you must first read all existing fields so you can include them when updating the Content Type.
  • Any fields which are not included when you update a Content Type via the REST API will be removed from that Content Type.

Example

The following command updates an existing Content Type (by ID), using the bodyUpdate.json file to define the json object required to update the Content Type's properties.

curl -v -u admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/contenttype/id/39fecdb0-46cc-40a9-a056-f2e1a80ea78c -H "Content-Type: application/json" --data @bodyUpdate.json

Payload

The command above passes a file called bodyUpdate.json which contains the new Content Type properties that will be used to Update the specified Content Type. The contents of the bodyUpdate.json file are shown below:

{
    "clazz": "com.dotcms.contenttype.model.type.ImmutableSimpleContentType", 
    "defaultType": false,
    "id": "39fecdb0-46cc-40a9-a056-f2e1a80ea78c",
    "name": "The Content Type 2",
    "description": "THE DESCRIPTION 2",
    "host": "48190c8c-42c4-46af-8d1a-0cd5db894797",
    "owner": "dotcms.org.1",
    "variable": "TheContentType1",
    "fixed": false,
    "system": false,
    "folder": "SYSTEM_FOLDER"
    "workflow":[
        "d61a59e1-a49c-46f2-a929-db2b4bfa88b2"
    ]
}

The json object properties of any Content Type can be seen by examining the json view link when editing a Content Type.

Add Default Actions to a Content Type

The Default Actions for any Content Type may be specified either when creating or updating a Content Type, by adding a `` value to the payload, in the following format:

    "systemActionMappings":{
        "NEW":"ceca71a0-deee-4999-bd47-b01baa1bcfc8"
    },

In the above example, the “NEW” specifies that this is the Default Workflow Action to apply to new content created without invoking a workflow (such as when uploading files via WebDAV), and the identifier is the ID of the Workflow Action to use for this Default Action.

The following operations can be specified in the systemActionMappings property:

OperationExecuted When Content Is
"NEW"Created for the first time
"EDIT"Saved/updated
"PUBLISH"Published
"UNPUBLISH"Unpublished
"ARCHIVE"Archived
"UNARCHIVE"Unarchived
"DELETE"Deleted
"DESTROY"Destroyed

The identifier may reference any Workflow Action which is available to the Content Type, in any Step of any Workflow Scheme which is assigned to the Content Type.

Example

The following command is the same command to update an existing Content Type (by ID) used in the example above:

curl -v -u admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/contenttype/id/39fecdb0-46cc-40a9-a056-f2e1a80ea78c -H "Content-Type: application/json" --data @bodyUpdate.json

Payload

To add or change the Default Actions for the Content Type, the only change required is to add the systemActionMappings property to the payload, as follows:

{
    "clazz": "com.dotcms.contenttype.model.type.ImmutableSimpleContentType", 
    "defaultType": false,
    "id": "39fecdb0-46cc-40a9-a056-f2e1a80ea78c",
    "name": "The Content Type 2",
    "description": "THE DESCRIPTION 2",
    "host": "48190c8c-42c4-46af-8d1a-0cd5db894797",
    "owner": "dotcms.org.1",
    "variable": "TheContentType1",
    "fixed": false,
    "system": false,
    "folder": "SYSTEM_FOLDER",
    "workflow":[
        "d61a59e1-a49c-46f2-a929-db2b4bfa88b2"
    ]
    "systemActionMappings":{
        "NEW":"ceca71a0-deee-4999-bd47-b01baa1bcfc8"
    }
}

Delete a Content Type

Usage

DELETE /v1/contenttype/id/{typeId}

Example

The following command deletes the field specified by identifier, from the specified Content Type (by identifier):

curl -v -u admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/contenttype/id/05c64f1d-2d39-4b93-95c4-99d72ebe869a

Quick Access from the Content Types Screen

You can quickly access the Content Type API from the dotCMS back-end via the API button on the Content Type editing screen:

  1. Select Types & Tags -> Content Types.
  2. Select a Content Type from the list.
  3. Click the API button next to the Content Type name.

The API button in the Content Types screen

A REST API call to the Content Type API will be executed for the selected Content Type, and the results will be displayed in a new browser tab:

The results of the API call, displayed in a new tab

On this page

×

We Dig Feedback

Selected excerpt:

×